قد تسمح التطبيقات للمستخدمين بإنشاء جهات اتصال وتخزينها. يمكن عادةً حفظ جهات الاتصال هذه في مكانَين:
- حساب على السحابة الإلكترونية: يمكنك حفظ جهات الاتصال في حساب مرتبط بخدمة سحابية (مثل Google Cloud) للسماح بمزامنة جهات الاتصال ونسخها احتياطيًا.
- الحساب المحلي: يمكن تخزين جهات الاتصال محليًا على الجهاز.
يمكن للمستخدمين ضبط موقع التخزين المفضّل لديهم في إعدادات الجهاز. يُعرف هذا الموقع الجغرافي المفضّل باسم الحساب التلقائي، ويتم استخدامه عند إنشاء جهات الاتصال. ويجب أن تحترم التطبيقات هذا الخيار. يوضّح هذا المستند كيفية استخدام مواقع تخزين جهات الاتصال المختلفة، بما في ذلك الحسابات على السحابة الإلكترونية والحسابات المحلية، وكيفية تطبيق أفضل الممارسات لإدارة إعدادات المستخدم المفضّلة. يشير الحساب المحلي إلى تخزين جهات الاتصال مباشرةً على الجهاز.
استرداد الحساب التلقائي
لتحديد الحساب التلقائي لجهات الاتصال الجديدة، استخدِم
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
أخرى إلى قائمة العمليات لتضمين حقول جهات الاتصال، ونفِّذ العمليات المجمّعة لإنشاء جهة الاتصال.