ContactsManager.select() — Methode · JavaScript-Referenz

Signatur

ContactsManager.prototype.select(properties, options)

Beschreibung

Die Methode select() gehört zur Contact Picker API und wird über navigator.contacts aufgerufen. Sie öffnet den nativen Kontaktwähler des Betriebssystems. Dort wählt der Nutzer selbst aus, welche Kontakte und welche Eigenschaften (Name, E-Mail, Telefonnummer, Adresse, Profilbild) die Webseite bekommt. Die Seite erhält dabei nie Zugriff auf das komplette Adressbuch, sondern nur auf das, was der Nutzer ausdrücklich freigibt.

Typische Anwendungsfälle sind Web-Apps, die ihre Nutzer Freunde einladen, eine Empfängerliste für Nachrichten zusammenstellen oder Formularfelder (z. B. Telefonnummer oder Lieferadresse) aus einem Kontakt füllen lassen. So muss niemand Daten mühsam von Hand abtippen.

Das zurückgegebene Promise wird mit einem Array von Kontaktobjekten aufgelöst. Jedes Objekt enthält nur die angeforderten Eigenschaften, und jeder Wert ist ein Array, weil ein Kontakt z. B. mehrere Telefonnummern haben kann. Bricht der Nutzer den Wähler ab, wird das Promise mit einem leeren Array aufgelöst.

Die Methode funktioniert nur in einem sicheren Kontext (HTTPS), nur im obersten Browsing-Kontext (nicht in iframes) und nur als Reaktion auf eine Nutzeraktion (transient user activation), also etwa innerhalb eines click-Handlers.

Parameter

Name	Typ	Default	Beschreibung
$properties Pflicht	Array<string>		Liste der Kontakteigenschaften, die abgefragt werden sollen. Mögliche Werte: `'name'`, `'email'`, `'tel'`, `'address'`, `'icon'`. Welche davon unterstützt werden, liefert `ContactsManager.getProperties()`.
$options	Object	{}	Optionales Objekt mit Einstellungen für den Wähler.
$options.multiple	boolean	false	Bei `true` darf der Nutzer mehrere Kontakte auswählen.

Rückgabewert

Typ

Promise<Array<ContactInfo>>

Beschreibung

Ein Promise, das mit einem Array von Kontaktobjekten aufgelöst wird. Jedes Objekt kann die Schlüssel name (string[]), email (string[]), tel (string[]), address (ContactAddress[]) und icon (Blob[]) enthalten. Bricht der Nutzer ab, ist das Array leer.

Beispiele

Einen einzelnen Kontakt auswählen und Formular füllen

const button = document.querySelector('#kontakt-waehlen');
const telInput = document.querySelector('#telefon');

button.addEventListener('click', async () => {
  // Feature-Erkennung
  if (!('contacts' in navigator && 'ContactsManager' in window)) {
    alert('Kontaktwähler wird nicht unterstützt.');
    return;
  }
  try {
    const [kontakt] = await navigator.contacts.select(['name', 'tel']);
    if (!kontakt) return; // Nutzer hat abgebrochen
    telInput.value = kontakt.tel?.[0] ?? '';
    console.log(`Gewählt: ${kontakt.name?.[0]}`);
  } catch (err) {
    console.error('Auswahl fehlgeschlagen:', err.name, err.message);
  }
});

Gewählt: Anna Müller

Mehrere Kontakte für eine Einladung auswählen

const einladen = async () => {
  const kontakte = await navigator.contacts.select(['name', 'email'], {
    multiple: true
  });

  const empfaenger = kontakte
    .filter((k) => k.email?.length)
    .map((k) => ({ name: k.name?.[0] ?? 'Unbekannt', email: k.email[0] }));

  console.log(`${empfaenger.length} Einladung(en) vorbereitet`, empfaenger);
  return empfaenger;
};

document.querySelector('#einladen').addEventListener('click', einladen);

2 Einladung(en) vorbereitet [{ name: 'Anna Müller', email: 'anna@example.com' }, { name: 'Ben Koch', email: 'ben@example.com' }]

Nur unterstützte Eigenschaften anfordern

document.querySelector('#import').addEventListener('click', async () => {
  const gewuenscht = ['name', 'email', 'tel', 'address', 'icon'];
  const verfuegbar = await navigator.contacts.getProperties();
  const props = gewuenscht.filter((p) => verfuegbar.includes(p));

  const kontakte = await navigator.contacts.select(props, { multiple: true });

  for (const k of kontakte) {
    if (k.icon?.[0]) {
      const img = document.createElement('img');
      img.src = URL.createObjectURL(k.icon[0]);
      img.alt = k.name?.[0] ?? '';
      document.body.append(img);
    }
  }
  console.log('Angefordert:', props);
});

Angefordert: ['name', 'email', 'tel', 'address', 'icon']

// Wichtig · Fallstricke

Browser-Kompatibilität: Die API ist experimentell und praktisch nur in Chrome für Android (ab Version 80) und darauf aufbauenden Browsern verfügbar. Desktop-Browser, Firefox und Safari unterstützen sie standardmäßig nicht (in iOS-Safari nur hinter einem Experimental-Flag). Prüfe die Unterstützung immer mit 'contacts' in navigator und biete eine manuelle Eingabe als Ausweichlösung an.

Fehlerfälle: Ohne Nutzeraktion, in einem iframe oder außerhalb des sichtbaren Tabs wird das Promise mit einem SecurityError bzw. InvalidStateError abgelehnt. Ein Wähler, der schon offen ist, führt ebenfalls zu InvalidStateError. Ein leeres oder ungültiges properties-Array löst einen TypeError aus.
Werte sind Arrays: Auch bei nur einem Namen gilt kontakt.name ist ['Anna'], nicht 'Anna'. Nicht angeforderte oder leere Eigenschaften können fehlen oder leere Arrays sein. Nutze daher optionale Verkettung (?.[0]).
Abbruch ist kein Fehler: Schließt der Nutzer den Wähler, wird das Promise mit [] aufgelöst und nicht abgelehnt.
Datenschutz: Fordere nur die Eigenschaften an, die du wirklich brauchst. Kontaktdaten sind personenbezogene Daten Dritter, deshalb gelten beim Übertragen an einen Server die Regeln der DSGVO.
Objekt-URLs aus icon-Blobs nach Gebrauch mit URL.revokeObjectURL() freigeben.

Siehe auch

Navigator.contacts Promise new SpeechSynthesisEvent() ContactsManager.getProperties() LockManager.request()