联系人提供程序

联系人提供程序是一个强大而又灵活的 Android 组件，用于管理设备上联系人相关数据的中央存储区。联系人提供程序是您在设备的联系人应用中看到的数据源，您也可以在自己的应用中访问其数据，并在设备与在线服务之间传输数据。提供程序包含各种各样的数据源，并尝试为每个人管理尽可能多的数据，因此其组织很复杂。为此，该提供程序的 API 包含丰富的协定类和接口，以便检索和修改数据。

本指南介绍了以下内容：

  • 基本提供程序结构。
  • 如何从提供程序检索数据。
  • 如何修改提供程序中的数据。
  • 如何编写用于将数据从服务器同步到联系人提供程序的同步适配器。

本指南假定您了解 Android 内容提供程序的基础知识。如需详细了解 Android 内容提供程序，请阅读 内容提供程序基础知识指南。

联系人提供程序结构

联系人提供程序是 Android 内容提供程序的一个组件。它保留了三种类型的联系人数据，每种数据都对应提供程序提供的一个表，如图 1 所示：

图 1. 联系人提供程序表结构。

这三个表通常以其协定类的名称命名。这些类定义表所用内容 URI、列名称及列值的常量：

ContactsContract.Contacts 表格
表示不同联系人的行，基于聚合的原始联系人行。
ContactsContract.RawContacts 表格
包含联系人数据摘要的行，针对特定用户账号和类型。
ContactsContract.Data 表格
包含原始联系人详细信息（例如电子邮件地址或电话号码）的行。

由 ContactsContract 中的协定类表示的其他表是辅助表，联系人提供程序使用它们来管理其操作或支持设备的联系人或电话应用中的特定功能。

原始联系人

原始联系人表示来自某一账号类型和账号名称的某一联系人数据。由于联系人提供程序允许将多项在线服务作为某个联系人的数据来源，因此该联系人提供程序允许同一联系人对应多个原始联系人。借助多个原始联系人，用户还可以合并同一账号类型中来自多个账号的用户数据。

原始联系人的大部分数据并非存储在 ContactsContract.RawContacts 表内，而是存储在 ContactsContract.Data 表中的一行或多行内。每个数据行都有一个 Data.RAW_CONTACT_ID 列，该列包含其父级 ContactsContract.RawContacts 行的 RawContacts._ID 值。

重要的原始联系人列

表 1 列出了 ContactsContract.RawContacts 表中的重要列。请阅读表后的说明：

表 1. 重要的原始联系人列。

列名称 使用 备注
ACCOUNT_NAME 作为该原始联系人的来源账号类型的账号名称。 例如，Google 账号的账号名称是设备所有者的某个 Gmail 地址。如需了解详情，请参阅“ACCOUNT_TYPE”的下一个条目。 此名称的格式专用于其账号类型。它不一定是电子邮件地址。
ACCOUNT_TYPE 作为该原始联系人来源的账号类型。例如，Google 账号的账号类型为 com.google。请务必使用您所拥有或控制的域的域标识符限定您的账号类型。这可以确保您的账号类型具有唯一性。 提供联系人数据的账号类型通常具有关联的同步适配器，用于与联系人提供程序进行同步。
DELETED 原始联系人的“已删除”标志。 借助此标志，联系人提供程序可在内部保留该行，直至同步适配器依次从服务器、存储区中删除该行。

备注

以下是关于 ContactsContract.RawContacts 表的重要说明：

  • 原始联系人的姓名并非存储在 ContactsContract.RawContacts 的行中，而是存储在 ContactsContract.Data 表的 ContactsContract.CommonDataKinds.StructuredName 行中。在 ContactsContract.Data 表中，原始联系人只有一个该类型的行。
  • 注意：要在原始联系人行中使用您自己的账号数据，必须先向 AccountManager 注册该账号。为此，请提示用户将账号类型及其账号名称添加到账号列表中。否则，联系人提供程序将自动删除您的原始联系人行。

    例如，如果您想让应用为域名为 com.example.dataservice、基于网络的服务保留联系人数据，并且该服务的用户账号是 becky.sharp@dataservice.example.com，则用户必须先添加账号“类型”(com.example.dataservice) 和账号“名称”(becky.smart@dataservice.example.com)，这样您的应用才能添加原始联系人行。 您可以在文档中向用户解释此要求，也可提示用户添加类型和名称，或者同时采用这两种措施。下一部分将为您更详细地介绍账号类型和账号名称。

原始联系人数据来源

为理解原始联系人的工作方式，假设有一个用户“Emily Dickinson”，她的设备上定义了以下三个用户账号：

  • emily.dickinson@gmail.com
  • emilyd@gmail.com
  • Twitter 账号“belle_of_amherst”

该用户已在“账号”设置中为这三个账号启用了同步通讯录。

假设 Emily Dickinson 打开一个浏览器窗口，以 emily.dickinson@gmail.com 身份登录 Gmail，打开“通讯录”，并添加“Thomas Higginson”。后来，她以 emilyd@gmail.com 身份登录 Gmail，并向“Thomas Higginson”发送一封电子邮件，此操作会自动将他添加为联系人。她还在 Twitter 上关注了“colonel_tom”（Thomas Higginson 的 Twitter ID）。

以上操作的结果是，联系人提供程序会创建以下三个原始联系人：

  1. 第一个原始联系人对应“Thomas Higginson”，关联账号 emily.dickinson@gmail.com。 用户账号类型为 Google。
  2. 第二个原始联系人对应“Thomas Higginson”，关联账号 emilyd@gmail.com。 用户账号类型也是 Google。由于添加的联系人对应的用户账号不同，因此尽管名称与前一名称完全相同，该联系人也只能作为第二个原始联系人。
  3. 第三个原始联系人对应“Thomas Higginson”，关联账号“belle_of_amherst”。用户账号类型为 Twitter。

数据

如前所述，原始联系人的数据存储在一个 ContactsContract.Data 行中，该行链接到原始联系人的 _ID 值。基于此，一位原始联系人便可拥有多个数据类型相同的实例，如电子邮件地址或电话号码。例如，如果对应 emilyd@gmail.com 的“Thomas Higginson”（关联 Google 账号 emilyd@gmail.com 的 Thomas Higginson 的原始联系人行）的住宅电子邮件地址为 thigg@gmail.com，办公电子邮件地址为 thomas.higginson@gmail.com，则联系人提供程序会存储这两个电子邮件地址行，并将二者链接到原始联系人。

请注意，此表中存储不同类型的数据。显示名称、电话号码、电子邮件地址、邮政地址、照片和网站详细信息行都可以在 ContactsContract.Data 表中找到。为便于管理这些数据，ContactsContract.Data 表为某些列使用描述性名称，为其他列使用通用名称。对于使用描述性名称的列而言，其内容具有相同的含义，且与行中数据的类型无关；而对于使用通用名称的列而言，其内容的含义会因数据类型而异。

描述性列名称

以下是一些描述性列名称的示例：

RAW_CONTACT_ID
该数据对应的原始联系人 _ID 列的值。
MIMETYPE
该行中存储的数据类型，以自定义 MIME 类型表示。联系人提供程序使用在 ContactsContract.CommonDataKinds 子类中定义的 MIME 类型。这些 MIME 类型为开源类型，可供与联系人提供程序协作的任何应用或同步适配器使用。
IS_PRIMARY
如果原始联系人可拥有多个此类型的数据行，则 IS_PRIMARY 列会标记包含该类型主要数据的数据行。例如，如果用户长按某个联系人的电话号码，并选择设为默认，则包含该号码的 ContactsContract.Data 行会将其 IS_PRIMARY 列设置为非零值。

通用列名称

有 15 个通用列命名为 DATA1 至 DATA15，可普遍适用；还有四个通用列命名为 SYNC1 至 SYNC4，只应由同步适配器使用。无论行包含何种类型的数据，通用列名称常量始终有效。

DATA1 列已编入索引。联系人提供程序会预测查询次数最多的目标数据，并且总是会用此列存储该数据。例如，在电子邮件行中，此列包含实际的电子邮件地址。

按照惯例，系统会预留 DATA15 列，用于存储照片缩略图等二进制大型对象 (BLOB) 数据。

类型专用列名称

为便于处理特定类型行的列，联系人提供程序还提供了在 ContactsContract.CommonDataKinds 子类中定义的类型专用列名称常量。这些常量只是为同一列名称提供不同的常量名称，这有助于您访问特定类型行中的数据。

例如，ContactsContract.CommonDataKinds.Email 类为 ContactsContract.Data 行定义类型专用列名称常量，该行的 MIME 类型为 Email.CONTENT_ITEM_TYPE。该类包含电子邮件地址列的常量 ADDRESS。ADDRESS 的实际值为“data1”，与列的通用名称相同。

注意：请勿使用具有提供程序某个预定义 MIME 类型的行向 ContactsContract.Data 表中添加您自己的自定义数据。否则您可能会丢失数据，或导致提供程序发生故障。例如，不应添加 MIME 类型 Email.CONTENT_ITEM_TYPE 且在 DATA1 列中包含用户名而不是电子邮件地址的行。如果您为该行使用自定义的 MIME 类型，则可以随意定义您自己的类型专用列名称，并随心所欲地使用这些列。

