Contact Picker API - 允许用户从其联系人列表中选择联系人

Contact Picker API（联系人选择器 API）允许用户从其联系人列表中选择联系人，并与网站或应用程序共享所选条目的有限详细信息。

注意： 此 API 在 Web Workers 中不可用（未通过 WorkerNavigator 公开）。

不要将 Contact Picker API 与不推荐使用的 Contact API 混淆。

联系人选择器 API 概念和用法

长期以来，对联系人的访问一直是原生应用程序中的一项功能。Contacts Picker API 将该功能引入了 Web 应用程序。

用例包括选择联系人通过电子邮件或聊天应用程序发送信息，选择联系人的电话号码用于 IP 语音（VOIP），或发现已经加入社交平台的联系人。用户代理还可以为用户设备上的其他应用程序提供一致的体验。

当调用 ContactsManager 接口的 select 方法时，用户会看到一个联系人选择器，然后他们可以选择联系人信息与网络应用共享。在授予显示联系人选择器的权限之前，需要用户互动，对联系人的访问不是持久的；用户必须在每次应用程序提出请求时授予访问权限。

该 API 仅可从安全的顶级浏览上下文中使用，并且非常谨慎地考虑了联系人数据的敏感性和隐私。用户需要选择要分享数据，并且只允许选定的联系人的特定数据，不能访问其他联系人的任何数据。

用户有责任选择要共享的数据，并且程序只能访问选择的联系人的数据，而不能访问其他联系人的任何数据。

接口

ContactsManager

ContactsManager 接口为用户提供了一种选择并与 Web 应用程序共享联系人的有限详细信息的方法。

Navigator.contacts

返回一个 ContactsManager 对象实例，从中可以访问所有其他功能。

实例

功能检测

以下代码检查是否支持联系人选择器 API。

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

检查支持的属性

以下异步函数使用 getProperties 方法检查支持的属性。

async function checkProperties() {
  const supportedProperties = await navigator.contacts.getProperties();
  if (supportedProperties.includes('name')) {
    // 运行支持名称的相关代码
  }
  if (supportedProperties.includes('email')) {
    // 运行支持邮箱的相关代码
  }
  if (supportedProperties.includes('tel')) {
    // 运行支持电话号码的相关代码
  }
  if (supportedProperties.includes('address')) {
    // 运行支持地址的相关代码
  }
  if (supportedProperties.includes('icon')) {
    // 运行支持地址的相关代码
  }
}

选择联系人

下面的实例设置要为每个联系人检索的属性数组，并设置选项对象以允许选择多个联系人。

然后定义一个异步函数，该函数使用 select() 方法为用户提供联系人选择器界面并处理选定的结果。

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

async function getContacts() {
  try {
      const contacts = await navigator.contacts.select(props, opts);
      handleResults(contacts);
  } catch (ex) {
      // 在这里处理任何错误。
  }
}

handleResults() 是开发人员定义的函数。

规范

规范	状态	备注
Unknown	Unknown	初始定义。

桌面浏览器兼容性

移动浏览器兼容性

相关链接

• Web 网络联系人选择器
• glitch 的联系人选择器演示