联系人选择器 API

可用性有限

此功能不是基线功能，因为它在一些最广泛使用的浏览器中不起作用。

安全上下文：此功能仅在安全上下文（HTTPS）中可用，在某些或所有支持的浏览器中。

实验性：这是一个实验性技术
在生产环境中使用之前，请仔细检查浏览器兼容性表。

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

注意：此 API不可用于Web 工作线程（通过WorkerNavigator未公开）。

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

访问联系人一直是原生应用程序中可用的功能。联系人选择器 API 将此功能引入 Web 应用程序。

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

当调用select方法时，ContactsManager接口会向用户显示一个联系人选择器，用户可以在其中选择要与 Web 应用程序共享的联系人信息。在授予显示联系人选择器的权限之前，需要用户交互，并且对联系人的访问权限不是永久性的；用户必须在应用程序每次发出请求时都授予访问权限。

此 API 仅在安全的顶级浏览上下文环境中可用，并且非常谨慎地考虑了联系人数据的敏感性和隐私性。用户负责选择要共享的数据，并且只允许共享所选联系人的特定数据，而不允许访问任何其他联系人的数据。

接口

ContactAddress

表示物理地址。

ContactsManager

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

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

示例

功能检测

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

js
const supported = "contacts" in navigator;

检查支持的属性

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

js
async function checkProperties() {
  const supportedProperties = await navigator.contacts.getProperties();
  if (supportedProperties.includes("name")) {
    // run code for name support
  }
  if (supportedProperties.includes("email")) {
    // run code for email support
  }
  if (supportedProperties.includes("tel")) {
    // run code for telephone number support
  }
  if (supportedProperties.includes("address")) {
    // run code for address support
  }
  if (supportedProperties.includes("icon")) {
    // run code for avatar support
  }
}

选择联系人

以下示例设置了一个属性数组，用于检索每个联系人的属性，以及一个选项对象，用于允许选择多个联系人。

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

js
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) {
    // Handle any errors here.
  }
}

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

规范

规范
联系人选择器 API
# contacts-manager

浏览器兼容性

BCD 表仅在启用 JavaScript 的浏览器中加载。

另请参阅