图 2 显示的是描述性列和数据列在 ContactsContract.Data 行中的显示情况，以及类型专用列名称“覆盖”通用列名称的情况

类型专用列名称如何映射到通用列名称

图 2. 类型专用列名称和通用列名称。

类型专用列名称类

表 2 列出了最常用的类型专用列名称类：

表 2. 类型专用列名称类

映射类 数据类型 备注
ContactsContract.CommonDataKinds.StructuredName 与该数据行关联的原始联系人的姓名数据。 一位原始联系人只有其中一行。
ContactsContract.CommonDataKinds.Photo 与该数据行关联的原始联系人的主要照片。 一位原始联系人只有其中一行。
ContactsContract.CommonDataKinds.Email 与该数据行关联的原始联系人的电子邮件地址。 一位原始联系人可有多个电子邮件地址。
ContactsContract.CommonDataKinds.StructuredPostal 与该数据行关联的原始联系人的邮政地址。 一位原始联系人可有多个邮政地址。
ContactsContract.CommonDataKinds.GroupMembership 将原始联系人链接到联系人提供程序内某个组的标识符。 组是账号类型和账号名称的一项可选功能。联系人群组部分对其进行了更详细的说明。

通讯录

联系人提供程序会将所有账号类型和账号名称的原始联系人行进行合并，从而形成联系人。这有助于显示和修改用户针对某一联系人收集的所有数据。联系人提供程序可管理新联系人行的创建，以及原始联系人与现有联系人行的合并。系统不允许应用或同步适配器添加联系人，并且联系人行中的某些列为只读列。

注意：如果您尝试使用 insert() 将联系人添加到联系人提供程序，会发生 UnsupportedOperationException 异常。如果您尝试更新列表中列为“只读”的列，则更新会被忽略。

如果新增的原始联系人与现有联系人均不匹配，则联系人提供程序会相应地创建新联系人。如果某个现有原始联系人的数据发生变化，不再匹配其之前关联的联系人，则提供程序也会执行此操作。如果应用或同步适配器创建的新原始联系人确实与某位现有联系人匹配，则系统会将二者合并。

联系人提供程序会利用 Contacts 表内联系人行的 _ID 列，将联系人行链接至其原始联系人行。原始联系人表 ContactsContract.RawContacts 的 CONTACT_ID 列包含与每个原始联系人行相关联的联系人行的 _ID 值。

ContactsContract.Contacts 表还包含 LOOKUP_KEY 列，该列是指向联系人行的“永久”链接。由于联系人提供程序会自动维护联系人，因此可能会在合并或同步时相应地更改联系人行的 _ID 值。即使出现这种情况，合并了联系人 LOOKUP_KEY 的内容 URI CONTENT_LOOKUP_URI 仍将指向联系人行，这样，您就能使用 LOOKUP_KEY 保持指向“收藏”联系人的链接，以及执行其他操作。该列具有其自己的格式，与 _ID 列的格式无关。

图 3 展示三个主表的相互关系。

联系人提供程序主表

图 3. 联系人表、原始联系人表与详细信息表之间的关系。

注意 ：如果您将应用发布到 Google Play 商店，或者如果应用所在设备运行 Android 10（API 级别 29）或更高版本，请记住，一组有限的联系人数据字段和方法已过时。

在上述条件下，系统会定期清除写入这些数据字段的任何值：

用于设置上述数据字段的 API 也已过时：

此外，以下字段不再返回常用联系人。请注意，仅当联系人属于特定的数据类型时，其中一些字段才会影响联系人的排名。

如果您的应用访问或更新这些字段或 API，请使用替代方法。例如，您可以使用私有内容提供程序或存储在应用或后端系统中的其他数据来实现某些用例。

如要验证应用的功能不受此更改的影响，您可以手动清除这些数据字段。为此，请在搭载 Android 4.1（API 级别 16）或更高版本的设备上运行以下 ADB 命令： 

adb shell content delete \
--uri content://com.android.contacts/contacts/delete_usage

来自同步适配器的数据

虽然用户会直接将联系人数据输入到设备中，但数据也会通过同步适配器从网络服务流入联系人提供程序，这些同步适配器可自动在设备和服务之间传输数据。同步适配器在系统的控制下在后台运行，并会调用 ContentResolver 方法来管理数据。

在 Android 中，与同步适配器协作的网络服务由账号类型进行标识。 每个同步适配器都与一个账号类型协作，但它可以支持该类型的多个账号名称。原始联系人数据来源部分对账号类型和账号名称做了简要描述。以下定义提供了更多详细信息，并描述了账号类型及账号名称与同步适配器及服务之间的关系。

账号类型
表示用户在其中存储数据的服务。在大多数情况下，用户必须向服务进行身份验证。例如，Google 通讯录是一个以代码 google.com 标识的账号类型。此值对应于 AccountManager 使用的账号类型。
账号名称
表示某个账号类型的特定账号或登录名。Google 通讯录账号与 Google 账号相同，都是以电子邮件地址作为账号名称。 其他服务可能使用一个单词的用户名或数字 ID。

账号类型不必具有唯一性。用户可以配置多个 Google 通讯录账号，并将其数据下载到联系人提供程序；如果用户为个人账号名称和工作账号名称分别设置了一组联系人，则可能会发生此情况。账号名称通常具有唯一性。它们共同标识联系人提供程序与外部服务之间的具体数据流。

如果您想将服务的数据传送至联系人提供程序，则需编写您自己的同步适配器。联系人提供程序同步适配器部分对此做了更详尽的描述。

图 4 展示了联系人提供程序如何融入联系人数据流。在标记为“sync adapters”（同步适配器）的方框中，每个适配器都以其账号类型命名。

联系人数据流

图 4. 联系人提供程序数据流。

所需权限

如要访问联系人提供程序，应用必须请求以下权限：

对一个或多个表的读取权限
READ_CONTACTS，在 AndroidManifest.xml 中指定，使用 <uses-permission> 元素作为 <uses-permission android:name="android.permission.READ_CONTACTS">。
对一个或多个表的写入权限
WRITE_CONTACTS，在 AndroidManifest.xml 中指定，并且 <uses-permission> 元素为 <uses-permission android:name="android.permission.WRITE_CONTACTS">。

这些权限不适用于用户个人资料数据。如需了解用户个人资料及其所需权限的详细介绍，请参阅下面的用户个人资料部分。

请谨记，用户的联系人数据属于个人敏感数据。用户担心他们的隐私，因此不希望应用收集有关他们自己或其联系人的数据。 如果应用无法提供明确的理由以使用权限访问用户联系人数据，则用户可能会对其做出差评或干脆拒绝安装。

用户个人资料

ContactsContract.Contacts 表有一行包含设备用户的个人资料数据。这些数据描述设备的 user，而非用户的其中一位联系人。该个人资料联系人行会链接到某个原始联系人行，以便所有系统使用个人资料。 每个个人资料原始联系人行可拥有多个数据行。ContactsContract.Profile 类中提供了用于访问用户个人资料的常量。

访问用户个人资料需要特殊权限。除了进行读取和写入所需的 READ_CONTACTS 和 WRITE_CONTACTS 权限外，如果想访问用户个人资料，还分别需要 android.Manifest.permission#READ_PROFILE 和 android.Manifest.permission#WRITE_PROFILE 权限进行读取和写入访问。

请记住，您应将用户的个人资料视为敏感数据。借助 android.Manifest.permission#READ_PROFILE 权限，您可以访问设备用户的个人可识别数据。请务必在应用说明中告知用户您需要用户个人资料访问权限的原因。

如需检索包含用户个人资料的联系人行，请调用 ContentResolver.query()。将内容 URI 设置为 CONTENT_URI，并且不要提供任何选择条件。您还可以使用此内容 URI 作为检索原始联系人或个人资料数据的基础 URI。例如，以下代码段用于检索个人资料的数据：

Kotlin

// Sets the columns to retrieve for the user profile
projection = arrayOf(
        ContactsContract.Profile._ID,
        ContactsContract.Profile.DISPLAY_NAME_PRIMARY,
        ContactsContract.Profile.LOOKUP_KEY,
        ContactsContract.Profile.PHOTO_THUMBNAIL_URI
)

// Retrieves the profile from the Contacts Provider
profileCursor = contentResolver.query(
        ContactsContract.Profile.CONTENT_URI,
        projection,
        null,
        null,
        null
)

Java

// Sets the columns to retrieve for the user profile
projection = new String[]
    {
        Profile._ID,
        Profile.DISPLAY_NAME_PRIMARY,
        Profile.LOOKUP_KEY,
        Profile.PHOTO_THUMBNAIL_URI
    };

// Retrieves the profile from the Contacts Provider
profileCursor =
        getContentResolver().query(
                Profile.CONTENT_URI,
                projection ,
                null,
                null,
                null);

注意：如果您要检索多个联系人行并想要确定其中一个是否为用户个人资料，请测试该行的 IS_USER_PROFILE 列。如果该联系人是用户个人资料，则此列设为“1”。

联系人提供程序元数据

联系人提供程序会对追踪存储区内联系人数据状态的数据进行管理。这类元数据与存储区有关且存储在各处，其中包括原始联系人表行、数据表行和联系人表行、ContactsContract.Settings 表以及 ContactsContract.SyncState 表。下表显示了这三部分元数据的效果：

