此页面由 Cloud Translation API 翻译。

联系人提供程序

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

本指南介绍了以下内容：

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

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

联系人提供程序结构

联系人提供程序是一个 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）。

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

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

流量

如前所述，原始联系人的数据存储在 ContactsContract.Data 行中，该行链接到原始联系人的 _ID 值。这允许单个原始联系人拥有多个相同类型数据的实例，例如电子邮件地址或电话号码。例如，如果 emilyd@gmail.com（与 Google 帐号 emilyd@gmail.com 关联的 Thomas Higginson 的原始联系人行）的“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 的通用列已正式发布，另外 4 个通用列 SYNC1 到 SYNC4 只应由同步适配器使用。无论行包含的数据类型如何，通用列名称常量始终有效。

DATA1 列已编入索引。联系人提供程序会始终将此列用于其预期会成为最频繁查询目标的数据。例如，在电子邮件行中，此列包含实际电子邮件地址。

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

类型专用列名称

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

例如，ContactsContract.CommonDataKinds.Email 类为 MIME 类型为 Email.CONTENT_ITEM_TYPE 的 ContactsContract.Data 行定义了类型专用列名称常量。该类包含电子邮件地址列的 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 值以响应汇总或同步。即使发生这种情况，内容 URI CONTENT_LOOKUP_URI 与联系人的 LOOKUP_KEY 相结合仍会指向该联系人行，因此您可以使用 LOOKUP_KEY 保留指向“收藏”联系人的链接，等等。此列具有自己的格式，与 _ID 列的格式无关。

图 3 显示了这三个主表的相互关系。

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

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

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

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

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

ContactsContract.Contacts.CONTENT_FREQUENT_URI
ContactsContract.Contacts.CONTENT_STREQUENT_URI
ContactsContract.Contacts.CONTENT_STREQUENT_FILTER_URI
CONTENT_FILTER_URI（仅影响 Email、Phone、Callable 和 Contactables 数据类型）
ENTERPRISE_CONTENT_FILTER_URI（仅影响 Email、Phone 和 Callable 数据类型）

如果您的应用要访问或更新这些字段或 API，请使用其他方法。例如，您可以使用私有 content provider 或者存储在您的应用或后端系统中的其他数据来实现某些用例。

如需验证应用的功能不受此变更的影响，您可以手动清除这些数据字段。为此，请在搭载 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 显示了联系人提供程序如何适应联系人数据流。在标有“同步适配器”的框中，每个适配器都按其帐号类型进行标记。

图 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 应用更新行时，联系人提供程序会自动设置该值。修改原始联系人表或数据表的同步适配器应始终将字符串 `CALLER_IS_SYNCADAPTER` 附加到其使用的内容 URI。这可以防止提供程序将行标记为脏行。否则，即使服务器是修改的来源，同步适配器修改也会显示为本地修改，并会发送到服务器。
`ContactsContract.RawContacts`	`DIRTY`	“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 应用界面中不应可见。	此列用于兼容那些允许用户隐藏特定群组中联系人的服务器。
`ContactsContract.Groups`	`GROUP_VISIBLE`	“1”：系统允许此群组中的联系人在应用 UI 中处于可见状态。	此列用于兼容那些允许用户隐藏特定群组中联系人的服务器。
`ContactsContract.Settings`	`UNGROUPED_VISIBLE`	“0”：对于此帐号和帐号类型，未归入组的联系人在 Android 应用界面中不可见。	默认情况下，如果联系人的所有原始联系人都未归入组，则这些联系人不可见（原始联系人的组成员资格通过 `ContactsContract.Data` 表中的一个或多个 `ContactsContract.CommonDataKinds.GroupMembership` 行指示）。通过在帐号类型和帐号的 `ContactsContract.Settings` 表格行中设置此标志，您可以强制显示未加入群组的联系人。此标志的一个用途是显示不使用群组的服务器中的联系人。
`ContactsContract.Settings`	`UNGROUPED_VISIBLE`	“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，即“主 activity”和“detail”。主 activity 显示联系人行列表；当用户选择一行时，此 activity 会将其 ID 发送到详情 activity。详情 activity 使用 ContactsContract.Contacts.Entity 显示与所选联系人关联的所有原始联系人中的所有数据行。

此代码段取自“detail”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());

接下来，该代码为显示名称行、电话号码行和电子邮件地址行创建数据行。

每个操作构建器对象都使用 withValueBackReference() 来获取 RAW_CONTACT_ID。该引用指向第一次操作中的 ContentProviderResult 对象，第一次操作添加原始联系人行并返回其新的 _ID 值。因此，每个数据行都会通过其 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 行时使用乐观并发控制，请按以下步骤操作：

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

如果在您读取原始联系人行之后，在您读取该行与尝试修改该行之间有其他操作更新了该行，则“断言”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 类型和数据值，而 ContactsContract.Intents.Insert 参考文档中列出了可与 putExtra() 一起使用的 extra 值：

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

