網頁版聯絡人選擇器

Contact Picker API 可讓使用者輕鬆分享聯絡人清單中的聯絡人。

Pete LePage

什麼是 Contact Picker API？

自 (幾乎) 新版發生以來，行動裝置使用者 也一直都是 iOS/Android 應用程式的功能之一。這是網頁程式開發人員最常提出的功能要求之一，也是開發 iOS/Android 應用程式的關鍵原因。

自 Android M 或以上版本的 Chrome 80 起，Contact Picker API 規格是一種隨選 API，可讓使用者從聯絡人清單中選取項目，並將所選項目的有限詳細資料提供給網站。使用者不僅可以隨時分享自己想要的內容，也能讓使用者更輕鬆地與親朋好友聯繫及保持聯繫。

舉例來說，網頁式電子郵件用戶端可以使用 Contact Picker API 選取電子郵件的收件者。舉例來說，配音圖應用程式可以查詢要撥打的電話號碼。或者，社群網路也能協助使用者找出哪些好友已加入。

使用 Contact Picker API

Contact Picker API 需要使用選項參數的方法呼叫，該參數會指定您需要的聯絡資訊類型。第二種方法會告訴您基礎系統提供的資訊。

功能偵測

如要確認系統是否支援 Contact Picker API，請使用：

const supported = ('contacts' in navigator && 'ContactsManager' in window);

此外，在 Android 裝置上，聯絡人選擇器需要 Android M 以上版本。

正在開啟聯絡人選擇器

Contact Picker API 的進入點為 navigator.contacts.select()。呼叫完成後，系統會傳回承諾並顯示聯絡人選擇器，讓使用者可以選取要與網站共用的聯絡人。選取要分享的內容並按一下「完成」後，承諾會以使用者選取的聯絡人陣列解析。

呼叫 select() 時，您必須提供要傳回做為第一個參數的屬性陣列 (允許的值可以是 'name'、'email'、'tel'、'address' 或 'icon' 中的任一個)，並視需要選擇是否要選取多個聯絡人做為第二個參數。

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
  const contacts = await navigator.contacts.select(props, opts);
  handleResults(contacts);
} catch (ex) {
  // Handle any errors here.
}

Contacts Picker API 只能從安全的、頂層瀏覽情境和其他強大的 API 呼叫，因此您必須使用使用者手勢。

偵測可用屬性

如要偵測可用的屬性，請呼叫 navigator.contacts.getProperties()。這個方法會傳回承諾，而且會透過字串陣列指出可用的屬性。例如：['name', 'email', 'tel', 'address']。您可以將這些值傳遞至 select()。

提醒您，屬性不一定隨時可用，且可能會新增屬性。日後，其他平台和聯絡來源可能會限制可共用的屬性。

處理結果

Contact Picker API 會傳回聯絡人陣列，且每個聯絡人都包含所要求屬性的陣列。如果聯絡人沒有所要求屬性的資料，或者使用者選擇拒絕共用特定屬性，API 就會傳回空白陣列。(我們會在「使用者控制項」部分中說明使用者選擇屬性的方式)。

舉例來說，如果網站要求 name、email 和 tel，且使用者在名稱欄位中選取一位具有資料的聯絡人，且此聯絡人在沒有電子郵件地址的情況下提供兩組電話號碼，則傳回的回應為：

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

安全性和權限

Chrome 團隊在設計及實作 Contact Picker API 時，是以控管強大的網路平台功能存取權一文定義的核心原則，這些原則包括使用者控制權、資訊公開和人體工學。我會分別說明

使用者控制項

您可以透過挑選器存取使用者的聯絡人，而且只能以使用者手勢在安全的頂層瀏覽情境中呼叫。這可確保網站無法在網頁載入時顯示挑選器，也不會在沒有任何結構定義的情況下隨機顯示挑選器。

螢幕截圖，使用者可以選擇要分享哪些屬性。
使用者可選擇不共用某些資源。在此螢幕截圖中，使用者已取消勾選「電話號碼」按鈕。雖然網站會要求提供電話號碼，但不會將這些資訊提供給網站。

您無法一次大量選取所有聯絡人，以便建議使用者只選取需要針對該網站分享的聯絡人。使用者也可以切換挑選器頂端的資源按鈕，控制要與網站共用的屬性。

資訊公開

為了清楚說明要分享哪些詳細聯絡資料，挑選器一律會顯示聯絡人的名稱和圖示，以及網站要求的所有屬性。舉例來說，如果網站要求 name、email 和 tel，挑選器中就會顯示這三項屬性。或者，如果網站僅要求 tel，挑選器只會顯示名稱和電話號碼。

要求所有屬性的網站選擇器螢幕截圖。
Picker，網站要求存取 name、email 和 tel，已選取一位聯絡人。
網站選擇器的螢幕截圖，僅要求電話號碼。
挑選器，僅要求 tel 的網站，已選取一位聯絡人。
長按聯絡人時顯示的挑選器螢幕截圖。
長按聯絡人的結果。

如果選取聯絡人，長按聯絡人即可顯示系統將分享的所有資訊。(請參考 Cheshire Cat 聯絡人圖片)。

未設定權限

聯絡人存取權隨需求提供，不會保留。網站每次需要存取權時，都必須透過使用者手勢呼叫 navigator.contacts.select()，且使用者必須個別選擇要與網站共用的聯絡人。

意見回饋：

Chrome 團隊想瞭解您使用 Contact Picker API 的經驗。

實作時遇到問題嗎？

您在執行 Chrome 時發現錯誤了嗎？還是實作與規格不同？

  • 前往 https://new.crbug.com 回報錯誤。請務必盡可能附上詳細資料，提供重現錯誤的簡易操作說明，並將「Components」設為 Blink>Contacts。Glitch 適合用來快速分享輕鬆快速地重現問題的過程。

打算使用 API 嗎？

你打算使用 Contact Picker API 嗎？您的公開支援可協助 Chrome 團隊決定功能的優先順序，以及向其他瀏覽器廠商說明這項功能有多重要。

實用連結

感謝

感謝 Finnur Thorarinsson 和 Rayan Kanso 實作這項功能，並感謝 Peter Beverloo 對我最神奇的竊取並為示範重新建構程式碼。

附註：我的聯絡人挑選器中的姓名是 Alice 在 Wonderland 中的字元。