表 3. 联系人提供程序中的元数据

表格 Column 值 含义
ContactsContract.RawContacts DIRTY “0”：自上次同步以来未发生变化。 标记设备上因发生变化而需同步回服务器的原始联系人。当 Android 应用更新行时，联系人提供程序会自动设置该值。

修改原始联系人表或数据表的同步适配器应始终向其使用的内容 URI 追加字符串 CALLER_IS_SYNCADAPTER。这可以防止提供程序将行标记为已更新。 否则，即使服务器是修改的来源，同步适配器修改仍显示为本地修改，并会发送到服务器。

“1”：自上次同步以来发生了变化，需要同步回服务器。
ContactsContract.RawContacts VERSION 此行的版本号。 每当行或其相关数据发生变化时，联系人提供程序都会自动增加此值。
ContactsContract.Data DATA_VERSION 此行的版本号。 每当数据行发生变化时，联系人提供程序都会自动增加此值。
ContactsContract.RawContacts SOURCE_ID 一个字符串值，用于在创建此原始联系人的账号中对该联系人进行唯一标识。 当同步适配器创建新的原始联系人时，应将此列设置为该原始联系人在服务器中的唯一 ID。当 Android 应用创建新的原始联系人时，应将此列留空。这会向同步适配器表明，它应在服务器上创建新的原始联系人，并获取 SOURCE_ID 的值。

具体地讲，对于每个账号类型，该源 ID 都必须是唯一的，并且应在所有同步中保持稳定：

  • 唯一：账号的每个原始联系人都必须有自己的源 ID。如果您不强制执行此要求，会在联系人应用中引发问题。 请注意，账号类型相同的两个原始联系人可以具有相同的源 ID。例如，账号 emily.dickinson@gmail.com 的原始联系人“Thomas Higginson”与账号 emilyd@gmail.com 的原始联系人“Thomas Higginson”具有相同的来源 ID。
  • 稳定：源 ID 是原始联系人在线服务数据的永久性部分。例如，如果用户从“应用”设置中清除存储的联系人数据并重新同步，则恢复的原始联系人的源 ID 应与先前相同。如果您不强制执行此要求，快捷方式将停止工作。
ContactsContract.Groups GROUP_VISIBLE “0”：此组中的联系人在 Android 应用界面中不应处于可见状态。 此列用于兼容允许用户隐藏特定组内联系人的服务器。
“1”：系统允许此组中的联系人在应用界面中处于可见状态。
ContactsContract.Settings UNGROUPED_VISIBLE “0”：对于此账号和账号类型，未归入组的联系人在 Android 应用界面中处于不可见状态。 默认情况下，如果联系人的所有原始联系人均未归入组，则其将处于不可见状态（通过 ContactsContract.Data 表中的一个或多个 ContactsContract.CommonDataKinds.GroupMembership 行指示原始联系人的组成员身份）。 通过在 ContactsContract.Settings 表行中为账号类型和账号设置此标志，您可以强制显示未分组的联系人。 此标志的一个用途是显示不使用组的服务器的联系人。
“1”：对于此账号和账号类型，未归入组的联系人在应用界面中处于可见状态。
ContactsContract.SyncState （所有列） 此表用于存储同步适配器的元数据。 利用此表，您可以持续在设备中存储同步状态及其他与同步相关的数据。

联系人提供程序访问

本部分介绍了访问联系人提供程序中数据的准则，重点介绍以下内容：

  • 实体查询。
  • 批量修改。
  • 通过 intent 执行检索和修改。
  • 数据完整性。

联系人提供程序同步适配器部分也详细介绍了如何通过同步适配器进行修改。

查询实体

由于联系人提供程序表是以层次结构的形式组织的，因此检索某一行以及与该行链接的所有“子”行通常很有用。例如，如需显示某个人的所有信息，您可能需要检索单个 ContactsContract.Contacts 行的所有 ContactsContract.RawContacts 行，或者检索单个 ContactsContract.RawContacts 行的所有 ContactsContract.CommonDataKinds.Email 行。为方便起见，联系人提供程序提供了实体结构，其作用类似于表之间的数据库联接。

实体类似于一个表，该表由父表及其子表中的选定列组成。 查询实体时，您需根据实体中的可用列提供投影和搜索条件。结果会得到一个 Cursor，检索的每个子表行在其中都有一行与之对应。例如，如果您在 ContactsContract.Contacts.Entity 中查询某个联系人姓名，以及使用该姓名的所有原始联系人的所有 ContactsContract.CommonDataKinds.Email 行，则会获得一个 Cursor，每个 ContactsContract.CommonDataKinds.Email 行在其中都有一行与之对应。

实体可简化查询。使用实体，您可以一次性检索某个联系人或原始联系人的所有联系人数据，而不必先查询父表以获取 ID，然后使用该 ID 查询子表。此外，联系人提供程序会在单个事务中处理针对实体的查询，这可确保检索到的数据在内部保持一致。

注意：实体通常不包含父表和子表的所有列。如果您试图使用的列名称并未出现在实体的列名称常量列表中，则会引发一个 Exception。

以下代码段展示了如何检索某位联系人的所有原始联系人行。该代码段取自某个大型应用，该应用包含两种 activity：“main”activity 和“detail”activity。主 activity 显示联系人行列表；当用户选择某一行时，该 activity 会将该行 ID 发送至详情 activity。详情 activity 使用 ContactsContract.Contacts.Entity 显示与所选联系人关联的所有原始联系人中的所有数据行。

以下代码段摘自“详情”activity：

Kotlin

...
    /*
     * Appends the entity path to the URI. In the case of the Contacts Provider, the
     * expected URI is content://com.google.contacts/#/entity (# is the ID value).
     */
    contactUri = Uri.withAppendedPath(
            contactUri,
            ContactsContract.Contacts.Entity.CONTENT_DIRECTORY
    )

    // Initializes the loader identified by LOADER_ID.
    loaderManager.initLoader(
            LOADER_ID,  // The identifier of the loader to initialize
            null,       // Arguments for the loader (in this case, none)
            this        // The context of the activity
    )

    // Creates a new cursor adapter to attach to the list view
    cursorAdapter = SimpleCursorAdapter(
            this,                       // the context of the activity
            R.layout.detail_list_item,  // the view item containing the detail widgets
            mCursor,                    // the backing cursor
            fromColumns,               // the columns in the cursor that provide the data
            toViews,                   // the views in the view item that display the data
            0)                          // flags

    // Sets the ListView's backing adapter.
    rawContactList.adapter = cursorAdapter
...
override fun onCreateLoader(id: Int, args: Bundle?): Loader<Cursor> {
    /*
     * Sets the columns to retrieve.
     * RAW_CONTACT_ID is included to identify the raw contact associated with the data row.
     * DATA1 contains the first column in the data row (usually the most important one).
     * MIMETYPE indicates the type of data in the data row.
     */
    val projection: Array<String> = arrayOf(
            ContactsContract.Contacts.Entity.RAW_CONTACT_ID,
            ContactsContract.Contacts.Entity.DATA1,
            ContactsContract.Contacts.Entity.MIMETYPE
    )

    /*
     * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw
     * contact collated together.
     */
    val sortOrder = "${ContactsContract.Contacts.Entity.RAW_CONTACT_ID} ASC"

    /*
     * Returns a new CursorLoader. The arguments are similar to
     * ContentResolver.query(), except for the Context argument, which supplies the location of
     * the ContentResolver to use.
     */
    return CursorLoader(
            applicationContext, // The activity's context
            contactUri,        // The entity content URI for a single contact
            projection,         // The columns to retrieve
            null,               // Retrieve all the raw contacts and their data rows.
            null,               //
            sortOrder           // Sort by the raw contact ID.
    )
}

Java

...
    /*
     * Appends the entity path to the URI. In the case of the Contacts Provider, the
     * expected URI is content://com.google.contacts/#/entity (# is the ID value).
     */
    contactUri = Uri.withAppendedPath(
            contactUri,
            ContactsContract.Contacts.Entity.CONTENT_DIRECTORY);

    // Initializes the loader identified by LOADER_ID.
    getLoaderManager().initLoader(
            LOADER_ID,  // The identifier of the loader to initialize
            null,       // Arguments for the loader (in this case, none)
            this);      // The context of the activity

    // Creates a new cursor adapter to attach to the list view
    cursorAdapter = new SimpleCursorAdapter(
            this,                        // the context of the activity
            R.layout.detail_list_item,   // the view item containing the detail widgets
            mCursor,                     // the backing cursor
            fromColumns,                // the columns in the cursor that provide the data
            toViews,                    // the views in the view item that display the data
            0);                          // flags

    // Sets the ListView's backing adapter.
    rawContactList.setAdapter(cursorAdapter);
