ContactsManager: select() 方法

語法

select(properties)
select(properties, options)

引數

properties

一個由 字串 組成的陣列，用於定義要從聯絡人中檢索哪些資訊。允許的值如下：

• 'name'：聯絡人的姓名。
• 'tel'：聯絡人的電話號碼。
• 'email'：聯絡人的電子郵件地址。
• 'address'：聯絡人的郵寄地址。
• 'icon'：聯絡人的頭像。

options 可選

選項如下：

multiple

一個布林值，允許選擇多個聯絡人。預設為 false。

返回值

返回一個 Promise，該 Promise 解析為一個包含聯絡人資訊的物件陣列。每個物件代表一個單獨的聯絡人，可能包含以下屬性：

地址

一個 陣列，包含 ContactAddress 物件，每個物件包含一個唯一物理地址的詳細資訊。

電子郵件

包含電子郵件地址的字串陣列。

icon

包含個人影像的 Blob 物件陣列。

name

包含個人姓名唯一標識的字串陣列。

電話

包含個人電話號碼唯一標識的字串陣列。

異常

InvalidStateError DOMException

如果瀏覽上下文不是頂層上下文，如果聯絡人選擇器顯示了一個已存在的聯絡人選擇器標誌（因為一次只能存在一個選擇器），或者如果啟動聯絡人選擇器失敗，則返回此錯誤。

SecurityError DOMException

如果該方法不是由 使用者啟用 觸發的，則返回此錯誤。

TypeError

如果 properties 為空，或者指定的任何屬性不受支援，則返回此錯誤。

安全

需要 瞬時啟用。使用者必須與頁面或 UI 元素進行互動，此功能才能正常工作。

示例

基本示例

以下示例設定了要為每個聯絡人檢索的屬性陣列，並設定了一個選項物件以允許選擇多個聯絡人。

然後定義一個非同步函式，該函式使用 select() 方法向用戶展示聯絡人選擇器介面並處理選擇的結果。handleResults() 是一個由開發者定義的函式。

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

async function getContacts() {
  try {
    const contacts = await navigator.contacts.select(props, opts);
    handleResults(contacts);
  } catch (ex) {
    // Handle any errors here.
  }
}

僅使用支援的屬性進行選擇

以下示例使用 getProperties() 來確保只傳遞受支援的屬性。否則，select() 可能會丟擲 TypeError。handleResults() 是一個由開發者定義的函式。

const supportedProperties = await navigator.contacts.getProperties();

async function getContacts() {
  try {
    const contacts = await navigator.contacts.select(supportedProperties);
    handleResults(contacts);
  } catch (ex) {
    // Handle any errors here.
  }
}

規範

瀏覽器相容性