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

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

  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.

في ما يلي مثال على كيفية تحليل العنصر 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 أخرى إلى قائمة العمليات لتضمين حقول جهات الاتصال وتنفيذ العملية المجمّعة لإنشاء جهة الاتصال.

إنشاء جهات اتصال في الحساب المحلي

لإنشاء جهة اتصال في الحساب المحلي، أدرِج صف جهة اتصال أولية جديدًا في جدول 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 أخرى إلى قائمة العمليات لتضمين حقول جهات الاتصال، ونفِّذ العمليات المجمّعة لإنشاء جهة الاتصال.