...
@Override
public Loader<Cursor> onCreateLoader(int id, Bundle args) {

    /*
     * Sets the columns to retrieve.
     * RAW_CONTACT_ID is included to identify the raw contact associated with the data row.
     * DATA1 contains the first column in the data row (usually the most important one).
     * MIMETYPE indicates the type of data in the data row.
     */
    String[] projection =
        {
            ContactsContract.Contacts.Entity.RAW_CONTACT_ID,
            ContactsContract.Contacts.Entity.DATA1,
            ContactsContract.Contacts.Entity.MIMETYPE
        };

    /*
     * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw
     * contact collated together.
     */
    String sortOrder =
            ContactsContract.Contacts.Entity.RAW_CONTACT_ID +
            " ASC";

    /*
     * Returns a new CursorLoader. The arguments are similar to
     * ContentResolver.query(), except for the Context argument, which supplies the location of
     * the ContentResolver to use.
     */
    return new CursorLoader(
            getApplicationContext(),  // The activity's context
            contactUri,              // The entity content URI for a single contact
            projection,               // The columns to retrieve
            null,                     // Retrieve all the raw contacts and their data rows.
            null,                     //
            sortOrder);               // Sort by the raw contact ID.
}

加载完成后，LoaderManager 会调用 onLoadFinished() 回调。此方法的传入参数之一是一个 Cursor，其中包含查询的结果。在您自己的应用中，您可以从该 Cursor 获取数据，以进行显示或做进一步处理。

批量修改

您应尽可能通过创建 ContentProviderOperation 对象的 ArrayList 并调用 applyBatch()，以“批量模式”在联系人提供程序中插入、更新和删除数据。由于联系人提供程序是在 applyBatch() 中通过单一事务执行所有操作，因此您的修改绝不会使联系人存储区出现不一致问题。此外，批量修改还有助于同时插入原始联系人及其详细数据。

注意：如需修改单个原始联系人，请考虑向设备的联系人应用发送一个 intent，而不是在您的应用中处理修改。使用 intent 进行检索和修改部分对此操作进行了更详细的说明。

挂起点

包含大量操作的批量修改可能会阻塞其他进程，导致糟糕的整体用户体验。为将所有您想执行的修改操作尽量分散到各个集合中，并同时防止其阻塞系统，您需要为一项或多项操作设置屈服点。 挂起点是一个 ContentProviderOperation 对象，其 isYieldAllowed() 值设置为 true。当联系人提供程序遇到挂起点时，它会暂停其工作，让其他进程运行，并关闭当前事务。当提供程序再次启动时，它会继续执行 ArrayList 中的下一项操作，并启动新事务。

屈服点会导致每次调用 applyBatch() 涉及多个事务。因此，您应该为一组相关行的最后一项操作设置屈服点。例如，您应该为集中添加原始联系人行及其关联数据行的最后一项操作设置屈服点，或者为与单个联系人相关的一组行的最后一项操作设置屈服点。

挂起点也是一个原子操作单元。无论访问成功还是失败，两个挂起点之间的所有访问均以一个单元的形式呈现。如果您不设置任何挂起点，则最小的原子操作即为整个批量操作。如果您使用了屈服点，则可以防止操作降低系统性能，还可确保一部分操作是原子操作。

修改向后引用

在将新的原始联系人行及其关联的数据行作为一组 ContentProviderOperation 对象插入时，您需将原始联系人的 _ID 值作为 RAW_CONTACT_ID 值插入，从而将数据行链接到原始联系人行。不过，您在数据行创建 ContentProviderOperation 时仍无法使用该值，因为您尚未对原始联系人行应用 ContentProviderOperation。为解决此问题，ContentProviderOperation.Builder 类提供了 withValueBackReference() 方法。借助该方法，您可以插入或修改包含上一次操作结果的列。

withValueBackReference() 方法有两个参数：

key
键值对的键。此参数的值应为您要修改的表中某一列的名称。
previousResult
applyBatch() 中 ContentProviderResult 对象数组内某个值的索引（从 0 开始）。在应用批处理操作时，每个操作的结果均存储在结果的中间数组内。previousResult 值是其中某个结果的索引，并且需通过 key 值对其进行检索和存储。这样，您便可插入一条新的原始联系人记录，并取回其 _ID 值，然后在添加 ContactsContract.Data 行时“向后引用”该值。

系统会在您首次调用 applyBatch() 时创建整个结果数组，其大小等于您提供的 ContentProviderOperation 对象的 ArrayList 大小。不过，结果数组中的所有元素均设置为 null，如果您尝试对尚未应用的操作的结果进行反向引用，withValueBackReference() 会抛出 Exception。

以下代码段展示了如何批量插入新的原始联系人和数据。其中包括用于建立屈服点和使用向后引用的代码。

第一个代码段用于检索界面中的联系人数据。此时，用户已选择应添加新原始联系人的账号。

Kotlin

// Creates a contact entry from the current UI values, using the currently-selected account.
private fun createContactEntry() {
    /*
     * Gets values from the UI
     */
    val name = contactNameEditText.text.toString()
    val phone = contactPhoneEditText.text.toString()
    val email = contactEmailEditText.text.toString()

    val phoneType: String = contactPhoneTypes[mContactPhoneTypeSpinner.selectedItemPosition]

    val emailType: String = contactEmailTypes[mContactEmailTypeSpinner.selectedItemPosition]

Java

// Creates a contact entry from the current UI values, using the currently-selected account.
protected void createContactEntry() {
    /*
     * Gets values from the UI
     */
    String name = contactNameEditText.getText().toString();
    String phone = contactPhoneEditText.getText().toString();
    String email = contactEmailEditText.getText().toString();

    int phoneType = contactPhoneTypes.get(
            contactPhoneTypeSpinner.getSelectedItemPosition());

    int emailType = contactEmailTypes.get(
            contactEmailTypeSpinner.getSelectedItemPosition());

下一个代码段将创建一项操作，将原始联系人行插入 ContactsContract.RawContacts 表：

Kotlin

    /*
     * Prepares the batch operation for inserting a new raw contact and its data. Even if
     * the Contacts Provider does not have any data for this person, you can't add a Contact,
     * only a raw contact. The Contacts Provider will then add a Contact automatically.
     */

    // Creates a new array of ContentProviderOperation objects.
    val ops = arrayListOf<ContentProviderOperation>()

    /*
     * Creates a new raw contact with its account type (server type) and account name
     * (user's account). Remember that the display name is not stored in this row, but in a
     * StructuredName data row. No other data is required.
     */
    var op: ContentProviderOperation.Builder =
            ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)
                    .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.name)
                    .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.type)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

Java

    /*
     * Prepares the batch operation for inserting a new raw contact and its data. Even if
     * the Contacts Provider does not have any data for this person, you can't add a Contact,
     * only a raw contact. The Contacts Provider will then add a Contact automatically.
     */

     // Creates a new array of ContentProviderOperation objects.
    ArrayList<ContentProviderOperation> ops =
            new ArrayList<ContentProviderOperation>();

    /*
     * Creates a new raw contact with its account type (server type) and account name
     * (user's account). Remember that the display name is not stored in this row, but in a
     * StructuredName data row. No other data is required.
     */
    ContentProviderOperation.Builder op =
            ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)
            .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType())
            .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName());

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

接下来，代码会创建显示姓名行、电话行和电子邮件行的数据行。

每个操作的 Builder 对象均使用 withValueBackReference() 来获取 RAW_CONTACT_ID。引用指回第一次操作（添加原始联系人行并返回其新 _ID 值）的 ContentProviderResult 对象。因此，每个数据行都通过其 RAW_CONTACT_ID 自动关联到其所属的新 ContactsContract.RawContacts 行。

添加电子邮件行的 ContentProviderOperation.Builder 对象带有 withYieldAllowed() 标记，用于设置挂起点：

Kotlin

    // Creates the display name for the new raw contact, as a StructuredName data row.
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * withValueBackReference sets the value of the first argument to the value of
             * the ContentProviderResult indexed by the second argument. In this particular
             * call, the raw contact ID column of the StructuredName data row is set to the
             * value of the result returned by the first operation, which is the one that
             * actually adds the raw contact row.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to StructuredName
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE)

            // Sets the data row's display name to the name in the UI.
            .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

    // Inserts the specified phone number and type as a Phone data row
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Phone
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)

            // Sets the phone number and type
            .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
            .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

    // Inserts the specified email and type as a Phone data row
    op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Email
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)

            // Sets the email address and type
            .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email)
            .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType)

    /*
     * Demonstrates a yield point. At the end of this insert, the batch operation's thread
     * will yield priority to other threads. Use after every set of operations that affect a
     * single contact, to avoid degrading performance.
     */
    op.withYieldAllowed(true)

    // Builds the operation and adds it to the array of operations
    ops.add(op.build())

Java

    // Creates the display name for the new raw contact, as a StructuredName data row.
    op =
            ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * withValueBackReference sets the value of the first argument to the value of
             * the ContentProviderResult indexed by the second argument. In this particular
             * call, the raw contact ID column of the StructuredName data row is set to the
             * value of the result returned by the first operation, which is the one that
             * actually adds the raw contact row.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to StructuredName
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE)

            // Sets the data row's display name to the name in the UI.
            .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name);

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

    // Inserts the specified phone number and type as a Phone data row
    op =
            ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Phone
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)

            // Sets the phone number and type
            .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
            .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType);

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

    // Inserts the specified email and type as a Phone data row
    op =
            ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            /*
             * Sets the value of the raw contact id column to the new raw contact ID returned
             * by the first operation in the batch.
             */
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

            // Sets the data row's MIME type to Email
            .withValue(ContactsContract.Data.MIMETYPE,
                    ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)

            // Sets the email address and type
            .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email)
            .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType);

    /*
     * Demonstrates a yield point. At the end of this insert, the batch operation's thread
     * will yield priority to other threads. Use after every set of operations that affect a
     * single contact, to avoid degrading performance.
     */
    op.withYieldAllowed(true);

    // Builds the operation and adds it to the array of operations
    ops.add(op.build());

