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

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

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