Contact Picker API仅在HTTPS/localhost安全上下文且用户手势触发时可用，需检查浏览器支持、指定合法字段并处理返回数组，iOS Safari不支持。
Contact Picker API 不支持在普通网页中直接调用
它只在安全上下文（https:// 或 localhost）且用户主动触发的事件中可用，比如点击按钮。直接在页面加载时调用 navigator.contacts.select() 会立刻报错：SecurityError: Permission denied。
常见错误现象：控制台显示 TypeError: navigator.contacts.select is not a function —— 这通常是因为浏览器不支持（仅 Chromium 84+，如 Chrome、Edge）、未启用实验性功能（旧版需手动开启 chrome://flags/#contact-picker），或当前页面不是 HTTPS/localhost。
- 必须用用户手势（如
click、touchstart）触发，不能放在setTimeout或异步回调里“模拟”触发 - 请求字段需明确指定，如
['name', 'email', 'tel']；传空数组或非法字段名会拒绝执行 - 移动端（Android Chrome）支持较好；iOS Safari 完全不支持，
navigator.contacts为undefined
如何正确调用 navigator.contacts.select()
先检查 API 可用性，再绑定到按钮点击事件。注意它返回的是 Promise，需用 await 或 .then() 处理结果。
button.addEventListener('click', async () => {
if (!('contacts' in navigator)) {
console.error('Contact Picker API not supported');
return;
}
try {
const contacts = await navigator.contacts.select(
['name', 'email', 'tel'],
{ multiple: true }
);
console.log(contacts); // [{ name: ['Alice'], email: ['a@example.com'], tel: ['123'] }]
} catch (err) {
console.error('Contact selection failed:', err.name); // 可能是 'AbortError' 或 'SecurityError'
}
});
-
multiple: true允许选多个联系人，但部分 Android 版本仍只支持单选 - 字段名必须小写且严格匹配：用
'email'，不能写'emails'或'Email' - 返回的每个联系人字段都是字符串数组（即使只有一个值），例如
contact.name[0]才是姓名字符串
为什么获取不到电话或邮箱？
不是所有联系人都有完整字段，而且系统权限模型限制了默认暴露范围。用户在选择界面可以取消勾选某类信息（如隐藏电话），此时对应字段在返回对象中可能完全缺失，或为空数组。
立即学习“前端免费学习笔记（深入）”；
- 不要假设
contact.tel一定存在，需先判断：if (contact.tel && contact.tel.length) - 某些 Android 厂商定制系统（如 Samsung One UI）会过滤掉未标记为“常用”或“已验证”的号码
- Chrome 97+ 开始要求网站先通过
Permissions-Policy: interest-cohort=()等头禁用 FLoC，否则可能静默降级行为（极少见，但有报告）
替代方案：当 Contact Picker 不可用时怎么办？
不能回退到读取 input[type="file"] 导入 vCard —— 浏览器不会自动解析，且用户需手动导出联系人，体验差。更现实的做法是降级为表单手动输入，并提示“可使用系统联系人快速填充（仅 Chrome/Edge）”。
- 检测失败后，可动态插入一个带占位符的
<input type="email">，并设list属性指向<datalist>（预填常用邮箱） - 避免 polyfill：目前没有任何可靠 JS 库能绕过浏览器沙箱读取本地通讯录
- 如果业务强依赖联系人数据（如邮件客户端），需明确告知 iOS 用户需手动复制粘贴，或引导使用桌面端 Chrome
最易被忽略的一点：API 返回的字段值未经清洗，tel 可能含空格、括号、分机号标记（如 "(555) 123-4567 x102"），实际使用前必须正则提取纯数字，否则发短信或拨号会失败。