最后一个代码段显示的是 applyBatch() 调用，用于插入新原始联系人行和数据行。

Kotlin

    // Ask the Contacts Provider to create a new contact
    Log.d(TAG, "Selected account: ${mSelectedAccount.name} (${mSelectedAccount.type})")
    Log.d(TAG, "Creating contact: $name")

    /*
     * Applies the array of ContentProviderOperation objects in batch. The results are
     * discarded.
     */
    try {
        contentResolver.applyBatch(ContactsContract.AUTHORITY, ops)
    } catch (e: Exception) {
        // Display a warning
        val txt: String = getString(R.string.contactCreationFailure)
        Toast.makeText(applicationContext, txt, Toast.LENGTH_SHORT).show()

        // Log exception
        Log.e(TAG, "Exception encountered while inserting contact: $e")
    }
}

Java

    // Ask the Contacts Provider to create a new contact
    Log.d(TAG,"Selected account: " + selectedAccount.getName() + " (" +
            selectedAccount.getType() + ")");
    Log.d(TAG,"Creating contact: " + name);

    /*
     * Applies the array of ContentProviderOperation objects in batch. The results are
     * discarded.
     */
    try {

            getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);
    } catch (Exception e) {

            // Display a warning
            Context ctx = getApplicationContext();

            CharSequence txt = getString(R.string.contactCreationFailure);
            int duration = Toast.LENGTH_SHORT;
            Toast toast = Toast.makeText(ctx, txt, duration);
            toast.show();

            // Log exception
            Log.e(TAG, "Exception encountered while inserting contact: " + e);
    }
}

借助批量操作，您还可以实现乐观并发控制，这是一种在不锁定底层代码库的情况下应用修改事务的方法。如要使用此方法，您需要应用事务，并检查是否存在可能已同时执行的其他修改。如果您发现修改不一致，请回滚事务并重试。

乐观并发控制非常适用于移动设备，因为在此类设备上，同一时间只有一位用户，并且同时访问数据存储区的情况很少见。由于该类设备未使用锁定功能，因此无需浪费时间设置锁定或等待其他事务解除锁定。

如需在更新单个 ContactsContract.RawContacts 行时使用乐观并发控制，请按以下步骤操作：

  1. 检索原始联系人的 VERSION 列以及要检索的其他数据。
  2. 使用 newAssertQuery(Uri) 方法创建适合强制执行约束的 ContentProviderOperation.Builder 对象。对于内容 URI，请使用追加有原始联系人 _ID 的 RawContacts.CONTENT_URI。
  3. 对于 ContentProviderOperation.Builder 对象，请调用 withValue()，将 VERSION 列与您刚检索的版本号进行比较。
  4. 对于同一 ContentProviderOperation.Builder，请调用 withExpectedCount()，确保此断言只对一行进行测试。
  5. 调用 build() 创建 ContentProviderOperation 对象，然后将此对象添加为要传递给 applyBatch() 的 ArrayList 中的第一个对象。
  6. 应用批处理事务。

如果在读取原始联系人行和准备对其进行修改的这段时间内，如有另一项操作更新该行，则“断言”ContentProviderOperation 会失败，系统将终止整个批处理操作。此情况下，您可以选择重新执行批处理操作，或执行其他操作。

以下代码段演示了如何在使用 CursorLoader 查询一位原始联系人后创建一个“断言”ContentProviderOperation：

Kotlin

/*
 * The application uses CursorLoader to query the raw contacts table. The system calls this method
 * when the load is finished.
 */
override fun onLoadFinished(loader: Loader<Cursor>, cursor: Cursor) {
    // Gets the raw contact's _ID and VERSION values
    rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID))
    mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION))
}

...

// Sets up a Uri for the assert operation
val rawContactUri: Uri = ContentUris.withAppendedId(
        ContactsContract.RawContacts.CONTENT_URI,
        rawContactID
)

// Creates a builder for the assert operation
val assertOp: ContentProviderOperation.Builder =
        ContentProviderOperation.newAssertQuery(rawContactUri).apply {
            // Adds the assertions to the assert operation: checks the version
            withValue(SyncColumns.VERSION, mVersion)

            // and count of rows tested
            withExpectedCount(1)
        }

// Creates an ArrayList to hold the ContentProviderOperation objects
val ops = arrayListOf<ContentProviderOperation>()

ops.add(assertOp.build())

// You would add the rest of your batch operations to "ops" here

...

// Applies the batch. If the assert fails, an Exception is thrown
try {
    val results: Array<ContentProviderResult> = contentResolver.applyBatch(AUTHORITY, ops)
} catch (e: OperationApplicationException) {
    // Actions you want to take if the assert operation fails go here
}

Java

/*
 * The application uses CursorLoader to query the raw contacts table. The system calls this method
 * when the load is finished.
 */
public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {

    // Gets the raw contact's _ID and VERSION values
    rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID));
    mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION));
}

...

// Sets up a Uri for the assert operation
Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactID);

// Creates a builder for the assert operation
ContentProviderOperation.Builder assertOp = ContentProviderOperation.newAssertQuery(rawContactUri);

// Adds the assertions to the assert operation: checks the version and count of rows tested
assertOp.withValue(SyncColumns.VERSION, mVersion);
assertOp.withExpectedCount(1);

// Creates an ArrayList to hold the ContentProviderOperation objects
ArrayList ops = new ArrayList<ContentProviderOperation>;

ops.add(assertOp.build());

// You would add the rest of your batch operations to "ops" here

...

// Applies the batch. If the assert fails, an Exception is thrown
try
    {
        ContentProviderResult[] results =
                getContentResolver().applyBatch(AUTHORITY, ops);

    } catch (OperationApplicationException e) {

        // Actions you want to take if the assert operation fails go here
    }

通过 Intent 执行检索和修改

通过向设备的通讯录应用发送 intent，您可以间接访问通讯录提供程序。intent 会启动设备的联系人应用界面，用户可以在该界面中执行与联系人相关的工作。通过这种访问方式，用户可以：

  • 从列表中选取一位联系人并将其返回给您的应用以执行进一步操作。
  • 修改现有联系人的数据。
  • 为其任一账户插入新原始联系人。
  • 删除联系人或联系人数据。

如果用户正在插入或更新数据，您可以先收集数据，然后将其作为 intent 的一部分发送。

当您使用 intent 通过设备的联系人应用访问联系人提供程序时，您无需自行编写用于访问该提供程序的界面或代码。您也无需请求对提供程序的读取或写入权限。设备的通讯录应用可以将联系人读取权限授予给您，而且您是通过另一个应用对该提供程序进行修改，因此无需拥有写入权限。

如需详细了解通过发送 intent 来访问提供程序的常规步骤，请参阅 内容提供程序基础知识指南的“通过 intent 访问数据”部分。表 4 总结了可用任务中所用的操作、MIME 类型和数据值，而可用于 putExtra() 的 Extra 值则列在 ContactsContract.Intents.Insert 参考文档中：

表 4. 联系人提供程序 intent。

任务 操作 数据 MIME 类型 备注
从列表中选择联系人 ACTION_PICK 以下各项中的一项： 未使用 显示原始联系人列表或某位原始联系人的数据列表，具体取决于您提供的内容 URI 类型。

调用 startActivityForResult()，该方法会返回所选行的内容 URI。该 URI 的形式为：表的内容 URI 附加了该行的 LOOKUP_ID。设备的联系人应用会在 activity 的生命周期内将读取和写入权限授予给此内容 URI。如需了解详情，请参阅 内容提供程序基础知识指南。

插入新原始联系人 Insert.ACTION 不适用 RawContacts.CONTENT_TYPE，用于一组原始联系人的 MIME 类型。 显示设备“通讯录”应用的添加联系人屏幕。系统会显示您添加到 intent 中的 extra 值。如果随 startActivityForResult() 一起发送新添加的原始联系人的内容 URI，则系统会将新添加的原始联系人的内容 URI 传回到 Activity 的 onActivityResult() 回调方法，该回调方法位于 Intent 参数的“data”字段中。如需获取该值，请调用 getData()。
修改联系人 ACTION_EDIT CONTENT_LOOKUP_URI 表示联系人。用户可使用编辑 activity 编辑任何与此联系人关联的数据。 Contacts.CONTENT_ITEM_TYPE，单个联系人。 显示“通讯录”应用中的“编辑联系人”屏幕。系统会显示您添加到 intent 中的 extra 值。当用户点击完成保存编辑时，您的 activity 会返回前台。
显示一个同样可以添加数据的选择器。 ACTION_INSERT_OR_EDIT N/A CONTENT_ITEM_TYPE 此 intent 始终显示“通讯录”应用的选择器屏幕。用户可以选择要修改的联系人，也可以添加新的联系人。根据用户的选择，系统会显示编辑界面或添加界面，还会显示您使用 intent 传递的 extra 数据。如果您的应用显示电子邮件或电话号码等联系人数据，请使用此 intent 来允许用户向现有联系人添加数据。 联系人、

