使用 JavaScript 读取电话联系人

发布于2024-08-26

作者注：本文中描述的技术和流程是实验性的，仅适用于少数浏览器。在撰写本文时，联系人选取器 API 仅受 Android Chrome（从版本 80 开始）和 iOS Safari（从版本 14.5 开始，但仅在标志后面）支持。如果您想查看该功能，可以在我的网站上查看正在运行的演示。

从手机或平板电脑上的联系人列表中读取条目传统上仅限于本机应用程序。但通过联系人选择器 API，我们可以使用 JavaScript 来做到这一点。

此功能对于需要电话号码或 VoIP 等联系信息的应用程序、我们想要发现认识的人的社交网络或需要填写表单信息而不交换应用程序来查看数据的应用程序可能很有趣。

API 和设备将限制哪些属性可用。有五个标准可供开发者选择：

姓名
电话
电子邮件
地址
图标

这里的复数很重要，因为一个联系人可以有多个电话、电子邮件或多个地址。为了一致性，返回的数据将始终位于数组内，即使它是单个值。稍后会详细介绍。

隐私和安全

手机上存储的联系信息可能包含我们必须谨慎对待的敏感信息。因此，我们必须考虑隐私和安全因素：

联系人选取器 API 代码必须在顶级浏览上下文中运行。它可以防止外部代码（例如广告或第三方插件）读取您手机上的联系人列表。
联系人选取器 API 代码只能在用户手势后运行。因此，开发人员无法完全自动化该过程。用户必须采取行动才能触发接触读取。
此人必须允许访问联系人列表。这个限制是手机强加的，不是JS强加的。用户必须授予浏览器访问联系人的权限（如果还没有）。

他们第一次使用使用联系人选择器 API 的网站时，可能会收到如下消息：

Read Phone Contacts with JavaScript — 有些人可能会觉得这个弹出窗口“可怕”。

手机每次都会显示此弹出窗口，直到用户点击“允许”。在此之前，联系人选取器 API 将不会运行。哪个好；我们希望确保用户授予适当的权限。一次性的事情也很好。每次页面运行联系人选择器 API 代码时授予授权将是一件令人头疼的事情。

API 和代码

联系人选取器 API 只定义了两个方法：

getProperties()：返回可在设备上读取的属性列表。定义中只有五个：“地址”、“电子邮件”、“图标”（这可能不是联系人图片）、“姓名”、“电话”（电话），但设备可能不允许访问所有其中。
select()：打开联系人弹出窗口并在用户完成操作后返回选择。它需要两个参数：要读取的属性列表和带有选项的可选对象。

这两种方法都返回 Promise，但考虑到它们触发的操作会阻塞应用程序的常规流程，我们在处理它们时应该使用 async/await。

忽略 getProperties() 并直接请求所有属性可能很诱人。但如果你这样做的话要小心：它可能会起作用，但如果任何指定的属性不可用， select() 方法将抛出异常。

例子

联系人选择器 API 的演示正在运行（在此处在线运行或观看此视频）。如果支持 API，它会显示一个按钮，用于读取联系人的电话号码、姓名和电子邮件以进行显示。

首先，我们需要按钮。正如隐私和安全部分前面详细介绍的，在调用 API 之前需要用户执行操作，因此如果没有用户交互，我们无法触发任何内容：

主要代码在 getContactData() 函数中。但在此之前，如果联系人选择器 API 不可用，那么显示该按钮有何意义呢？如果按钮不可用，我们将其隐藏。或者更好的是，让我们默认隐藏按钮（添加隐藏属性），并且仅在 API 可用时才显示它。

// only show the button if browser supports Contact Picker API
if ("contacts" in navigator) {
  document.querySelector("button").removeAttribute("hidden");
}

现在按钮逻辑已经就位，让我们关注 getContactData()。这是该函数的注释版本：

// it is asynchronous because we'll wait for the modal selection
async function getContactData() {
  // indicate what contact values will be read
  const props = ["tel", "name", "email"];

  // wrap everything in a try...catch, just in case
  try {
    // open the native contact selector (after permission is granted)
    const contacts = await navigator.contacts.select(props);

    // this will execute after the native contact selector is closed
    if (contacts.length) {
      // if there's data, show it
      alert("Selected data: "   JSON.stringify(contacts));
    } else {
      // ...if not, indicate nothing was selected
      alert("No selection done");
    }
  } catch (ex) {
    // if something fails, show the error message
    alert(ex.message)
  }
}

一旦按钮触发此功能，并且如果浏览器有权限（参见上一节的屏幕截图），则会显示联系模式，指示基本信息：读取数据的 URL、将返回什么数据以及可供选择的联系人列表。

关闭模式后，contacts 变量会将数据存储在 JSON 中，作为一个数组，其中包含包含所请求信息的对象（如果联系人卡片中不可用，则可能为空）。

例如，这是选择自己作为联系人后的结果（假数据）：

[
  {
    "address": [],
    "email": [ "[email protected]" ],
    "icon": [],
    "name": [ "Alvaro Montoro" ],
    "tel": [ "555-555-5555", "555-123-4567" ]
  }
]

如果数据包含图标，它将是带有图像的斑点。如果数据中包含地址，那么它将是一个更复杂的对象，包含街道、城市、国家、邮政编码等。您可以在规范中查看返回值。

但是，如果我们只选择一个联系人，为什么要使用数组呢？因为可以选择多个联系人！

选择多个联系人

可以选择多个联系人。如果我们想这样做，我们需要将第二个参数传递给 navigator.contacts.select() 方法来指示此选项。

const props = ["tel", "address", "icon", "name", "email"];
// only one option available: read multiple or only one (default)
const options = { multiple: true };

try {
  const contacts = await navigator.contacts.select(props, options);
  // ...

结果是一个联系人数组，因此本示例的其余代码可以保持不变。

上面的代码可能会令人生畏，主要是因为我添加了所有注释。这是上面代码的简单注释版本。正如您可能注意到的，这非常简单：

async function getContactData() {
  if ("contacts" in navigator) {
    const props = await navigator.contacts.getProperties();
    const options = { multiple: true };

    try {
      const contacts = await navigator.contacts.select(props, options);

      if (contacts.length) {
        // code managing the selected data
      } else {
        // code when nothing was selected
      }
    } catch (ex) {
      // code if there was an error
    }
  }
}

您可以在我的网站上查看正在运行的演示。别担心，除了将联系信息写在屏幕上之外，我不会对其进行任何操作。但如果你不相信我，请先检查一下代码。