ContactsManager.select()
安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。
Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。
select()
は ContactsManager
インターフェイスのメソッドで、プロミス (Promise
) を返し、解決されると、共有したい連絡先を選択できる連絡先ピッカーがユーザーに表示されます。このメソッドでは、 Promise
が解決するためにユーザーのジェスチャーが必要です。
構文
js
select(properties)
select(properties, options)
引数
properties
-
文字列の配列で、連絡先からどの情報を受け取るかを定義します。許可されている値は次の通りです。
'name'
: 連絡先の名前。'tel'
: 連絡先の電話番号。'email'
: 連絡先のメールアドレス。'address'
: 連絡先の住所。'icon'
: 連絡先のアバター。
options
省略可-
オプションは以下のとおりです。
multiple
-
複数の連絡先を選択できるようにするかどうかの論理値。既定値では
false
です。
返値
連絡先情報を格納したオブジェクトの配列で解決する Promise
を返します。各オブジェクトは、それぞれ単一の連絡先を表し、以下のプロパティを格納する可能性があります。
address
-
それぞれ固有の物理的な住所の詳細を格納した
ContactAddress
オブジェクトのArray
です。 email
-
メールアドレスを格納した文字列の配列です。
icon
-
個人の画像を格納した
Blob
オブジェクトの配列です。 name
-
文字列の配列で、それぞれが固有の個人名です。
tel
-
文字列の配列で、それぞれが個人の固有の電話番号です。
例外
InvalidStateError
DOMException
-
閲覧コンテキストが最上位でない場合、または連絡先ピッカーがフラグを表示している場合に返されます。フラグは既に存在する連絡先ピッカーを表します。ピッカーは常に 1 つだけ存在できます。
SecurityError
DOMException
-
このメソッドがユーザーの操作によって起動していない場合に返されます。
TypeError
-
properties
が空の場合、または指定されたプロパティのいずれかが対応していない場合に返されます。
例
基本的な例
以下の例では、それぞれの連絡先に対して取得するプロパティの配列を設定し、また、複数の連絡先を選択できるようにオプションオブジェクトを設定しています。
次に、select()
メソッドを使用して、ユーザーに連絡先ピッカーインターフェイスを表示し、選択された結果を処理する非同期関数を定義しています。 handleResults()
は開発者が定義する関数です。
js
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()
は開発者が定義した関数です。
js
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.
}
}
仕様書
Specification |
---|
Contact Picker API # contacts-manager-select |
ブラウザーの互換性
BCD tables only load in the browser