注意：无需在此 intent 的 extra 中发送姓名值，因为用户总是会选择现有姓名或添加新姓名。此外，如果您发送姓名，并且用户选择执行编辑操作，则联系人应用将显示您发送的姓名，该姓名将覆盖先前的值。如果用户未注意此情况便保存了编辑，则旧值会丢失。

设备的联系人应用不允许您使用 intent 删除原始联系人或其任何数据。因此，如要删除原始联系人，请使用 ContentResolver.delete() 或 ContentProviderOperation.newDelete()。

以下代码段展示了如何构建和发送用于插入新原始联系人和数据的 intent：

Kotlin

// Gets values from the UI
val name = contactNameEditText.text.toString()
val phone = contactPhoneEditText.text.toString()
val email = contactEmailEditText.text.toString()

val company = companyName.text.toString()
val jobtitle = jobTitle.text.toString()

/*
 * Demonstrates adding data rows as an array list associated with the DATA key
 */

// Defines an array list to contain the ContentValues objects for each row
val contactData = arrayListOf<ContentValues>()

/*
 * Defines the raw contact row
 */

// Sets up the row as a ContentValues object
val rawContactRow = ContentValues().apply {
    // Adds the account type and name to the row
    put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.type)
    put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.name)
}

// Adds the row to the array
contactData.add(rawContactRow)

/*
 * Sets up the phone number data row
 */

// Sets up the row as a ContentValues object
val phoneRow = ContentValues().apply {
    // Specifies the MIME type for this data row (all data rows must be marked by their type)
    put(ContactsContract.Data.MIMETYPE,ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)

    // Adds the phone number and its type to the row
    put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
}

// Adds the row to the array
contactData.add(phoneRow)

/*
 * Sets up the email data row
 */

// Sets up the row as a ContentValues object
val emailRow = ContentValues().apply {
    // Specifies the MIME type for this data row (all data rows must be marked by their type)
    put(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE)

    // Adds the email address and its type to the row
    put(ContactsContract.CommonDataKinds.Email.ADDRESS, email)
}

// Adds the row to the array
contactData.add(emailRow)

// Creates a new intent for sending to the device's contacts application
val insertIntent = Intent(ContactsContract.Intents.Insert.ACTION).apply {
    // Sets the MIME type to the one expected by the insertion activity
    type = ContactsContract.RawContacts.CONTENT_TYPE

    // Sets the new contact name
    putExtra(ContactsContract.Intents.Insert.NAME, name)

    // Sets the new company and job title
    putExtra(ContactsContract.Intents.Insert.COMPANY, company)
    putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle)

    /*
    * Adds the array to the intent's extras. It must be a parcelable object in order to
    * travel between processes. The device's contacts app expects its key to be
    * Intents.Insert.DATA
    */
    putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData)
}

// Send out the intent to start the device's contacts app in its add contact activity.
startActivity(insertIntent)

Java

// Gets values from the UI
String name = contactNameEditText.getText().toString();
String phone = contactPhoneEditText.getText().toString();
String email = contactEmailEditText.getText().toString();

String company = companyName.getText().toString();
String jobtitle = jobTitle.getText().toString();

// Creates a new intent for sending to the device's contacts application
Intent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION);

// Sets the MIME type to the one expected by the insertion activity
insertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE);

// Sets the new contact name
insertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name);

// Sets the new company and job title
insertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company);
insertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle);

/*
 * Demonstrates adding data rows as an array list associated with the DATA key
 */

// Defines an array list to contain the ContentValues objects for each row
ArrayList<ContentValues> contactData = new ArrayList<ContentValues>();


/*
 * Defines the raw contact row
 */

// Sets up the row as a ContentValues object
ContentValues rawContactRow = new ContentValues();

// Adds the account type and name to the row
rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType());
rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName());

// Adds the row to the array
contactData.add(rawContactRow);

/*
 * Sets up the phone number data row
 */

// Sets up the row as a ContentValues object
ContentValues phoneRow = new ContentValues();

// Specifies the MIME type for this data row (all data rows must be marked by their type)
phoneRow.put(
        ContactsContract.Data.MIMETYPE,
        ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
);

// Adds the phone number and its type to the row
phoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone);

// Adds the row to the array
contactData.add(phoneRow);

/*
 * Sets up the email data row
 */

// Sets up the row as a ContentValues object
ContentValues emailRow = new ContentValues();

// Specifies the MIME type for this data row (all data rows must be marked by their type)
emailRow.put(
        ContactsContract.Data.MIMETYPE,
        ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE
);

// Adds the email address and its type to the row
emailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email);

// Adds the row to the array
contactData.add(emailRow);

/*
 * Adds the array to the intent's extras. It must be a parcelable object in order to
 * travel between processes. The device's contacts app expects its key to be
 * Intents.Insert.DATA
 */
insertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData);

// Send out the intent to start the device's contacts app in its add contact activity.
startActivity(insertIntent);

数据完整性

由于联系人存储库包含用户希望正确且最新的重要敏感数据，因此联系人提供程序具有明确定义的数据完整性规则。您有责任在修改联系人数据时遵守这些规则。以下列出了一些重要规则：

务必为您添加的每个 ContactsContract.RawContacts 行添加一个 ContactsContract.CommonDataKinds.StructuredName 行。
如果 ContactsContract.Data 表中的 ContactsContract.RawContacts 行没有 ContactsContract.CommonDataKinds.StructuredName 行，则可能会在汇总时遇到问题。
请始终将新的 ContactsContract.Data 行与其父级 ContactsContract.RawContacts 行相关联。
未链接到 ContactsContract.RawContacts 的 ContactsContract.Data 行在设备的联系人应用中将不会显示，并且可能会导致同步适配器出现问题。
只更改您所拥有的原始联系人的数据。
请注意，联系人提供程序通常管理来自多个不同账号类型/在线服务的数据。您需要确保您的应用仅修改或删除归您所有的行的数据，并且仅通过您控制的账号类型和账号名称插入数据。
对于授权方、内容 URI、URI 路径、列名称、MIME 类型和 TYPE 值，请始终使用 ContactsContract 及其子类中定义的常量。
使用这些常量有助于您避免错误。如有任何常量被弃用，您还会收到编译器警告。

自定义数据行

通过创建和使用自己的自定义 MIME 类型，您可以在 ContactsContract.Data 表中插入、编辑、删除和检索您的自有数据行。这些行仅限使用 ContactsContract.DataColumns 中定义的列，但您可以将自己的类型专用列名称映射到默认列名称。设备的通讯录应用会显示这些行的数据，但用户无法对其进行编辑或删除，亦无法添加其他数据。如要让用户修改您的自定义数据行，您必须在自己的应用中提供编辑 activity。

如需显示自定义数据，请提供一个 contacts.xml 文件，其中须包含一个 <ContactsAccountType> 元素，及其一个或多个 <ContactsDataKind> 子元素。<ContactsDataKind> element 部分对此进行了更详细的说明。

如需详细了解自定义 MIME 类型，请参阅 创建内容提供程序指南。

联系人提供程序同步适配器

联系人提供程序专门设计用于处理设备与在线服务之间的联系人数据的同步。借助同步功能，用户可以将现有数据下载到新设备，并将现有数据上传到新账号。 同步还能确保用户手握最新数据，无需考虑数据增加和更改的来源。同步的另一个优点是，即使设备未连接网络，它也能让用户使用联系人数据。

虽然您可以通过各种方式实现同步，不过 Android 系统提供了一个插件同步框架，可自动完成下列任务：

  • 检查网络可用性。
  • 根据用户偏好安排和执行同步。
  • 重启已停止的同步。

如要使用此框架，您需提供同步适配器插件。每个同步适配器都专用于某个服务和内容提供程序，但可以处理同一服务的多个账号名称。该框架还允许同一服务和提供程序拥有多个同步适配器。

同步适配器类和文件

您需要将同步适配器作为 AbstractThreadedSyncAdapter 的子类进行实现，并作为 Android 应用的一部分进行安装。系统会通过应用清单文件中的元素以及清单文件指向的特殊 XML 文件，了解同步适配器的相关信息。该 XML 文件定义在线服务的账号类型和内容提供程序的权限，二者共同对适配器进行唯一标识。只有当用户为同步适配器的账号类型添加账号，并为与同步适配器同步的内容提供程序启用同步后，同步适配器才会激活。激活后，系统将开始管理适配器，并在必要时调用该适配器，以在内容提供程序与服务器之间同步数据。

注意：通过将账号类型用作同步适配器标识的部分内容，系统可检测出从同一账号类型访问不同服务的同步适配器，并对其进行分类。例如，Google 在线服务的同步适配器都具有相同的账号类型 com.google。当用户向其设备添加 Google 账号时，已安装的所有 Google 服务同步适配器会一起列出；列出的每个同步适配器都会与设备上不同的内容提供程序同步。

