ContactsManager: select()-Methode

Syntax

select(properties)
select(properties, options)

Parameter

properties

Ein Array von Strings, die definieren, welche Informationen von einem Kontakt abgerufen werden sollen. Erlaubte Werte sind wie folgt:

• 'name': Der Name des Kontakts.
• 'tel': Die Telefonnummer(n) des Kontakts.
• 'email': Die E-Mail-Adresse des Kontakts.
• 'address': Die Postadresse des Kontakts.
• 'icon': Das Avatarbild des Kontakts.

options Optional

Optionen sind wie folgt:

multiple

Ein Boolescher Wert, der die Auswahl mehrerer Kontakte erlaubt. Der Standardwert ist false.

Rückgabewert

Gibt ein Promise zurück, das mit einem Array von Objekten, die Kontaktinformationen enthalten, aufgelöst wird. Jedes Objekt stellt einen einzelnen Kontakt dar und kann die folgenden Eigenschaften enthalten:

address

Ein Array von ContactAddress-Objekten, die jeweils die Details einer eindeutigen physischen Adresse enthalten.

email

Ein Array von Strings, die E-Mail-Adressen enthalten.

icon

Ein Array von Blob-Objekten, die Bilder einer Person enthalten.

name

Ein Array von Strings, die jeweils einen eindeutigen Namen einer Person enthalten.

tel

Ein Array von Strings, die jeweils eine eindeutige Telefonnummer einer Person enthalten.

Ausnahmen

InvalidStateError DOMException

Wird zurückgegeben, wenn der Browser-Kontext nicht im obersten Level ist, wenn der Kontaktwähler ein Flag anzeigt, das einen bereits existierenden Kontaktwähler kennzeichnet, da nur ein Wähler gleichzeitig existieren kann, oder wenn das Starten eines Kontaktwählers fehlgeschlagen ist.

SecurityError DOMException

Wird zurückgegeben, wenn die Methode nicht durch Nutzeraktivierung ausgelöst wird.

TypeError

Wird zurückgegeben, wenn properties leer ist oder wenn einer der angegebenen Eigenschaften nicht unterstützt wird.

Sicherheit

Transiente Aktivierung ist erforderlich. Der Nutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.

Beispiele

Grundlegendes Beispiel

Im folgenden Beispiel wird ein Array von Eigenschaften festgelegt, die für jeden Kontakt abgerufen werden sollen, sowie ein Optionsobjekt, das die Auswahl mehrerer Kontakte erlaubt.

Eine asynchrone Funktion wird dann definiert, die die select()-Methode verwendet, um dem Nutzer ein Kontaktwähler-Interface zu präsentieren und die ausgewählten Ergebnisse zu verarbeiten. handleResults() ist eine vom Entwickler definierte Funktion.

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.
  }
}

Auswahl nur unterstützter Eigenschaften

Im folgenden Beispiel wird getProperties() verwendet, um sicherzustellen, dass nur unterstützte Eigenschaften übergeben werden. Andernfalls könnte select() einen TypeError werfen. handleResults() ist eine vom Entwickler definierte Funktion.

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.
  }
}

Spezifikationen

Browser-Kompatibilität