إدارة أماكن تخزين جهات الاتصال

يمكن للتطبيقات السماح للمستخدمين بإنشاء جهات اتصال وتخزينها. يمكن عادةً حفظ جهات الاتصال هذه في مكانَين:

1. حساب على السحابة الإلكترونية: يمكنك حفظ جهات الاتصال في حساب مرتبط بأحد خدمات السحابة الإلكترونية (مثل Google Cloud) للسماح بمزامنة جهات الاتصال والاحتفاظ بنسخة احتياطية منها.
2. الحساب على الجهاز: يمكن تخزين جهات الاتصال على الجهاز.

يمكن للمستخدمين ضبط موقع التخزين المفضّل لديهم في إعدادات الجهاز. يُعرف هذا الموقع الجغرافي المفضّل باسم الحساب التلقائي، ويتم استخدامه عند إنشاء جهات الاتصال. ويجب أن تحترم التطبيقات هذا الخيار المفضّل. يشرح هذا المستند كيفية العمل مع مواقع تخزين مختلفة لجهات الاتصال، بما في ذلك حسابات السحابة الإلكترونية والحسابات المحلية، وتنفيذ أفضل الممارسات لإدارة الإعدادات المفضّلة للمستخدم. يشير الحساب على الجهاز إلى تخزين جهات الاتصال مباشرةً على الجهاز.

استرداد الحساب التلقائي

لتحديد الحساب التلقائي لجهات الاتصال الجديدة، استخدِم ContactsContract.RawContacts.DefaultAccount

اتصل بـ getDefaultAccountForNewContacts() للحصول على ContactsContrast.RawContacts.DefaultAccount.DefaultAccountAndState العنصر. يحتوي هذا العنصر على معلومات عن إعدادات الحساب التلقائية.

Kotlin

import ContactsContrast.RawContacts
import ContactsContrast.RawContacts.DefaultAccount
import ContactsContrast.RawContacts.DefaultAccount.DefaultAccountAndState

val defaultAccountAndState: DefaultAccountAndState =
  DefaultAccount.getDefaultAccountForNewContacts(
      getContentResolver()
  )

Java

import ContactsContrast.RawContacts;
import ContactsContrast.RawContacts.DefaultAccount;
import ContactsContrast.RawContacts.DefaultAccount.DefaultAccountAndState;

DefaultAccountAndState defaultAccountAndState =
  DefaultAccount.getDefaultAccountForNewContacts(
    getContentResolver()
  );

يحتوي عنصر DefaultAccountAndState على ما يلي:

• الحالة: تشير إلى ما إذا تم ضبط حساب تلقائي، وإذا كان الأمر كذلك، تشير إلى فئة هذا الحساب (سحابة أو جهاز أو شريحة SIM).
• الحساب: يوفّر تفاصيل الحساب المحدّدة (الاسم والنوع) إذا كانت الحالة هي DEFAULT_ACCOUNT_STATE_CLOUD or DEFAULT_ACCOUNT_STATE_SIM. وسيكون القيمة خالية للولايات الأخرى، بما في ذلك DEFAULT_ACCOUNT_STATE_LOCAL.

ملاحظة: بالنسبة إلى الحساب على الجهاز (DEFAULT_ACCOUNT_STATE_LOCAL)، يمكنك استرداد معلومات الحساب باستخدام RawContacts.getLocalAccountName() و RawContacts.getLocalAccountType().

في ما يلي مثال على كيفية تحليل العنصر DefaultAccountAndState:

Kotlin

// Retrieves the state of default account.
val defaultAccountState = defaultAccountAndState.state
var defaultAccountName: String? = null
var defaultAccountType: String? = null

when (defaultAccountState) {
    // Default account is set to a cloud or a SIM account.
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_CLOUD,
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_SIM -> {
        defaultAccountName = defaultAccountAndState.account?.name
        defaultAccountType = defaultAccountAndState.account?.type
    }
    // Default account is set to the local account on the device.
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_LOCAL -> {
        defaultAccountName = RawContacts.getLocalAccountType()
        defaultAccountType = RawContacts.getLocalAccountName()
    }
    // Default account is not set.
    DefaultAccountState.DEFAULT_ACCOUNT_STATE_NOT_SET -> {
    }
}

Java

// Retrieves the state of default account.
var defaultAccountState = defaultAccountAndState.getState();
String defaultAccountName = null;
String defaultAccountType = null;

switch (defaultAccountState) {
  // Default account is set to a cloud or a SIM account.
  case DefaultAccountState.DEFAULT_ACCOUNT_STATE_CLOUD:
  case DefaultAccountState.DEFAULT_ACCOUNT_STATE_SIM:
    defaultAccountName = defaultAccountAndState.getAccount().name;
    defaultAccountType = defaultAccountAndState.getAccount().type;
    break;
  // Default account is set to the local account on the device.
  case  DefaultAccountState.DEFAULT_ACCOUNT_STATE_LOCAL:
    defaultAccountName = RawContacts.getLocalAccountType();
    defaultAccountType = RawContacts.getLocalAccountName();
    break;

  // Default account is not set.
  case DefaultAccountState.DEFAULT_ACCOUNT_STATE_NOT_SET:
    break;
}

إنشاء جهات اتصال بدون تحديد حساب

في حال ضبط الحساب التلقائي، لا يحتاج تطبيقك عادةً إلى تحديد حساب بشكل صريح عند إنشاء جهات اتصال. يحفظ النظام تلقائيًا جهة الاتصال الجديدة في الحساب التلقائي. في ما يلي كيفية إنشاء جهة اتصال بدون تحديد حساب.

