管理聯絡人儲存位置

應用程式可以允許使用者建立及儲存聯絡人。這些聯絡人通常可儲存在兩個位置：

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;
}

不指定帳戶建立聯絡人

如果已設定預設帳戶，應用程式在建立聯絡人時，通常不需要明確指定帳戶。系統會自動將新聯絡人儲存至預設帳戶。以下說明如何在不指定帳戶的情況下建立聯絡人。

建立新的 ContentProviderOperation 物件 ArrayList。這個清單會保留用於插入原始聯絡人及其相關資料的作業。

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 資料表，並指定雲端帳戶。方法如下：

建立新的 ContentProviderOperation 物件 ArrayList。

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 資料表中插入新的原始聯絡人資料列，並指定本機帳戶的帳戶資訊：

建立新的 ContentProviderOperation 物件 ArrayList。

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 物件新增至作業清單，以便納入聯絡人欄位，然後執行批次作業來建立聯絡人。