UD5工具箱
什么是 Contact Picker API？
Contact Picker API 是一项 Web 标准 API，允许网页应用请求用户从设备通讯录中选择联系人，并获取被选中联系人的基本信息。与传统的通讯录读取方式不同，该 API 采用用户主动选择的设计模式，确保用户对分享哪些联系人信息拥有完全的控制权。开发者可以通过调用 navigator.contacts.select() 方法来使用此 API，传入需要获取的属性列表即可。该 API 特别适用于需要邀请好友、社交分享或身份验证的移动 Web 应用场景。
Contact Picker API 可以获取哪些联系人信息？
Contact Picker API 目前支持获取五种类型的联系人属性。name 属性返回联系人的姓名字符串；tel 属性返回电话号码数组（因为一个联系人可能有多个电话号码）；email 属性返回电子邮件地址数组；address 属性返回联系人的邮政地址字符串；icon 属性返回联系人头像的 Blob 对象，可以转换为图片 URL 进行显示。开发者可以根据实际需求选择性地获取这些属性，无需请求不需要的数据，这既提高了效率也更好地保护了用户隐私。
哪些浏览器支持 Contact Picker API？
目前 Contact Picker API 主要在 Chrome for Android 80 及以上版本中得到支持。桌面版 Chrome、Safari、Firefox、Edge 等主流浏览器暂时不支持此 API。由于兼容性限制，开发者在使用 Contact Picker API 时需要检测浏览器支持情况，并为不支持的浏览器提供替代方案。本工具内置了兼容性检测功能，会在使用前自动检查当前浏览器是否支持该 API，并给出相应的提示。建议开发者在生产环境中始终添加兼容性检测和降级处理逻辑。
使用 Contact Picker API 是否安全？会泄露通讯录吗？
Contact Picker API 采用了三重安全机制来保护用户隐私。首先，API 调用必须由用户手势触发（如点击按钮），脚本无法自动调用联系人选择器。其次，用户在浏览器弹出的联系人界面中必须明确选择要分享的联系人，未被选中的通讯录信息不会被任何应用获取。第三，API 要求页面在 HTTPS 环境下运行，确保数据传输的加密安全。这三个条件共同构成了完整的隐私保护体系，使 Contact Picker API 成为获取联系人信息的安全方式。
如何在代码中调用 Contact Picker API？
调用 Contact Picker API 的基本步骤如下。首先，检查浏览器是否支持 navigator.contacts 对象。然后，在用户点击事件的处理函数中调用 navigator.contacts.select() 方法，传入配置对象指定需要获取的属性。例如：const contacts = await navigator.contacts.select({ properties: ['name', 'tel', 'email'] })。该方法返回一个 Promise，解析后得到联系人数据数组。你需要使用 async/await 或 .then() 来处理异步结果。完整的代码示例可以在本工具的源码中找到。
为什么我在浏览器中无法使用这个工具？
无法使用本工具通常有几个原因。最常见的原因是浏览器不支持 Contact Picker API，目前只有 Chrome for Android 80+ 支持此 API。如果你使用的是桌面浏览器、Safari 或 Firefox，将无法使用此功能。另一个原因是页面未在 HTTPS 环境下运行，Contact Picker API 要求安全上下文。此外，某些浏览器设置可能会禁用 API 访问。建议使用 Chrome for Android 访问本工具，确保页面地址以 https:// 开头，如果在本地测试请使用 localhost 地址。
Contact Picker API 和 HTML <input type="file"> 有什么区别？
Contact Picker API 和 HTML 文件输入元素是两种完全不同的技术。HTML <input type="file"> 用于让用户选择文件（包括联系人导出文件 vCard），而 Contact Picker API 直接与设备通讯录交互获取联系人信息。Contact Picker API 的优势在于无需用户导出和上传文件，直接在浏览器中完成联系人选择，用户体验更流畅。此外，Contact Picker API 返回的数据是结构化的，可以直接在代码中使用，无需额外的文件解析步骤。对于需要访问设备通讯录的 Web 应用，Contact Picker API 是更现代和便捷的选择。
如何处理用户取消联系人选择的情况？
当用户在浏览器弹出的联系人选择界面中点击取消或关闭时，navigator.contacts.select() 返回的 Promise 会被拒绝（reject），抛出一个 AbortError。开发者需要使用 try/catch 或 .catch() 来捕获这个错误。在本工具中，取消操作会被优雅处理，不会显示错误信息。在实际项目中，建议捕获 AbortError 并给出友好的提示，如"您已取消联系人选择"，同时不要将其作为程序错误进行处理。对于其他类型的错误（如 NotAllowedError），则需要检查权限和环境配置。