大多数服务都要求用户在验证身份后访问数据，为此，Android 系统提供身份验证框架，该框架与同步适配器框架类似，并且经常与其联用。该身份验证框架使用的插件身份验证器是 AbstractAccountAuthenticator 的子类。身份验证器通过下列步骤验证用户的身份：

  1. 收集用户的名称、密码或类似信息（用户的凭据）。
  2. 将凭据发送给服务
  3. 检查服务的回复。

如果服务接受凭据，身份验证器便可存储凭据以供日后使用。由于插件身份验证器框架的存在，AccountManager 可以访问身份验证器支持并选择公开的任何身份验证令牌（例如 OAuth2 身份验证令牌）。

虽然身份验证不是必需的，但大多数联系人服务都会使用它。不过，您不一定要使用 Android 身份验证框架进行身份验证。

同步适配器实现

要为联系人提供程序实现同步适配器，请先创建一个包含以下内容的 Android 应用：

一个 Service 组件，用于响应系统发出的绑定到同步适配器的请求。
当系统想要运行同步时，它会调用服务的 onBind() 方法以获取同步适配器的 IBinder。这样，系统便可跨进程调用适配器的方法。
作为 AbstractThreadedSyncAdapter 具体子类实现的实际同步适配器。
此类的作用是从服务器下载数据、从设备上传数据以及解决冲突。系统会在 onPerformSync() 方法中完成适配器的主要工作。必须将此类实例化为单例。
Application 的子类。
此类充当同步适配器单例的工厂。使用 onCreate() 方法实例化同步适配器，并提供一个静态“getter”方法，使单例返回同步适配器服务的 onBind() 方法。
可选：一个 Service 组件，用于响应系统发出的用户身份验证请求。
AccountManager 会启动此服务以开始身份验证流程。该服务的 onCreate() 方法会实例化一个身份验证器对象。当系统想要对应用同步适配器的用户账号进行身份验证时，它会调用该服务的 onBind() 方法，为该身份验证器获取一个 IBinder。这样，系统便可跨进程调用身份验证器的方法。
可选：用于处理身份验证请求的 AbstractAccountAuthenticator 具体子类。
此类会为 AccountManager 提供调用的方法，以便其通过服务器验证用户的凭据。身份验证过程的细节差别很大，具体取决于所使用的服务器技术。如要了解身份验证的相关详情，请参阅服务器软件的文档。
用于向系统定义同步适配器和身份验证器的 XML 文件。
之前描述的同步适配器和身份验证器服务组件都是在应用清单文件中的 <service> 元素内定义的。这些元素包含 <meta-data> 子元素，可以为系统提供特定数据：
  • 同步适配器服务的 <meta-data> 元素指向 XML 文件 res/xml/syncadapter.xml。而该文件则指定将与联系人提供程序同步的网络服务的 URI，以及指定该 Web 服务的账号类型。
  • 可选：身份验证器的 <meta-data> 元素指向 XML 文件 res/xml/authenticator.xml。而该文件则指定此身份验证器所支持的账号类型，以及身份验证过程中出现的界面资源。在此元素中指定的账号类型必须与为同步适配器指定的账号类型相同。

社交流数据

android.provider.ContactsContract.StreamItems 表和 android.provider.ContactsContract.StreamItemPhotos 表管理着来自社交网络的传入数据。您可以编写同步适配器，将自己社交网络中的流数据添加至这些表内，也可读取表中的流数据并将其显示在自己的应用中，或同时执行这两种操作。利用这些功能，可以将您的社交网络服务和应用集成到 Android 的社交网络体验之中。

社交流文本

流式传输项始终与原始联系人相关联。android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID 会链接到原始联系人的 _ID 值。原始联系人的账号类型和账号名称也存储在流项目行中。

将您的流数据存储在以下列中：

android.provider.Contacts 合同.StreamItems 列#ACCOUNT_TYPE
必需。与该流项目关联的原始联系人的用户账号类型。请记得在插入流项目时设置此值。
android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME
必需。与此流式传输项关联的原始联系人的用户账号名称。请记得在插入流项目时设置此值。
标识符列
必需。插入流项目时，您必须插入下列标识符列：
  • android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID：与此流项目关联的联系人的 android.provider.BaseColumns#_ID 值。
  • android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY：与此流项目关联的联系人的 android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY 值。
  • android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID：与此流项目关联的原始联系人的 android.provider.BaseColumns#_ID 值。
android.provider.ContactsContract.StreamItemsColumns#COMMENTS
可选。存储您可以在流项目开头显示的摘要信息。
android.provider.ContactsContract.StreamItemsColumns#TEXT
流项目的文本，可以是项目来源发布的内容，也可以是对生成流项目的某项操作的描述。此列可包含可由 fromHtml() 渲染的任何格式设置和嵌入式资源图片。提供程序可能会截断或省略较长内容，但它会尽力避免破坏标记。
android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP
一个包含流项目插入时间或更新时间的文本字符串，以从公元纪年开始计算的毫秒数形式表示。此列由插入或更新流项的应用负责维护；联系人提供程序不会自动维护此列。

如需显示您的流项目的标识信息，请使用 android.provider.ContactsContract.StreamItemsColumns#RES_ICON、android.provider.ContactsContract.StreamItemsColumns#RES_LABEL 和 android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE 链接到应用中的资源。

android.provider.ContactsContract.StreamItems 表还包含供同步适配器专用的列 android.provider.ContactsContract.StreamItemsColumns#SYNC1 至 android.provider.ContactsContract.StreamItemsColumns#SYNC4。

社交流照片

android.provider.ContactsContract.StreamItemPhotos 表存储与流项目关联的照片。该表的 android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID 列会链接到 android.provider.ContactsContract.StreamItems 表的 _ID 列中的值。照片引用存储在表中的以下列：

android.provider.ContactsContract.StreamItemPhotos#PHOTO 列（一个二进制大型对象）。
照片的二进制表示，由提供程序调整尺寸，以便存储和显示。 此列可用于向后兼容使用它来存储照片的旧版联系人提供程序。不过，在当前版本中，您不应使用此列来存储照片。而应使用 android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID 或 android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI（下文对两者都做了描述）将照片存储在一个文件内。此列现在包含可供读取的照片缩略图。
android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID
原始联系人照片的数字标识符。将此值附加到常量 DisplayPhoto.CONTENT_URI 以获取指向单个照片文件的内容 URI，然后调用 openAssetFileDescriptor() 来获取照片文件的句柄。
android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI
一个内容 URI，直接指向此行所表示的照片的照片文件。 使用此 URI 调用 openAssetFileDescriptor()，以获取照片文件的句柄。

使用社交流表

这些表的工作方式与联系人提供程序中的其他主表基本相同，不同的是：

  • 这些表需要额外的访问权限。如要读取它们的数据，您的应用必须拥有 android.Manifest.permission#READ_SOCIAL_STREAM 权限。如要修改它们，您的应用必须拥有 android.Manifest.permission#WRITE_SOCIAL_STREAM 权限。
  • 对于 android.provider.ContactsContract.StreamItems 表，为每位原始联系人存储的行数有限。一旦达到该限制，联系人提供程序即会自动删除 android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP 最旧的行，为新的流项目行腾出空间。如需获取该限制，请发出对内容 URI android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI 的查询。您可以将除内容 URI 之外的所有其他参数保持设置为 null。查询会返回一个 Cursor，其中包含一行，并且只有 android.provider.ContactsContract.StreamItems#MAX_ITEMS 一列。

android.provider.ContactsContract.StreamItems.StreamItemPhotos 类定义了 android.provider.ContactsContract.StreamItemPhotos 的一个子表，其中包含某个流项目的照片行。

社交流交互

通过将联系人提供程序管理的社交流数据与设备的联系人应用相结合，您可以在社交网络系统与现有联系人之间建立起有效的连接。可使用以下功能：

  • 您可以通过同步适配器将您的社交网络服务与联系人提供程序进行同步，从而检索用户联系人的近期 activity，并将其存储在 android.provider.ContactsContract.StreamItems 表和 android.provider.ContactsContract.StreamItemPhotos 表中，以供日后使用。
  • 除了定期同步外，您还可以在用户选择某位联系人进行查看时触发您的同步适配器以检索更多数据。这样，您的同步适配器就可以检索该联系人的高分辨率照片和最新的流项。
  • 通过在设备的通讯录应用和通讯录提供程序中注册通知，您可以在用户查看联系人时接收一个 intent，并在那时通过您的服务更新联系人的状态。与通过同步适配器执行完全同步相比，此方法可能更快速，占用的带宽也更少。
  • 用户可以在查看设备联系人应用中的联系人时，将联系人添加到您的社交网络服务。您可以通过“邀请联系人”功能实现此目的，而该功能则是通过将 activity 与 XML 文件结合使用来实现的，前者将现有联系人添加到您的社交网络，后者为设备的联系人应用和联系人提供程序提供您应用的相关详情。

流项目与联系人提供程序的定期同步与其他同步相同。如需详细了解同步，请参阅联系人提供程序同步适配器部分。接下来的两部分介绍如何注册通知和邀请联系人。

通过注册处理社交网络查看

