在黄色背景上的电话。

Web 联系人选取器

Contact Picker API 为用户提供了一种从他们的联系人列表中共享联系人的简单方法。

— 更新日期
Available in: English、Português、Русский、日本語和한국어
Pete LePage
Pete LePage
TwitterGitHubGlitchHomepage
本页内容

什么是 Contact Picker API? {: #what }？ #

<style> #video-demo { max-height: 600px; } </style>

（几乎）自从出现以来，在移动设备上访问用户的联系人一直是 iOS/Android 应用的功能之一。这是我从 Web 开发人员那里听到的最常见的功能请求之一，并且通常是他们构建 iOS/Android 应用的关键原因。

Android 的 Chrome 80 提供了一个按需访问的 Contact Picker API，它可以使用户从联系人列表中选择条目，并与网站共享所选条目的有限详细信息。它允许用户在需要的时候只分享他们想分享的内容，并让用户更容易联系到他们的朋友和家人。

例如，基于 Web 的电子邮件客户端可以使用 Contact Picker API 来选择电子邮件的收件人。 IP 语音应用可以查找要呼叫的电话号码。社交网络也可以帮助用户发现哪些朋友已经加入了该网络。

当前状态 #

步骤状态
1. 创建解释文档已完成
2. 创建规范初稿已完成
3. 收集反馈并对设计进行迭代已完成
4. 极早期试验已完成
5. 发布Chrome 80
仅在 Android 上提供。

使用 Contact Picker API #

Contact Picker API 需要使用一个带有 options 参数的方法调用，该参数会指定您需要的联系信息类型。第二个方法会告诉您底层系统将提供哪些信息。

功能检测 #

要检查是否支持 Contact 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.
}

联系人选取器 API 只能从安全的顶级浏览上下文中调用，而且与其他功能强大的 API 一样，它需要用户手势。

检测可用属性 #

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

请记住，属性并不总是可用的，并且可能会添加新的属性。今后其他平台和联系人来源可能会限制共享哪些属性。

处理结果 #

Contact Picker API 返回一组联系人，每个联系人都包含一组请求的属性。如果联系人没有所请求属性的数据，或者用户选择不分享特定的属性，那么 API 将返回一个空数组。（我在用户控制部分介绍了用户选择属性的方式。）

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

[{
  "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 上提交错误。确保提供尽可能多的详细信息，提供重现该错误的简单说明，并将 Components 设置为 Blink>NFC。Glitch 非常适合共享快速简单的重现。

打算使用此 API？ #

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

实用链接 #

鸣谢 #

非常感谢实现该功能的 Finnur Thorarinsson 和 Rayan Kanso ，以及我在演示中参考了其代码的 Peter Beverloo。

附注：我在联系人选取器中使用的名字是小说《爱丽丝梦游仙境》中的角色。

Last updated: — Improve article
Return to all articles
分享