網頁版聯絡人選擇器

使用者可以透過 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 實作方式有錯誤？還是實作方式與規格不同？

  • 請前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資料、簡單的錯誤重現說明，並將「Components」設為 Blink>Contacts。

打算使用 API 嗎？

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

實用連結

謝謝

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

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