如要注册您的同步适配器，以便在用户查看由其管理的联系人时收到通知，请执行以下步骤：

  1. 在项目的 res/xml/ 目录中创建一个名为 contacts.xml 的文件。如果您已有该文件，可跳过此步骤。
  2. 在此文件中，添加 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> 元素。 如果此元素已存在，则可以跳过此步骤。
  3. 如要注册一项服务，以便在用户于设备的联系人应用中打开某位联系人的详情页面时通知该服务，请为该元素添加 viewContactNotifyService="serviceclass" 属性，其中 serviceclass 是该服务的完全限定类名，并且应由该服务接收来自设备联系人应用的 intent。对于通知程序服务，请使用扩展 IntentService 的类，以便该服务能够接收 intent。传入 intent 中的数据包含用户点击的原始联系人的内容 URI。您可以使用通知程序服务绑定到您的同步适配器，然后调用该同步适配器更新原始联系人的数据。

如需注册在用户点击流项目和/或照片时调用的 Activity，请执行以下操作：

  1. 在项目的 res/xml/ 目录中创建一个名为 contacts.xml 的文件。如果您已有此文件，可以跳过此步骤。
  2. 在此文件中，添加 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> 元素。 如果该元素已存在，可跳过此步骤。
  3. 如需注册您的某个 Activity 来处理用户点击设备联系人应用中的流项的操作，请将属性 viewStreamItemActivity="activityclass" 添加到该元素中，其中 activityclass 是应从设备联系人应用接收 intent 的 Activity 的完全限定类名。
  4. 如要注册某个 activity，以处理用户在设备联系人应用中点击某个流照片的操作，请为该元素添加 viewStreamItemPhotoActivity="activityclass" 属性，其中 activityclass 是该 activity 的完全限定类名，并且应由该 activity 接收来自设备联系人应用的 intent。

<ContactsAccountType> 元素部分对 <ContactsAccountType> 元素做了更详尽的描述。

传入 intent 包含用户所点击的项目或照片的内容 URI。 如需为文本项和照片分别创建 activity，请在同一文件中使用这两个属性。

与您的社交网络服务进行交互

用户无需离开设备的联系人应用即可邀请联系人访问您的社交网站。取而代之的是，您可以让设备的通讯录应用发送一个 intent，将联系人邀请到您的某个 activity。如需设置此模式，请执行以下操作：

  1. 在项目的 res/xml/ 目录中创建一个名为 contacts.xml 的文件。如果您已有该文件，可跳过此步骤。
  2. 在此文件中，添加 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> 元素。 如果此元素已存在，则可以跳过此步骤。
  3. 添加以下属性：
    • inviteContactActivity="activityclass"
    • inviteContactActionLabel="@string/invite_action_label"
    activityclass 值是应接收该 intent 的 activity 的完全限定类名。invite_action_label 值是一个文本字符串，将显示在设备联系人应用的添加关联菜单中。

注意：ContactsSource 是 ContactsAccountType 的一个已废弃的标记名称。

contacts.xml 引用

文件 contacts.xml 包含一些 XML 元素，这些元素控制您的同步适配器和应用与联系人应用及联系人提供程序的交互。下文将对这些元素进行描述。

<ContactsAccountType> 元素

<ContactsAccountType> 元素控制您的应用与联系人应用的交互。其语法如下： 

<ContactsAccountType
        xmlns:android="http://schemas.android.com/apk/res/android"
        inviteContactActivity="activity_name"
        inviteContactActionLabel="invite_command_text"
        viewContactNotifyService="view_notify_service"
        viewGroupActivity="group_view_activity"
        viewGroupActionLabel="group_action_text"
        viewStreamItemActivity="viewstream_activity_name"
        viewStreamItemPhotoActivity="viewphotostream_activity_name">

包含在：

res/xml/contacts.xml

可以包含：

<ContactsDataKind>

说明：

声明 Android 组件和界面标签，以便用户邀请他们的一位联系人加入社交网络、在其某个社交网络流更新时通知用户，以及执行其他操作。

请注意，对 <ContactsAccountType> 的属性而言，属性前缀 android: 并非必需的。

属性：

inviteContactActivity
您的应用中某个 activity 的完全限定类名，您想要在用户于设备的联系人应用中选择 Add connection 时激活该 activity。
inviteContactActionLabel
Add connection 菜单中为 inviteContactActivity 中指定的 activity 显示的文本字符串。 例如，您可以使用字符串“Follow in my network”。您可以为此标签使用字符串资源标识符。
viewContactNotifyService
您的应用中某项服务的完全限定类名，当用户查看联系人时，应由该服务接收通知。此通知由设备的联系人应用发送；您的应用可根据该通知将数据密集型操作推迟到必要时再执行。例如，您的应用可按如下方式响应该通知：读入并显示联系人的高分辨率照片和最近的社交流项目。社交流交互部分对此功能做了更详尽的描述。
viewGroupActivity
您的应用中某个可显示组信息的 activity 的完全限定类名。当用户点击设备联系人应用中的组标签时，系统会显示此 activity 的界面。
viewGroupActionLabel
联系人应用为某个界面控件显示的标签，用户可通过该控件查看您应用中的组。

此属性允许使用字符串资源标识符。

viewStreamItemActivity
您的应用中某个 activity 的完全限定类名，当用户点击原始联系人的流项目时，设备的联系人应用会启动该 activity。
viewStreamItemPhotoActivity
您的应用中某个 activity 的完全限定类名，当用户点击原始联系人流项目中的照片时，设备的联系人应用会启动该 activity。

<ContactsDataKind> 元素

<ContactsDataKind> 元素控制着您应用的自定义数据行在通讯录应用界面中的显示。其语法如下： 

<ContactsDataKind
        android:mimeType="MIMEtype"
        android:icon="icon_resources"
        android:summaryColumn="column_name"
        android:detailColumn="column_name">

包含在：

<ContactsAccountType>

说明：

此元素用于让联系人应用将自定义数据行的内容显示为原始联系人详细信息的一部分。<ContactsAccountType> 的每个 <ContactsDataKind> 子元素都代表您的同步适配器向 ContactsContract.Data 表添加的某个自定义数据行类型。请为您使用的每个自定义 MIME 类型添加一个 <ContactsDataKind> 元素。如果您不想显示任何自定义数据行的数据，则无需添加该元素。

属性：

android:mimeType
您为 ContactsContract.Data 表中某个自定义数据行类型定义的自定义 MIME 类型。例如，可将值 vnd.android.cursor.item/vnd.example.locationstatus 作为记录联系人最后已知位置的数据行的自定义 MIME 类型。
android:icon
联系人应用在您的数据旁边显示的 Android 可绘制资源。该属性用于向用户指明数据来自您的服务。
android:summaryColumn
从数据行检索的两个值中第一个值的列名。该值显示为该数据行的第一个输入行。第一行专用作数据摘要，但它是可选项。另请参阅 android:detailColumn。
android:detailColumn
从数据行检索的两个值中第二个值的列名。该值显示为该数据行的第二个输入行。另请参阅 android:summaryColumn。

其他联系人提供程序功能

除了上文描述的主要功能外，联系人提供程序还为处理联系人数据提供了下列实用功能：

  • 联系人群组
  • 照片功能

联系人群组

联系人提供程序可以选择性地为相关联系人集合添加组数据标签。如果与某个用户账号关联的服务器想要维护组，则与该账号的账号类型对应的同步适配器应在联系人提供程序与服务器之间传送组数据。当用户向服务器添加新联系人，然后将其放入新组时，同步适配器必须将该新组添加到 ContactsContract.Groups 表中。原始联系人所属的一个或多个组使用 ContactsContract.CommonDataKinds.GroupMembership MIME 类型存储在 ContactsContract.Data 表中。

如果您设计的同步适配器会将服务器中的原始联系人数据添加到联系人提供程序，并且您不使用组，则需要告知提供程序使您的数据可见。在用户向设备添加账号时执行的代码中，更新联系人提供程序为该账号添加的 ContactsContract.Settings 行。在此行中，将 Settings.UNGROUPED_VISIBLE 列的值设置为 1。执行此操作后，即使您不使用组，联系人提供程序也会让您的联系人数据始终可见。

联系人照片

ContactsContract.Data 表会使用 MIME 类型 Photo.CONTENT_ITEM_TYPE，以行的形式存储照片。该行的 CONTACT_ID 列链接到其所属原始联系人的 _ID 列。ContactsContract.Contacts.Photo 类定义了 ContactsContract.Contacts 的子表，该表中包含联系人主要照片（联系人的主要原始联系人的主要照片）的照片信息。同样，ContactsContract.RawContacts.DisplayPhoto 类定义了 ContactsContract.RawContacts 的子表，其中包含原始联系人主要照片的照片信息。

ContactsContract.Contacts.Photo 和 ContactsContract.RawContacts.DisplayPhoto 参考文档包含检索照片信息的示例。没有可用于检索原始联系人主要缩略图的便捷类，但您可以向 ContactsContract.Data 表发送查询，选择原始联系人的 _ID、Photo.CONTENT_ITEM_TYPE 和 IS_PRIMARY 列以查找原始联系人的主要照片行。

联系人的社交流数据也可能包含照片。这些照片存储在 android.provider.ContactsContract.StreamItemPhotos 表中，社交流照片部分对该表进行了更详细的介绍。