PWA 實作 Contact Picker API 完整指南：掌握 navigator.contacts.select，讓 Web App 具備選取聯絡人功能

什麼是 Contact Picker API？

Contact Picker API 是一種 Web API，允許 Progressive Web App (PWA) 安全地請求存取使用者的本機通訊錄資訊（如姓名、電話、Email 與地址）。與傳統方法不同，這項 API 遵循「隱私優先」原則：瀏覽器會彈出系統原生的選取介面，使用者可以逐一勾選想要分享的聯絡人，而非一次性將整個通訊錄曝露給網頁。它是實現邀請好友功能、快速填寫收件人資訊或社群互動的高效解決方案，能大幅縮短 Web 與原生 App (Native App) 在功能上的差距。

什麼是 Contact Picker API？PWA 存取通訊錄解析

透過 Contact Picker API，網頁也能像原生 App (Native App) 一樣去選取用戶的聯絡人資訊。API 允許開發者選擇一個或多個欄位（如姓名、電話、Email），而用戶則能自主決定要分享哪些內容。

小編覺得這項功能非常實用，例如：

• Email Web App：直接從通訊錄選擇收信人。
• 社群網站：邀請好友或檢查哪些聯絡人已加入。

底下連結是小編按照教學文件製作出的 Demo 網站，建議使用 Android M 以上手機開啟 Chrome 80+ 版本來玩玩看：
https://linyencheng.github.io/pwa-contact-picker/

Contact Picker API 實作教學：如何存取通訊錄？

在進行 Contact Picker API 實作 時，小編整理了以下關鍵步驟：

1. 檢查瀏覽器支援度

PWA 教學 的第一步永遠是檢查功能是否可用。請使用以下程式碼片段：

1

const supported = "contacts" in navigator && "ContactsManager" in window;

2. 設定參數與呼叫 API

Contact Picker API 接受兩個主要參數：properties (欄位陣列) 與 options (配置物件)。

• properties: 包含 name, email, tel, address, icon。
• options: 例如 { multiple: true } 來開啟多選功能。

使用方式非常直觀，直接呼叫 navigator.contacts.select()。當 API 被叫用後，系統會自動彈出聯絡人選取介面。

3. navigator.contacts.select 範例程式碼

1
2
3
4
5
6
7
8
9
10

const properties = ["name", "email", "tel", "address", "icon"];
const options = { multiple: true };

try {
  // 開啟聯絡人選取器，會等待使用者選取後才繼續
  const contacts = await navigator.contacts.select(properties, options);
  handleResults(contacts); // 處理回傳的聯絡人資料
} catch (ex) {
  // 處理使用者取消選取或系統錯誤
}

PWA 聯絡人選取器介面範例 (圖片來源: Google Web Fundamentals)

FAQ：PWA Contact Picker 常見問題

Q1：使用 Contact Picker API 會不會有隱私洩漏的風險？

A：API 設計上非常注重隱私。開發者無法直接讀取整個通訊錄，只能獲得使用者在系統彈窗中「明確點選」的那幾個聯絡人。且該 API 僅限於 HTTPS 安全環境，並要求必須由使用者的點擊行為（User Gesture）觸發。

Q2：哪些瀏覽器目前支援這項功能？

A：這項功能目前主要支援 Android 上的 Chrome 80+。對於 iOS 使用者，雖然 Safari 支援程度較慢，但這正是「漸進式增強」的精神——在支援的裝置上提供頂級體驗，在不支援的裝置上則提供手動輸入作為替代方案。

Q3：回傳的聯絡人資料包含圖片 (icon) 嗎？

A：可以。只要在 properties 陣列中包含 'icon' 欄位，且該聯絡人在通訊錄中有設定照片，API 就會回傳圖片的 Blob 物件。這對於在 Web App 中顯示精美的頭像非常有幫助。

• ← 上一篇
• 下一篇 →