能力中的 API
Contact Picker API
发布于
Contact Picker API(navigator.contacts)让用户从设备通讯录中选择要分享给页面的联系人。浏览器显示选择器,只返回用户同意分享的联系人和属性(name、email、tel、address、icon)。
授权不会保留,用户每次调用都要重新选择;API 不提供读取整个通讯录的方式,multiple: true 只能一次返回用户选中的多个联系人。
Android 上的 Chrome 80(Android 6 及以上)是唯一的稳定实现;address 与 icon 在 Chrome 84 加入。桌面 Chrome、Edge 与 Firefox 不暴露 navigator.contacts。iOS 14.5 的 Safari 把它放在「设置 > Safari 浏览器 > 高级」下名为「Contact Picker API」的实验性功能开关之后(默认关闭);Samsung Internet 14.0 至 21 暴露了接口,但打开选择器时失败(BCD api.ContactsManager)。MDN 将该 API 标记为实验性且不属于 Baseline。
navigator.contacts.select(properties)navigator.contacts.select(properties, options)navigator.contacts.getProperties()select() 返回 Promise<sequence<ContactInfo>>,用户取消时以空数组兑现。getProperties() 返回 Promise<sequence<ContactProperty>>,列出设备能提供的属性。两者都在只暴露于 Window 的 [SecureContext] 接口上;select() 还要求顶层浏览上下文与瞬时用户激活,getProperties() 两者都不要求。
select() 接受要请求的属性列表和一个选项;getProperties() 不接受参数。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
properties |
sequence<ContactProperty> |
是 | "name"、"email"、"tel"、"address"、"icon" 中的一个或多个。空列表会拒绝;浏览器不支持的值会拒绝。 |
options.multiple |
boolean |
否 | 默认 false:选择器只允许选一个联系人。true 允许多选。 |
返回的 ContactInfo 只包含请求过的成员。一个联系人可能有多个值,所以成员均为序列。
| 成员 | 类型 | 出现条件 |
|---|---|---|
name |
sequence<DOMString> |
请求了 "name" |
email |
sequence<DOMString> |
请求了 "email" |
tel |
sequence<DOMString> |
请求了 "tel" |
address |
sequence<ContactAddress> |
请求了 "address";ContactAddress 与 PaymentAddress 同形(country、addressLine、region、city、postalCode 等) |
icon |
sequence<Blob> |
请求了 "icon" |
用户在选择器里选择不分享的成员,与联系人本来就没有的成员无法区分:两者都返回空序列。
select() 以三个名称之一拒绝;getProperties() 不会拒绝。
| 异常 | 条件 |
|---|---|
InvalidStateError |
调用方不是顶层 traversable(例如在 iframe 中);该 navigable 已有选择器在显示;或呈现选择器、读取联系人源失败。 |
SecurityError |
调用时没有瞬时用户激活。 |
TypeError |
properties 为空,或包含联系人源支持集合之外的属性(Chrome 80 至 83 中的 "address" 与 "icon")。 |
Chromium 在最后一种 InvalidStateError 情形上有偏差:Android 选择器无法启动时,它以 TypeError: Unable to open a contact selector 拒绝。
桌面浏览器和未开启功能开关的 iOS Safari 没有这个 API。按 Chrome 文档,用 'contacts' in navigator && 'ContactsManager' in window 检测支持情况,并准备普通表单字段供用户手动输入。
选一个收件人邮箱,缺少支持时改为手动输入
链接到“选一个收件人邮箱,缺少支持时改为手动输入”一节在 click 处理函数内调用 select()。空结果表示用户取消,不算错误;API 缺失时显示 <input type="email">,保留输入邮箱的功能。
const pickButton = document.querySelector('#pick-recipient');const manualField = document.querySelector('#recipient-email');
const supported = 'contacts' in navigator && 'ContactsManager' in window;pickButton.hidden = !supported;manualField.hidden = supported;
pickButton.addEventListener('click', async () => { try { const [contact] = await navigator.contacts.select(['name', 'email']); if (!contact) return; // 用户取消 const email = contact.email[0]; if (!email) { manualField.hidden = false; // 该联系人没有邮箱 return; } manualField.value = email; } catch (err) { console.error(`${err.name}: ${err.message}`); manualField.hidden = false; }});选择成功后,contact.email[0] 仍可能是 undefined。保留 DOM 中的手动输入框,供用户补填。
按设备能返回的属性裁剪请求
链接到“按设备能返回的属性裁剪请求”一节getProperties() 在你请求之前告诉你 address 或 icon 是否可用;请求不受支持的属性会让整个调用以 TypeError 拒绝。先过滤期望列表,再打开多选选择器。
async function pickAttendees(wanted = ['name', 'tel', 'icon']) { if (!('contacts' in navigator && 'ContactsManager' in window)) { return null; // 调用方显示自己的参会人表单 } const available = await navigator.contacts.getProperties(); const props = wanted.filter((p) => available.includes(p)); if (props.length === 0) return null;
const contacts = await navigator.contacts.select(props, { multiple: true }); return contacts.map((c) => ({ name: c.name?.[0] ?? '', tel: c.tel?.[0] ?? '', avatar: c.icon?.[0] ? URL.createObjectURL(c.icon[0]) : null, }));}getProperties() 不需要用户手势,可以在页面加载时运行并决定渲染哪些按钮;只有 select() 调用必须等待点击。
另请参阅
链接到“另请参阅”一节- Web Share API,PWA 能从手势中打开的另一个系统面板
- Payment Request API,
ContactAddress复用了它的PaymentAddress结构 - Contact Picker API: select() method(w3.org)
- A contact picker for the web(developer.chrome.com)
- Chrome Platform Status: Contacts API(chromestatus.com)
规范
| 规范 | 状态 |
|---|---|
| Contact Picker(联系人选择器) | WICG 草案 |
| Contact Picker API: select() method | W3C 草案 |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Desktop)# | 不支持 | — | 高 | 来源 | 1 |
| Chrome (Android)# | 支持 | 80 | 高 | 来源 | — |
| Edge (Desktop)# | 不支持 | — | 高 | 来源 | 23 |
| Firefox (Desktop)# | 不支持 | — | 高 | 来源 | 4 |
| Firefox (Android)# | 不支持 | — | 高 | 来源 | 56 |
| Safari (macOS)# | 不支持 | — | 高 | 来源 | 7 |
| Safari (iOS)# | 需开启标志 | 14.5 | 高 | 来源 | 8 |
| Samsung Internet# | 不支持 | removed in 22.0 | 高 | 来源 | 910 |
| WebView (Android)# | 支持 | 80 | 高 | 来源 | 11 |
- browser-compat-data 未记录 Chrome 的支持。
- browser-compat-data 未记录 Edge 的支持。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- 实现跟踪:https://bugzil.la/1756767。
- 实现跟踪:https://bugzil.la/1756767。
- 由 browser-compat-data 镜像自 Firefox 的数据推导。
- browser-compat-data 未记录 Safari 的支持。
- 需开启 `Contact Picker API` 偏好设置。
- Samsung Internet 自 14.0 起支持,22.0 中移除。
- 该 API 虽已暴露,但打开联系人选择器时会失败。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。