任务	操作	流量	MIME 类型	备注
从列表中选择联系人	`ACTION_PICK`	以下各项中的一项： `Contacts.CONTENT_URI`，用于显示联系人列表。 `Phone.CONTENT_URI`，显示原始联系人的电话号码列表。 `StructuredPostal.CONTENT_URI`，显示原始联系人的邮政地址列表。 `Email.CONTENT_URI`，显示原始联系人的电子邮件地址列表。	未使用	显示原始联系人列表或一位原始联系人的数据列表，具体取决于您提供的内容 URI 类型。调用 `startActivityForResult()`，它会返回所选行的内容 URI。该 URI 的格式为附加了该行的 `LOOKUP_ID` 的表的内容 URI。设备“通讯录”应用会在 Activity 的生命周期内将读取和写入权限委托给此内容 URI。如需了解详情，请参阅 Content Provider 基础知识指南。
插入新原始联系人	`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 值。当用户点击 Done 保存修改时，您的 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.CommonDataKinds.StructuredName 行的 ContactsContract.RawContacts 行可能会导致在聚合时出现问题。
始终将新的 ContactsContract.Data 行关联到其父级 ContactsContract.RawContacts 行。: 未关联到 ContactsContract.RawContacts 的 ContactsContract.Data 行不会在设备的联系人应用中显示，并且可能会导致同步适配器出现问题。
仅更改您拥有的原始联系人的数据。: 请注意，联系人提供程序所管理的数据通常来自多个不同帐号类型/在线服务。您需要确保您的应用仅修改或删除属于您的行的数据，并且仅通过由您控制的帐号类型和名称插入数据。
始终将 ContactsContract 及其子类中定义的常量用于授权方、内容 URI、URI 路径、列名称、MIME 类型和 TYPE 值。: 使用这些常量有助于避免错误。如有任何常量被废弃，您还会收到编译器警告。

自定义数据行

通过创建和使用自己的自定义 MIME 类型，您可以在 ContactsContract.Data 表中插入、修改、删除和检索您自己的数据行。您的行只能使用 ContactsContract.DataColumns 中定义的列，但您可以将您自己的类型专用列名称映射到默认列名称。在设备的联系人应用中，会显示各行的数据，但无法修改或删除数据，用户也无法添加其他数据。如需允许用户修改您的自定义数据行，您必须在自己的应用中提供编辑器 Activity。

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

如需详细了解自定义 MIME 类型，请参阅创建 Content Provider 指南。

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

联系人提供程序专门设计用于处理设备与在线服务之间的联系人数据同步。这样一来，用户可以将现有数据下载到新设备，以及将现有数据上传到新帐号。同步还可确保用户拥有最新的数据，而无需考虑数据增加和更改的来源。同步的另一个优势是，即使设备未连接到网络，联系人数据也可用。

尽管您可以通过多种方式实现同步，但 Android 系统提供了一个插件同步框架，可自动完成以下任务：

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

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

同步适配器类和文件

您要将同步适配器实现为 AbstractThreadedSyncAdapter 的子类，并将其作为 Android 应用的一部分进行安装。系统通过您的应用清单中的元素以及清单指向的特殊 XML 文件来了解同步适配器。该 XML 文件定义在线服务的帐号类型和 content provider 的授权，它们共同对适配器进行唯一标识。在用户为同步适配器的帐号类型添加帐号并为与同步适配器同步的内容提供程序启用同步之前，同步适配器不会变为活动状态。完成后，系统会开始管理适配器，并在必要时调用它，以在 content provider 和服务器之间进行同步。

注意：如果使用帐号类型作为同步适配器的标识的一部分，系统就可以检测访问同一组织不同服务的同步适配器，并将其归为一组。例如，Google 在线服务的同步适配器都具有相同的帐号类型 com.google。当用户向其设备添加 Google 帐号时，已安装的所有 Google 服务同步适配器会一起列出；列出的每个同步适配器都会与设备上不同的 content provider 同步。

由于大多数服务要求用户先验证其身份才能访问数据，因此 Android 系统提供了一个身份验证框架，该框架与同步适配器框架类似，并且经常与其结合使用。该身份验证框架使用插件身份验证器，它们是 AbstractAccountAuthenticator 的子类。身份验证器通过以下步骤验证用户的身份：

收集用户的姓名、密码或类似信息（用户的凭据）。
将凭据发送到服务
检查服务的回复。

如果服务接受了凭据，身份验证器便可以存储凭据以供日后使用。由于插件身份验证器框架的存在，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，以及该网络服务的帐号类型。
可选：身份验证器的 <meta-data> 元素指向 XML 文件 res/xml/authenticator.xml。而该文件会指定此身份验证器支持的帐号类型，以及身份验证过程中出现的界面资源。在此元素中指定的帐号类型必须与为同步适配器指定的帐号类型相同。

社交流数据

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

社交流文本

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

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

android.provider.ContactsContract.StreamItemsColumn#ACCOUNT_TYPE

必需。与此流项关联的原始联系人的用户账号类型。请记得在插入流项目时设置此值。

android.provider.ContactsContract.StreamItemsColumn#ACCOUNT_NAME

必需。与此流项关联的原始联系人的用户账号名称。请记得在插入流项目时设置此值。

标识符列

必需。插入流项时，您必须插入以下标识符列：

android.provider.ContactsContract.StreamItemsColumn#CONTACT_ID：此流项关联的联系人的 android.provider.Base 列#_ID 值。
android.provider.ContactsContract.StreamItemsColumn#CONTACT_LOOKUP_KEY：此流项目关联的联系人的 android.provider.ContactsContract.Contacts 列#LOOKUP_KEY 值。
android.provider.ContactsContract.StreamItemsColumn#RAW_CONTACT_ID：此流项关联的原始联系人的 android.provider.Base 列#_ID 值。

android.provider.ContactsContract.StreamItemsColumn#COMMENTS

可选。存储您可以在流项目开头显示的摘要信息。

android.provider.ContactsContract.StreamItemsColumn#TEXT

流项目的文本，可以是该项目的来源发布的内容，也可以是对生成该流项目的某项操作的说明。此列可以包含可由 fromHtml() 呈现的任何格式设置和嵌入式资源图片。提供程序可能会截断或省略较长的内容，但会尽量避免破坏标记。

android.provider.ContactsContract.StreamItemsColumn#TIMESTAMP

包含流项的插入或更新时间的文本字符串，以从公元纪年开始计算的毫秒数表示。此列由插入或更新流项目的应用负责维护；联系人提供程序不会自动维护此列。

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

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

社交流照片

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

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

使用社交流表

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

这些表需要额外的访问权限。如需读取它们的数据，您的应用必须具有 android.Manifest.permission#READ_SOCIAL_STREAM 权限。如需修改它们，您的应用必须具有 android.Manifest.permission#WRITE_SOCIAL_STREAM 权限。
对于 android.provider.ContactsContract.StreamItems 表，为每位原始联系人存储的行数有限。达到此上限后，联系人提供程序便会自动删除 android.provider.ContactsContract.StreamItemsColumn#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 的一个子表，其中包含单个流项的照片行。

社交流交互

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

通过使用同步适配器将您的社交网络服务同步到联系人提供程序，您可以检索用户联系人的近期活动，并将其存储在 android.provider.ContactsContract.StreamItems 表和 android.provider.ContactsContract.StreamItemPhotos 表中，以供日后使用。
除了定期同步外，您还可以在用户选择要查看的联系人时触发同步适配器以检索其他数据。这样，您的同步适配器就可以检索该联系人的高分辨率照片和最近的信息流项。
通过在设备的联系人应用和联系人提供程序中注册通知，您可以在查看联系人时收到 intent，并在此时通过您的服务更新联系人的状态。与使用同步适配器执行完全同步相比，这种方法可能更快，占用的带宽也更少。
用户可以在查看设备的联系人应用中查看某位联系人时，将其添加到您的社交网络服务。您可以使用“邀请联系人”功能来启用此功能，该功能可组合使用向广告联盟添加现有联系人的 activity 和为设备的联系人应用和联系人提供程序提供应用详细信息的 XML 文件来实现。

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

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

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

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

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

<ContactsAccountType> 元素部分对 <ContactsAccountType> 元素进行了更详细的介绍。

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

在邀请联系人访问您的社交网络网站时，用户无需离开设备的联系人应用。相反，您可以让设备“通讯录”应用发送一个 intent，以邀请联系人加入您的某个 activity。要进行此设置，请执行以下操作：

在项目的 res/xml/ 目录中创建一个名为 contacts.xml 的文件。如果您已有此文件，可以跳过此步骤。
在此文件中，添加元素 <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">。如果此元素已存在，您可以跳过此步骤。
添加以下属性：
- 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 的完全限定类名。
inviteContactActionLabel: 为 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 表中。有关该表的详细介绍，请参阅社交信息流照片部分。

联系人提供程序

联系人提供程序结构

原始联系人

重要的原始联系人列

备注

原始联系人数据来源

流量

描述性列名称

通用列名称

类型专用列名称

类型专用列名称类

通讯录

来自同步适配器的数据

所需权限

用户个人资料

Kotlin

Java

联系人提供程序元数据

联系人提供程序访问

查询实体

Kotlin

Java

批量修改

挂起点

修改向后引用

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

通过 Intent 执行检索和修改

Kotlin

Java

数据完整性

自定义数据行

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

同步适配器类和文件

同步适配器实现

社交流数据

社交流文本

社交流照片

使用社交流表

社交流交互

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

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

contacts.xml 引用

<ContactsAccountType> 元素

<ContactsDataKind> 元素

其他联系人提供程序功能

联系人组

联系人照片