HTML中如何调用联系人选择器API

Contact Picker API 是一种在安全上下文（HTTPS/localhost）下、通过用户手势（如点击）调用的现代浏览器特性，允许网页安全地访问用户系统联系人（仅支持 Chromium 84+，如 Chrome 和 Edge），但 iOS Safari 完全不支持；它需显式声明请求字段（如 'name'、'email'、'tel'），返回结构化但需谨慎处理的数据（字段可能缺失、为空数组或含格式化字符），且无法绕过权限限制或降级为自动解析 vCard——开发者必须做好兼容性检测、错误捕获、数据清洗和优雅降级（如引导手动输入或提示平台限制），才能真正提升表单填写体验。

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）”。

• 检测失败后，可动态插入一个带占位符的 ，并设 list 属性指向 （预填常用邮箱）
• 避免 polyfill：目前没有任何可靠 JS 库能绕过浏览器沙箱读取本地通讯录
• 如果业务强依赖联系人数据（如邮件客户端），需明确告知 iOS 用户需手动复制粘贴，或引导使用桌面端 Chrome

最易被忽略的一点：API 返回的字段值未经清洗，tel 可能含空格、括号、分机号标记（如 "(555) 123-4567 x102"），实际使用前必须正则提取纯数字，否则发短信或拨号会失败。

到这里，我们也就讲完了《HTML中如何调用联系人选择器API》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！