网页版联系人选择器

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

什么是联系人选择器 API?

从(几乎)黎明起,就已成为 iOS/Android 应用的一项功能,让用户在移动设备上访问通讯录。这是 Web 开发者向我反映的最常见功能请求之一,这往往是他们构建 iOS/Android 应用的主要原因。

Contact Picker API 规范适用于搭载 Android M 或更高版本的 Chrome 80。它是一个按需 API,允许用户从联系人列表中选择条目并与网站分享所选条目的有限详细信息。这样一来,用户便可以在需要时只分享自己需要的内容,还可以更轻松地与亲朋好友联系并保持联系。

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

使用联系人选择器 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 并在其中显示联系人选择器,以便用户选择要与网站分享的联系人。选择要共享的内容并点击 Done 后,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 会返回一个空数组。(我在用户控制部分介绍了用户如何选择属性。)

例如,如果网站请求了 nameemailtel,并且用户选择了姓名字段中包含数据的一位联系人,并提供了两个电话号码,但没有电子邮件地址,则返回的响应将为:

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

安全与权限

Chrome 团队按照控制对强大网络平台功能的访问权限中定义的核心原则(包括用户控制、透明度和工效学设计)设计和实现了 Contact Picker API。我会逐一介绍。

用户控制

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

屏幕截图,用户可以选择要共享的属性。
用户可以选择不共享某些媒体资源。在此屏幕截图中,用户已取消选中“电话号码”按钮。虽然网站要求用户提供电话号码,但系统不会将其透露给网站。

您无法批量选择所有联系人,从而鼓励用户仅选择他们需要针对该特定网站分享的联系人。用户还可以通过切换选择器顶部的属性按钮来控制与网站共享哪些属性。

透明度

为了指明要共享哪些详细联系信息,选择器始终会显示联系人的姓名和图标,以及网站请求的任何属性。例如,如果网站请求 nameemailtel,则选择器中都会显示所有这三个属性。或者,如果网站仅请求 tel,选择器将仅显示姓名和电话号码。

用于请求所有房源的网站的选择器屏幕截图。
选择器,网站请求 nameemailtel,已选择 1 位联系人。
用于仅请求电话号码的网站的选择器屏幕截图。
选择器,仅请求 tel 的网站,已选择 1 位联系人。
长按联系人时选择器的屏幕截图。
长按某个联系人的结果。

长按某个联系人会显示该联系人选中后将共享的所有信息。(请参见 Cheshire Cat 联系人图片。)

不存留权限

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

反馈

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

实施方面有问题?

您是否发现了 Chrome 实现方面的错误?或者实现方式是否不同于规范?

  • https://new.crbug.com 上提交 bug。请务必提供尽可能多的详细信息,提供重现 bug 的简单说明,并将组件设为 Blink>ContactsGlitch 非常适合用于分享快速轻松地重现的问题。

打算使用该 API?

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

实用链接

此致

非常感谢,感谢实现该功能的 Finnur Thorarinsson 和 Rayan Kanso,以及我为演示而付诸东流并重构了代码的 Peter Beverloo。

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