網頁版聯絡人選擇器

使用者可以透過 Contact Picker API，輕鬆分享聯絡人清單中的聯絡人。

Pete LePage

什麼是 Contact Picker API？

自古以來 (幾乎)，iOS/Android 應用程式就提供存取行動裝置上使用者聯絡人的功能。這是網頁開發人員最常提出的功能要求之一，也是他們建構 iOS/Android 應用程式的主要原因。

聯絡人挑選器 API 規格適用於 Android M 以上版本，是隨選 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()。 呼叫時，這個方法會傳回 Promise 並顯示聯絡人挑選器，讓使用者選取要與網站分享的聯絡人。選取要分享的內容並點按「完成」後，Promise 會解析為使用者選取的聯絡人陣列。

呼叫 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()。這個方法會傳回 Promise，並以字串陣列解析，指出可用的屬性。例如：['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，選擇器只會顯示名稱和電話號碼。

網站要求所有屬性的選擇器螢幕截圖。
選擇器、要求 name、email 和 tel 的網站，已選取一個聯絡人。
網站只要求提供電話號碼時，系統顯示的選擇器畫面截圖。
選擇器，網站僅要求 tel，已選取一個聯絡人。
長按聯絡人時，挑選器會顯示的螢幕截圖。
長按聯絡人後顯示的結果。

長按聯絡人會顯示選取該聯絡人後要分享的所有資訊。(請參閱柴郡貓聯絡人圖片)。

權限不會保留

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

意見回饋

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

導入時發生問題嗎？

您是否發現 Chrome 實作方式有錯誤？還是實作方式與規格不同？

打算使用 API 嗎？

您打算使用 Contact Picker API 嗎？您的公開支持有助於 Chrome 團隊排定功能優先順序，並向其他瀏覽器供應商展現支援這些功能的重要性。

實用連結

謝謝

特別感謝 Finnur Thorarinsson 和 Rayan Kanso 實作這項功能，以及 Peter Beverloo 的程式碼，我毫不避諱地竊取並重構了這些程式碼，用於示範。

附註：聯絡人挑選器中的名稱是《愛麗絲夢遊仙境》的角色。