联系人选取器演示 - Contacts API

Contacts API（也称为 Contact Picker API）是一个浏览器Web API，允许网站从用户设备的通讯录中选择一个或多个联系人。用户通过系统原生的联系人选择器界面进行选择，只有用户明确选中的联系人信息才会被共享给网站。这保证了用户隐私——网站无法静默读取通讯录，必须经过用户的主动选择操作。该API通过 navigator.contacts.select() 方法调用。

目前（2024-2025年），Chrome for Android（版本80+）是主要支持平台。在桌面端Chrome、Safari（包括iOS）、Firefox、Edge等浏览器中，此API通常不可用。使用前必须检测 navigator.contacts 是否存在。该API在移动端PWA场景下最为实用。部分浏览器可能需要用户在 chrome://flags 中启用相关实验性功能。

Contacts API 支持以下5种属性：
• name — 联系人姓名（包含 displayName、givenName、familyName 等）
• email — 邮箱地址列表（每个包含 address 和 type 如 work/home）
• tel — 电话号码列表（每个包含 number 和 type 如 mobile/work）
• address — 地址列表（包含 formattedAddress 等）
• icon — 联系人头像（返回 Blob URL）
开发者需要在调用时指定需要的属性数组，如 ['name', 'email', 'tel']。

这很常见。Contacts API 目前主要在移动端Chrome浏览器上可用。如果你在桌面端Chrome、Safari或Firefox上看到"不支持"提示，这是正常的。主要原因：
1. 桌面操作系统没有统一的联系人数据库供浏览器访问
2. 隐私和安全考虑——桌面环境的权限模型不同
3. 该API仍处于相对早期的阶段，尚未被所有浏览器厂商广泛采用
你可以点击「模拟演示」按钮查看API返回的数据格式。

安全性设计相当严格：
• 用户手势触发：必须由用户点击按钮等操作触发，不能自动弹出
• 用户主动选择：弹出的是系统原生联系人选择器，用户完全控制选择哪些联系人
• 仅返回选中数据：未选中的联系人信息完全不会泄露
• HTTPS要求：必须在安全上下文中使用
• 无静默访问：不存在任何方式在后台读取通讯录
简言之，用户拥有完全的控制权。

在PWA中使用Contacts API的最佳实践：
1. 检测支持：始终先检查 if ('contacts' in navigator)
2. 优雅降级：不支持的浏览器提供替代方案（如手动输入或vCard上传）
3. 只请求必要属性：最小化请求的属性以减少权限关注
4. 处理取消：用户可能取消选择，需处理空返回数组
5. 错误处理：权限被拒、API异常等都需要妥善处理
6. 缓存策略：对于icon（blob URL），注意其生命周期

返回的是 Contact对象数组。每个Contact对象结构如下：
• name → 数组，元素含 displayName, givenName[], familyName[]
• email → 数组，元素含 address（邮箱字符串）, type（如"personal","work"）
• tel → 数组，元素含 number（电话号码）, type（如"mobile","home"）
• address → 数组，元素含 formattedAddress, type 等
• icon → 数组，元素为Blob对象（可转为blob URL用于展示）
注意：所有属性值都是数组，因为一个联系人可能有多个电话号码、邮箱等。

目前浏览器中实现的 navigator.contacts.select() 是 Contact Picker API，它只支持选择联系人。还有一个更早的提案叫做 Web Contact API，它计划支持完整的CRUD操作（创建、读取、更新、删除联系人），但这个完整版本尚未被任何浏览器实现。目前可用的只有"选取器"功能——即从设备通讯录中选取并读取联系人信息。