管理联系人存储位置

应用可能会允许用户创建和存储联系人。这些联系人通常可以保存在两个位置：

  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），此值为 null。

以下示例展示了如何解析 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 对象添加到 ops 列表，以包含联系人字段并执行批量操作来创建联系人。

在本地账号中创建联系人

如需在本地账号中创建联系人，请在 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 对象添加到 ops 列表以包含联系人字段，然后执行批量操作以创建联系人。