網頁版聯絡人選擇器

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

Pete LePage

什麼是 Contact Picker API？

自從行動裝置存取使用者的聯絡人， (幾乎) 曝光的時間。這是最常見的功能要求之一 我聽到網頁程式開發人員表示，他們開發 iOS/Android 的主要原因通常是開發人員 應用程式。

適用於 Android M 以上版本的 Chrome 80，Contact Picker API 規格是 隨選 API，可讓使用者從聯絡人清單中選取項目，以及 與網站分享選定項目的有限詳細資料。可讓使用者 而且得隨時分享所需內容，方便使用者 與親朋好友交流互動

舉例來說，網頁式電子郵件用戶端可以使用 Contact Picker API 執行下列操作： 選取電子郵件的收件者。旁白應用程式可以查詢 。或者，使用者在社群網路中 哪些朋友已加入。

使用 Contact Picker API

Contact Picker API 規定必須使用 options 參數呼叫的方法， 指定所需的聯絡資訊類型。第二種方法是 那麼基礎系統提供的資訊

特徵偵測

如要查看系統是否支援 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.
}
敬上

聯絡人挑選器 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，挑選器只會顯示名稱， 電話號碼

網站挑選器的螢幕截圖，用於要求所有屬性。
挑選器、網站要求 name、email 和 tel，已選取一位聯絡人。
，瞭解如何調查及移除這項存取權。
網站的選擇器螢幕截圖，顯示只要求電話號碼。
挑選器，網站只要求 tel，已選取一位聯絡人。
長按聯絡人時的選擇工具螢幕截圖。
長按聯絡人的結果。

只要長按聯絡人，就能看到所有相應資訊 分享 (如果已選取聯絡人)。(請參閱 Cheshire Cat 聯絡人圖片)。

未保留權限

聯絡人存取權採隨選要求，不會保留。每次網站需要 必須透過使用者手勢呼叫 navigator.contacts.select() ，且使用者必須個別選擇要分享的聯絡人 互動資訊。

意見回饋

Chrome 團隊想瞭解你使用聯絡人挑選工具的經驗 也能使用 Google Cloud CLI 或 Compute Engine API

無法導入嗎？

您發現 Chrome 實作錯誤嗎？另一種是實作 該怎麼辦？

  • 前往 https://new.crbug.com 回報錯誤。請務必盡量附上 請盡可能詳細說明，提供重現錯誤的簡單操作說明，以及 將「元件」設為 Blink>Contacts。Glitch 的表現非常好 能快速輕鬆地重現問題。

想要使用這個 API 嗎？

您是否打算使用 Contact Picker API？你的公開支援讓 優先開發功能，並向其他瀏覽器廠商說明這些功能 對他們來說至關重要

實用連結

謝謝

由衷感謝 Finnur Thorarinsson 和 Rayan Kanso 並實作這項功能的 Peter Beverloo 程式碼 重新建構並重構示範。

附註：聯絡人選擇工具中的姓名是來自愛麗絲夢遊仙境的字元。