ContactsManager — Schnittstelle · JavaScript-Referenz

Signatur

interface ContactsManager

Beschreibung

Das ContactsManager-Interface ist der Einstiegspunkt der Contact Picker API. Man erreicht die einzige Instanz über navigator.contacts. Sie stellt eine native, vom Browser gesteuerte Kontaktauswahl bereit. Die Website bekommt dabei nie das ganze Adressbuch zu sehen, sondern nur die Kontakte und Felder, die der Nutzer ausdrücklich freigibt.

Das Interface hat zwei Methoden:

getProperties(): Gibt ein Promise<string[]> mit den Feldern zurück, die die Plattform unterstützt, zum Beispiel "name", "email", "tel", "address" oder "icon".
select(properties, options): Öffnet die Kontaktauswahl und gibt ein Promise zurück, das mit einem Array von Kontaktobjekten erfüllt wird. Jede angefragte Eigenschaft ist darin ein Array, weil ein Kontakt zum Beispiel mehrere Telefonnummern haben kann.

Typische Einsatzfälle sind Freunde einladen, eine Empfängeradresse für den Versand übernehmen, Telefonnummern für Messenger-Funktionen eintragen oder Formulare schneller ausfüllen. Die API funktioniert nur in einem sicheren Kontext (HTTPS), nur im obersten Browserkontext (nicht in eingebetteten iframes) und nur nach einer Nutzeraktion, etwa einem Klick.

Parameter

Name	Typ	Default	Beschreibung
$properties Pflicht	string[]		Parameter von `select()`: Liste der gewünschten Kontaktfelder, z. B. `["name", "email", "tel"]`. Gültige Werte: `"name"`, `"email"`, `"tel"`, `"address"`, `"icon"`. Fordert man ein Feld an, das nicht unterstützt wird, wird das Promise mit einem `TypeError` abgelehnt.
$options	{ multiple?: boolean }	{ multiple: false }	Parameter von `select()`: Mit `multiple: true` darf der Nutzer mehrere Kontakte auswählen.

Rückgabewert

Typ

ContactsManager

Beschreibung

Wird über navigator.contacts erreicht. select() gibt Promise<ContactInfo[]> zurück, getProperties() gibt Promise<string[]> zurück. ContactInfo ist ein Objekt mit Arrays: name: string[], email: string[], tel: string[], address: ContactAddress[], icon: Blob[].

Beispiele

Unterstützung prüfen und verfügbare Felder abfragen

const isSupported = 'contacts' in navigator && 'ContactsManager' in window;

if (isSupported) {
  const props = await navigator.contacts.getProperties();
  console.log('Unterstützte Felder:', props);
} else {
  console.log('Contact Picker API nicht verfügbar – Formular manuell ausfüllen.');
}

Unterstützte Felder: ["email", "name", "tel", "address", "icon"]

Freunde einladen: mehrere Kontakte per Klick auswählen

const button = document.querySelector('#invite');

button.addEventListener('click', async () => {
  try {
    const contacts = await navigator.contacts.select(['name', 'email'], { multiple: true });

    if (contacts.length === 0) {
      console.log('Auswahl abgebrochen.');
      return;
    }

    const invites = contacts
      .filter((c) => c.email.length > 0)
      .map((c) => ({ name: c.name[0] ?? 'Unbekannt', email: c.email[0] }));

    console.log(invites);
  } catch (err) {
    console.error('Kontaktauswahl fehlgeschlagen:', err.name, err.message);
  }
});

[{ name: "Anna Schmidt", email: "anna@example.com" }, { name: "Ben Meier", email: "ben@example.org" }]

Nur Felder anfragen, die unterstützt werden, und ein Formular füllen

const fillShipping = async () => {
  const wanted = ['name', 'tel', 'address'];
  const available = await navigator.contacts.getProperties();
  const props = wanted.filter((p) => available.includes(p));

  const [contact] = await navigator.contacts.select(props);
  if (!contact) return;

  document.querySelector('#name').value = contact.name?.[0] ?? '';
  document.querySelector('#tel').value = contact.tel?.[0] ?? '';

  const addr = contact.address?.[0];
  if (addr) {
    document.querySelector('#street').value = addr.addressLine.join(', ');
    document.querySelector('#zip').value = addr.postalCode;
    document.querySelector('#city').value = addr.city;
  }
};

document.querySelector('#pick-contact').addEventListener('click', fillShipping);

// Wichtig · Fallstricke

Experimentell und kaum verbreitet: Die API gibt es praktisch nur in Chromium-Browsern auf Android (Chrome 80+, Samsung Internet). Desktop-Browser, Firefox und Safari (dort nur hinter einem Flag unter iOS) unterstützen sie nicht. Sieh deshalb immer einen Ersatzweg vor, etwa ein manuelles Eingabeformular, und prüfe die Unterstützung mit 'contacts' in navigator.
Nutzeraktion nötig: select() muss aus einem Handler für eine Nutzeraktion aufgerufen werden, etwa bei einem Klick. Sonst wird das Promise mit einem SecurityError abgelehnt. Ist schon eine Auswahl offen, führt ein weiterer Aufruf zu einem InvalidStateError.
Nur sicherer Kontext: Die API funktioniert nur über HTTPS und nur im obersten Browserkontext.
Abbruch: Schließt der Nutzer die Auswahl, ohne etwas auszuwählen, wird das Promise mit einem leeren Array erfüllt (nicht abgelehnt).
Felder sind Arrays: Jedes Feld kann leer sein oder mehrere Werte haben. Greife deshalb vorsichtig zu, etwa mit c.email[0] ?? ''.
Datenschutz: Fordere nur die Felder an, die du wirklich brauchst. Kontaktdaten Dritter sind personenbezogene Daten im Sinne der DSGVO. Übertrage und speichere sie nur mit Rechtsgrundlage und klarer Information an den Nutzer.

Siehe auch

ContactsManager.select() ContactsManager.getProperties() Navigator.contacts ContactAddress Navigator PaymentManager