أنشئ ArrayList جديدًا من ContentProviderOperation عنصر. تحتوي هذه القائمة على العمليات التي يتم من خلالها إدراج جهة الاتصال الأوّلية والبيانات المرتبطة بها.

Kotlin

val ops = ArrayList<ContentProviderOperation>()

Java

ArrayList<ContentProviderOperation> ops =
        new ArrayList<ContentProviderOperation>();

أنشئ ContentProviderOperation جديدًا لإدراج جهة الاتصال الأوّلية. بما أنّك لن تحدّد حسابًا، لن تحتاج إلى تضمين ACCOUNT_TYPE وACCOUNT_NAME.

Kotlin

val op = ContentProviderOperation.newInsert(
    ContactsContract.RawContacts.CONTENT_URI
)
ops.add(op.build())

Java

ContentProviderOperation.Builder op =
    ContentProviderOperation.newInsert(
        ContactsContract.RawContacts.CONTENT_URI
    );
ops.add(op.build());

أضِف عناصر ContentProviderOperation أخرى إلى قائمة العمليات لتضمين حقول جهات الاتصال (مثل الاسم ورقم الهاتف والبريد الإلكتروني). بعد ذلك، نفِّذ عملية المعالجة المُجمَّعة لإنشاء جهة الاتصال.

Kotlin

try {
    getContentResolver().applyBatch(
        ContactsContract.AUTHORITY, ops
    )
} catch (e: Exception) {
    // Handle exceptions
}

Java

try {
    getContentResolver().applyBatch(
        ContactsContract.AUTHORITY, ops
    );
} catch (Exception e) {
    // Handle exceptions
}

إنشاء جهات اتصال في حساب على السحابة الإلكترونية

لإنشاء جهة اتصال في حساب على السحابة الإلكترونية، أدرِج صف جهة الاتصال الأوّلي في جدول ContactsContract.RawContacts وحدِّد حساب السحابة الإلكترونية. وإليك كيفية ذلك:

أنشئ ArrayList جديدًا من ContentProviderOperation عنصر.

Kotlin

val ops = ArrayList<ContentProviderOperation>()

Java

ArrayList<ContentProviderOperation> ops =
    new ArrayList<ContentProviderOperation>();

أنشئ ContentProviderOperation جديدًا لإدراج جهة الاتصال الأوّلية. استخدِم الطريقة withValue() لتحديد نوع الحساب واسم حساب سحابة المعلومات المحدّد.

Kotlin

val op = ContentProviderOperation.newInsert(
    ContactsContract.RawContacts.CONTENT_URI
)
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_TYPE,
        selectedAccount.type
    )
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_NAME,
        selectedAccount.name
    )
ops.add(op.build())

Java

ContentProviderOperation.Builder op =
    ContentProviderOperation.newInsert(
        ContactsContract.RawContacts.CONTENT_URI
    )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_TYPE,
            selectedAccount.getType()
        )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_NAME,
            selectedAccount.getName()
        );
ops.add(op.build());

أضِف عناصر ContentProviderOperation أخرى إلى قائمة العمليات لتضمين حقول جهات الاتصال وتنفيذ عملية الدُفعة لإنشاء جهة الاتصال.

إنشاء جهات اتصال في الحساب على الجهاز

تحذير: عند ضبط الحساب التلقائي على حساب على السحابة الإلكترونية (DEFAULT_ACCOUNT_STATE_CLOUD)، يجب إنشاء جهات الاتصال في حساب السحابة الإلكترونية فقط. تجنَّب إنشاء جهات اتصال في الحساب على الجهاز أو أي حسابات على شريحة SIM في هذا السيناريو.

لإنشاء جهة اتصال في الحساب على الجهاز، أدخِل صفًا جديدًا لجهة اتصال غير معالجة في جدول ContactsContract.RawContacts وحدِّد معلومات الحساب للحساب على الجهاز:

أنشئ ArrayList جديدًا من ContentProviderOperation عنصر.

Kotlin

val ops = ArrayList<ContentProviderOperation>()

Java

ArrayList<ContentProviderOperation> ops =
    new ArrayList<ContentProviderOperation>();

أنشئ ContentProviderOperation جديدًا لإدراج جهة الاتصال الأوّلية. استخدِم ContactsContract.RawContacts.getLocalAccountName() و ContactsContract.RawContacts.getLocalAccountType() لتحديد حساب معلومات الحساب المحلي.

Kotlin

val op = ContentProviderOperation.newInsert(
    ContactsContract.RawContacts.CONTENT_URI
)
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_TYPE,
        ContactsContract.RawContacts.getLocalAccountType()
    )
    .withValue(
        ContactsContract.RawContacts.ACCOUNT_NAME,
        ContactsContract.RawContacts.getLocalAccountName()
    )
ops.add(op.build())

Java

ContentProviderOperation.Builder op =
    ContentProviderOperation.newInsert(
        ContactsContract.RawContacts.CONTENT_URI
    )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_TYPE,
            ContactsContract.RawContacts.getLocalAccountType()
        )
        .withValue(
            ContactsContract.RawContacts.ACCOUNT_NAME,
            ContactsContract.RawContacts.getLocalAccountName()
        );
ops.add(op.build());

أضِف عناصر ContentProviderOperation أخرى إلى قائمة العمليات لتضمين حقول جهات الاتصال، ثم نفِّذ عمليات الدُفعات لإنشاء جهة الاتصال.