网页版联系人选择器

Contact Picker API 可让用户轻松分享联系人列表中的联系人。

Pete LePage

Contact Picker API 是什么？

从 iOS/Android 应用诞生之初，访问移动设备上的用户通讯录就一直是其一项功能。这是 Web 开发者向我提出的最常见的功能请求之一，也是他们构建 iOS/Android 应用的主要原因。

Contact Picker API 规范是 Android M 或更高版本的 Chrome 80 中提供的一项按需 API，可让用户从联系人列表中选择条目，并与网站共享所选条目的有限详细信息。它让用户能够在需要时分享所需内容，并更轻松地与亲朋好友联系互动。

例如，基于网络的电子邮件客户端可以使用 Contact Picker API 选择电子邮件的收件人。语音 over IP 应用可以查询要拨打的电话号码。或者，社交网络可以帮助用户发现哪些好友已加入。

使用 Contact Picker API

Contact Picker API 需要使用一个选项参数的方法调用，该参数用于指定您想要的联系信息类型。第二种方法可告知您底层系统将提供哪些信息。

功能检测

如需检查是否支持 Contacts Picker API，请使用以下命令：

const supported = ('contacts' in navigator && 'ContactsManager' in window);

此外，在 Android 设备上，联系人选择器需要 Android M 或更高版本。

打开联系人选择器

Contact Picker API 的入口点是 navigator.contacts.select()。调用此方法时，它会返回一个 Promise 并显示联系人选择器，以便用户选择要与网站共享的联系人。选择要共享的内容并点击完成后，promise 会解析为用户选择的联系人数组。

调用 select() 时，您必须提供要作为第一个参数返回的属性数组（允许的值为 'name'、'email'、'tel'、'address' 或 'icon'），并可选择是否可以选择多个联系人作为第二个参数。

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
  const contacts = await navigator.contacts.select(props, opts);
  handleResults(contacts);
} catch (ex) {
  // Handle any errors here.
}

只能从安全的顶级浏览上下文调用 Contacts Picker API，并且与其他强大的 API 一样，它需要用户手势。

检测可用媒体资源

如需检测哪些属性可用，请调用 navigator.contacts.getProperties()。它会返回一个 promise，该 promise 会解析为一个字符串数组，指示哪些属性可用。例如：['name', 'email', 'tel', 'address']。您可以将这些值传递给 select()。

请注意，房源并非始终可用，并且可能会添加新房源。未来，其他平台和联系人来源可能会限制共享哪些房源。

处理结果

Contact Picker API 会返回一个联系人数组，每个联系人包含一个请求的属性数组。如果联系人没有请求的媒体资源的数据，或者用户选择不分享特定媒体资源，API 会返回一个空数组。（我在用户控制部分介绍了用户如何选择房源。）

例如，如果某个网站请求 name、email 和 tel，并且用户选择了一个联系人，该联系人姓名字段中包含数据，提供了两个电话号码，但没有电子邮件地址，则返回的响应将如下所示：

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

安全与权限

Chrome 团队使用控制对强大 Web 平台功能的访问权限中定义的核心原则（包括用户控制、透明度和人体工学）设计和实现了 Contact Picker API。我会逐一进行说明。

用户控制

您可以通过选择器访问用户的联系人，并且只能在安全的顶级浏览上下文中通过用户手势调用它。这样可确保网站无法在网页加载时显示选择器，也无法在没有任何上下文的情况下随机显示选择器。

屏幕截图：用户可以选择要共享的媒体资源。
用户可以选择不共享某些媒体资源。在此屏幕截图中，用户已取消选中“电话号码”按钮。即使网站要求提供电话号码，我们也不会与该网站分享这些信息。

系统不提供批量选择所有联系人的选项，因此建议用户仅选择他们需要与该特定网站分享的联系人。用户还可以通过切换选择器顶部的媒体资源按钮来控制要与网站共享哪些媒体资源。

透明度

为明确系统要分享哪些联系详情，选择器始终会显示联系人的姓名和图标，以及网站请求的任何属性。例如，如果某个网站请求 name、email 和 tel，则选择器中会显示这三个属性。或者，如果某个网站仅请求 tel，则选择器只会显示姓名和电话号码。

请求所有媒体资源的网站的选择器屏幕截图。
选择器，网站请求 name、email 和 tel，选择了一位联系人。
仅请求电话号码的网站的选择器屏幕截图。
选择器，网站仅请求 tel，选择了一位联系人。
长按联系人时选择器的屏幕截图。
长按联系人后显示的结果。

长按某个联系人即可显示选择该联系人后系统会分享的所有信息。（请参阅 Cheshire Cat 联系人图片。）

无权限持久性

对联系人信息的访问是按需的，不会持久保留。每当网站想要访问时，都必须使用用户手势调用 navigator.contacts.select()，并且用户必须单独选择要与网站分享的联系人。

反馈

Chrome 团队希望了解您使用 Contact Picker API 的体验。

实现方面存在问题？

您是否发现了 Chrome 实现中的 bug？还是实现与规范不同？

  • 请访问 https://new.crbug.com 提交 bug。请务必尽可能提供详细信息，提供重现 bug 的简单说明，并将组件设置为 Blink>Contacts。故障非常适合分享快速轻松的问题重现。

打算使用该 API？

您打算使用 Contacts Picker API 吗？您的公开支持有助于 Chrome 团队确定功能的优先级，并向其他浏览器供应商表明支持这些功能的重要性。

实用链接

谢谢

非常感谢负责实现此功能的 Finnur Thorarinsson 和 Rayan Kanso，以及 Peter Beverloo，我厚颜无耻地盗用了他的代码并对其进行了重构，以便在演示中使用。

（附注）我联系人选择器中的名字是《爱丽丝梦游仙境》中的人物。