ContactAddress — Schnittstelle · JavaScript-Referenz

Signatur

interface ContactAddress

Beschreibung

ContactAddress ist ein reines Datenobjekt der Contact Picker API. Instanzen erzeugt man nicht selbst. Man erhält sie, wenn man navigator.contacts.select() mit der Eigenschaft 'address' aufruft: Jeder zurückgegebene Kontakt hat dann ein Array address, das aus ContactAddress-Objekten besteht.

Aufgebaut ist das Interface wie das frühere PaymentAddress der Payment Request API. Es hat nur schreibgeschützte Eigenschaften:

addressLine (string[]): Straße, Hausnummer, Zusatzzeilen
city: Ort bzw. Stadt
country: Ländercode nach ISO 3166-1 Alpha-2, z. B. "DE"
dependentLocality: Ortsteil bzw. Stadtbezirk
organization: Firma oder Organisation
phone: Telefonnummer zur Adresse
postalCode: Postleitzahl
recipient: Name des Empfängers
region: Bundesland, Kanton oder Provinz
sortingCode: Sortiercode, den manche Länder nutzen (z. B. CEDEX in Frankreich)

Mit der Methode toJSON() bekommt man ein einfaches Objekt mit allen Feldern. Das ist praktisch, wenn man die Adresse an einen Server schicken oder speichern will. Typischer Einsatz: Formulare mit Liefer- oder Rechnungsadressen vorausfüllen, ohne dass die Webseite dauerhaft auf das Adressbuch zugreifen kann. Der Nutzer entscheidet bei jedem Aufruf selbst, welche Kontakte er freigibt.

Rückgabewert

Typ

ContactAddress

Beschreibung

Kommt nur als Element im Array contact.address vor, das navigator.contacts.select() liefert. Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Adresse eines Kontakts auswählen und auslesen

// Muss durch eine Nutzeraktion (z. B. Klick) ausgelöst werden
const button = document.querySelector('#kontakt-waehlen');

button.addEventListener('click', async () => {
  if (!('contacts' in navigator)) {
    console.log('Contact Picker API wird nicht unterstützt');
    return;
  }

  const supported = await navigator.contacts.getProperties();
  if (!supported.includes('address')) {
    console.log('Adressen werden nicht unterstützt');
    return;
  }

  try {
    const [contact] = await navigator.contacts.select(['name', 'address']);
    const address = contact?.address?.[0]; // ContactAddress
    if (address) {
      console.log(address.addressLine.join(', '));
      console.log(`${address.postalCode} ${address.city}`);
      console.log(address.country);
    }
  } catch (err) {
    console.error('Auswahl abgebrochen oder fehlgeschlagen:', err);
  }
});

Musterstraße 12 10115 Berlin DE

Lieferformular aus einer ContactAddress befüllen

const fillShippingForm = (address) => {
  const form = document.forms.lieferung;
  form.empfaenger.value = address.recipient ?? '';
  form.firma.value = address.organization ?? '';
  form.strasse.value = (address.addressLine ?? []).join('\n');
  form.plz.value = address.postalCode ?? '';
  form.ort.value = address.city ?? '';
  form.region.value = address.region ?? '';
  form.land.value = address.country ?? '';
};

document.querySelector('#adresse-importieren').addEventListener('click', async () => {
  const contacts = await navigator.contacts.select(['address']);
  const first = contacts[0]?.address?.[0];
  if (first) fillShippingForm(first);
});

Adressen per toJSON() an den Server senden

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

  // Jede ContactAddress in ein einfaches Objekt umwandeln
  const payload = contacts.flatMap((c) =>
    (c.address ?? []).map((addr) => ({
      name: c.name?.[0] ?? '',
      ...addr.toJSON()
    }))
  );

  console.log(JSON.stringify(payload[0], null, 2));

  await fetch('/api/adressen', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });
};

document.querySelector('#import').addEventListener('click', importAddresses);

{ "name": "Erika Mustermann", "addressLine": ["Musterstraße 12"], "city": "Berlin", "country": "DE", "postalCode": "10115", ... }

// Wichtig · Fallstricke

Stark eingeschränkte Unterstützung: Die API ist experimentell und läuft praktisch nur in Chrome für Android (ab Version 80) und darauf aufbauenden Browsern. Desktop-Browser, Firefox und Safari unterstützen sie nicht (in Safari höchstens hinter einem Feature-Flag). Deshalb immer zuerst mit 'contacts' in navigator prüfen und eine Eingabe von Hand als Ausweichlösung anbieten.
Vor der Abfrage mit navigator.contacts.getProperties() klären, ob 'address' überhaupt verfügbar ist. Sonst wirft select() einen TypeError.
Die API funktioniert nur im sicheren Kontext (HTTPS), nur im obersten Browserfenster (Top-Level-Frame) und nur nach einer Nutzeraktion wie einem Klick. Ohne diese Aktion schlägt select() mit einem SecurityError fehl.
Jedes Feld kann leer sein ("" bzw. ein leeres Array). Welche Felder gefüllt sind, hängt vom Adressbuch des Geräts ab. Also nicht davon ausgehen, dass etwa postalCode oder region vorhanden ist.
country ist ein Ländercode ("DE"), kein Ländername. Für die Anzeige kann man Intl.DisplayNames verwenden.
Datenschutz: Adressen sind personenbezogene Daten. Nur so viel abfragen wie nötig, die Übertragung verschlüsseln und die Regeln der DSGVO beachten.

Siehe auch

Navigator.contacts PaymentAddress ContactsManager ContentIndex CanvasGradient