ContactsManager: Methode select()

properties

Ein Array von Strings, das definieren, welche Informationen von einem Kontakt abgerufen werden sollen. Zulässige 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 Boolean, der erlaubt, mehrere Kontakte auszuwählen. Der Standardwert ist false.

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

address

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

email

Ein Array von Strings, das E-Mail-Adressen enthält.

icon

Ein Array von Blob-Objekten, das Bilder von Einzelpersonen enthält.

name

Ein Array von Strings, die jeweils einen einzigartigen Namen einer Einzelperson enthalten.

tel

Ein Array von Strings, die jeweils eine einzigartige Telefonnummer einer Einzelperson enthalten.

InvalidStateError DOMException

Wird zurückgegeben, wenn der Browsing-Kontext nicht auf oberster Ebene ist, wenn der Kontaktpicker eine Flagge zeigt, die anzeigt, dass bereits ein bestehender Kontaktpicker vorhanden ist, da immer nur ein Picker existieren kann, oder wenn das Starten eines Kontaktpickers fehlgeschlagen ist.

SecurityError DOMException

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

TypeError

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

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

Das folgende Beispiel setzt ein Array von Eigenschaften, die für jeden Kontakt abgerufen werden sollen, sowie ein Optionsobjekt, das die Auswahl mehrerer Kontakte ermöglicht.

Eine asynchrone Funktion wird dann definiert, die die select()-Methode verwendet, um dem Benutzer ein Kontaktpicker-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.
  }
}

Das folgende Beispiel verwendet getProperties(), 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.
  }
}