ContactsManager: select() Methode

properties

Ein Array von Strings, die definieren, welche Informationen aus 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 Boolean, der es erlaubt, mehrere Kontakte auszuwählen. Der Standardwert ist false.

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

address

Ein Array von ContactAddress Objekten, von denen jedes die Details einer eindeutigen physischen Adresse enthält.

email

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

icon

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

name

Ein Array von Strings, von denen jeder einen eindeutigen Namen einer Person enthält.

tel

Ein Array von Strings, von denen jeder eine eindeutige Telefonnummer einer Person enthält.

InvalidStateError DOMException

Wird zurückgegeben, wenn der Browsing-Kontext nicht auf oberster Ebene ist, wenn der Kontaktpicker eine Markierung anzeigt, die einen bereits vorhandenen Kontaktpicker anzeigt, da zu jedem Zeitpunkt nur ein Picker existieren kann, oder wenn das Starten eines Kontaktpickers fehlschlägt.

SecurityError DOMException

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

TypeError

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

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, und setzt ein Optionsobjekt, um die Auswahl mehrerer Kontakte zu ermöglichen.

Eine asynchrone Funktion wird dann definiert, die die select() Methode verwendet, um dem Benutzer eine Kontaktpicker-Oberfläche zu präsentieren und die gewä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 auslösen. 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.
  }
}