ContactsManager: select() 方法

语法

select(properties)
select(properties, options)

参数

properties

一个由 字符串 组成的数组，用于定义要从联系人中检索哪些信息。允许的值如下：

• 'name'：联系人的姓名。
• 'tel'：联系人的电话号码。
• 'email'：联系人的电子邮件地址。
• 'address'：联系人的邮寄地址。
• 'icon'：联系人的头像。

options 可选

选项如下：

multiple

一个布尔值，允许选择多个联系人。默认为 false。

返回值

返回一个 Promise，该 Promise 解析为一个包含联系人信息的对象数组。每个对象代表一个单独的联系人，可能包含以下属性：

地址

一个 数组，包含 ContactAddress 对象，每个对象包含一个唯一物理地址的详细信息。

电子邮件

包含电子邮件地址的字符串数组。

icon

包含个人图像的 Blob 对象数组。

name

包含个人姓名唯一标识的字符串数组。

电话

包含个人电话号码唯一标识的字符串数组。

异常

InvalidStateError DOMException

如果浏览上下文不是顶层上下文，如果联系人选择器显示了一个已存在的联系人选择器标志（因为一次只能存在一个选择器），或者如果启动联系人选择器失败，则返回此错误。

SecurityError DOMException

如果该方法不是由 用户激活 触发的，则返回此错误。

TypeError

如果 properties 为空，或者指定的任何属性不受支持，则返回此错误。

安全

需要 瞬时激活。用户必须与页面或 UI 元素进行交互，此功能才能正常工作。

示例

基本示例

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

然后定义一个异步函数，该函数使用 select() 方法向用户展示联系人选择器界面并处理选择的结果。handleResults() 是一个由开发者定义的函数。

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.
  }
}

仅使用支持的属性进行选择

以下示例使用 getProperties() 来确保只传递受支持的属性。否则，select() 可能会抛出 TypeError。handleResults() 是一个由开发者定义的函数。

const supportedProperties = await navigator.contacts.getProperties();

async function getContacts() {
  try {
    const contacts = await navigator.contacts.select(supportedProperties);
    handleResults(contacts);
  } catch (ex) {
    // Handle any errors here.
  }
}

规范

浏览器兼容性