ContactsManager：select() 方法

properties

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

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

options 可选

选项如下

multiple

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

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

address

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

email

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

icon

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

name

字符串数组，每个字符串包含个人的唯一名称。

tel

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

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