Contact Picker API 可讓使用者輕鬆分享聯絡人清單中的聯絡人。
什麼是 Contact Picker API?
自從 iOS/Android 應用程式問世以來,使用者行動裝置上的聯絡人存取權一直是這類應用程式的功能。這是我聽到網頁開發人員最常提出的功能要求之一,也是他們建構 iOS/Android 應用程式的主要原因。
Contact Picker API 規格是 Android M 以上版本的 Chrome 80 推出的按需 API,可讓使用者從聯絡人清單中選取項目,並與網站分享所選項目的部分詳細資料。使用者可以隨時分享自己想分享的內容,並更輕鬆地與親朋好友聯繫。
舉例來說,網路電子郵件用戶端可以使用 Contact Picker API 選取電子郵件的收件者。語音通訊應用程式可以查詢要撥打的電話號碼。或者,社群網路可以協助使用者找出哪些朋友已加入。
使用 Contact Picker API
聯絡人挑選器 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.
}
只能透過安全的頂層瀏覽環境和其他強大的 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 團隊根據「控管強大網路平台功能的存取權」一文中定義的核心原則,設計並實作聯絡人挑選器 API,包括使用者控管、資訊公開和人體工學。我會逐一說明。
使用者控制項
使用者聯絡資料的存取權是透過挑選器取得,且只能在安全的頂層瀏覽內容上,透過使用者手勢呼叫。這麼做可確保網站不會在網頁載入時顯示挑選器,或在沒有任何背景資訊的情況下隨機顯示挑選器。
系統不會提供選取所有聯絡人的選項,因此建議使用者只選取他們需要分享給特定網站的聯絡人。使用者也可以切換挑選器頂端的資源按鈕,控制要與網站共用的資源。
透明度
為了清楚說明要分享哪些聯絡詳細資料,挑選器一律會顯示聯絡人的姓名和圖示,以及網站要求的任何屬性。舉例來說,如果網站要求 name
、email
和 tel
,則挑選器會顯示這三個屬性。或者,如果網站只要求 tel
,則挑選器只會顯示名稱和電話號碼。
長按聯絡人,即可查看選取該聯絡人時會分享的所有資訊。(請參閱 Cheshire Cat 聯絡人圖片)。
不保留權限
聯絡人的存取權是按需存取,不會保留。每當網站想要存取權限時,都必須使用使用者手勢呼叫 navigator.contacts.select()
,且使用者必須個別選擇要與網站分享的聯絡人。
意見回饋
Chrome 團隊希望瞭解你使用 Contact Picker API 的體驗。
無法導入嗎?
你是否發現 Chrome 實作項目有錯誤?還是實作方式與規格不同?
- 請前往 https://new.crbug.com 回報錯誤。請務必盡可能提供詳細資訊,提供重現錯誤的簡單操作說明,並將「元件」設為
Blink>Contacts
。Glitch 可讓您輕鬆快速地重現問題。
打算使用 API 嗎?
您打算使用聯絡人挑選工具 API 嗎?您的公開支援有助於 Chrome 團隊決定功能的優先順序,並向其他瀏覽器供應商顯示支援這些功能的重要性。
- 請在 WICG Discourse 討論串中分享您打算如何使用這項功能。
- 使用主題標記
#ContactPicker
向 @ChromiumDev 發送推文,並告訴我們你在何處使用這項功能,以及使用方式。
實用連結
- 公開說明
- 聯絡人挑選器規格
- Contact Picker API 示範和 Contact Picker API 示範來源
- 追蹤錯誤
- ChromeStatus.com 項目
- 閃爍元件:
Blink>Contacts
謝謝
在此要特別感謝負責實作這項功能的 Finnur Thorarinsson 和 Rayan Kanso,以及 Peter Beverloo,因為我為了示範而偷取並重構他的程式碼。
附註:我的聯絡人挑選器中的名稱是《愛麗絲夢遊仙境》中的角色。