跳转到内容

能力中的 API

Contact Picker API

发布于

有限可用不支持的浏览器: Chrome (Desktop)、Edge (Desktop)、Firefox (Desktop)、Firefox (Android)、Safari (macOS)WICG 草案

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() 调用必须等待点击。

规范

规范状态
Contact Picker(联系人选择器)WICG 草案
Contact Picker API: select() methodW3C 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
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
  1. browser-compat-data 未记录 Chrome 的支持。
  2. browser-compat-data 未记录 Edge 的支持。
  3. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  4. 实现跟踪:https://bugzil.la/1756767。
  5. 实现跟踪:https://bugzil.la/1756767。
  6. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  7. browser-compat-data 未记录 Safari 的支持。
  8. 需开启 `Contact Picker API` 偏好设置。
  9. Samsung Internet 自 14.0 起支持,22.0 中移除。
  10. 该 API 虽已暴露,但打开联系人选择器时会失败。
  11. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/contact-picker.json · 全球使用占比: 38 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)