ContactAddress.city — Eigenschaft · JavaScript-Referenz

Signatur

ContactAddress.city

Beschreibung

Die Eigenschaft city eines ContactAddress-Objekts enthält den Ort einer Adresse, also die Stadt, Gemeinde oder Ortschaft, z. B. "Berlin" oder "Garmisch-Partenkirchen". ContactAddress-Objekte bekommen Sie nur über die Contact Picker API: Wenn Sie navigator.contacts.select() mit der Eigenschaft 'address' aufrufen, enthält jeder zurückgegebene Kontakt ein Array address mit ContactAddress-Einträgen.

Typische Einsatzfälle sind Bestell- und Lieferformulare, in denen Nutzer eine Adresse direkt aus ihrem Adressbuch übernehmen möchten, statt sie abzutippen. Den Wert von city schreiben Sie dann meist in ein Formularfeld für den Ort, oft zusammen mit postalCode und country.

Die Eigenschaft ist schreibgeschützt. Hat der Kontakt keinen Ort gespeichert, ist der Wert ein leerer String. Das Format hängt vom Land ab: In manchen Ländern steht hier eine Stadt, in anderen eher eine Gemeinde oder ein Postort. Weitere Unterteilungen wie Stadtteile stehen in dependentLocality, Bundesländer oder Regionen in region.

Rückgabewert

Typ

string

Beschreibung

Der Ort (Stadt, Gemeinde, Ortschaft) der Adresse. Ist kein Ort bekannt, ist der Wert ein leerer String "".

Beispiele

Ort aus einem ausgewählten Kontakt lesen

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

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

  try {
    const [kontakt] = await navigator.contacts.select(['name', 'address']);
    const adresse = kontakt?.address?.[0];
    console.log(adresse ? `Ort: ${adresse.city}` : 'Keine Adresse hinterlegt');
  } catch (err) {
    console.error('Auswahl fehlgeschlagen:', err);
  }
});

Ort: München

Lieferformular mit Postleitzahl und Ort befüllen

const form = document.querySelector('#lieferadresse');

document.querySelector('#aus-adressbuch').addEventListener('click', async () => {
  const unterstuetzt = await navigator.contacts?.getProperties?.();
  if (!unterstuetzt?.includes('address')) {
    alert('Adressen können auf diesem Gerät nicht übernommen werden.');
    return;
  }

  const kontakte = await navigator.contacts.select(['address']);
  const adresse = kontakte[0]?.address?.[0];
  if (!adresse) return;

  form.elements.strasse.value = adresse.addressLine.join(', ');
  form.elements.plz.value = adresse.postalCode;
  form.elements.ort.value = adresse.city || ''; // Leerer String, wenn kein Ort gespeichert ist
  form.elements.land.value = adresse.country;
});

Alle Orte mehrerer Kontakte ohne Duplikate sammeln

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

  const orte = new Set(
    kontakte
      .flatMap((k) => k.address ?? [])
      .map((a) => a.city.trim())
      .filter(Boolean)
  );

  console.log([...orte].sort((a, b) => a.localeCompare(b, 'de')));
};

document.querySelector('#orte').addEventListener('click', orteSammeln);

["Berlin", "Hamburg", "Köln"]

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Contact Picker API ist experimentell und wird praktisch nur von Chrome für Android (ab Version 80) unterstützt. Desktop-Browser, Firefox und Safari (dort höchstens hinter einem Flag) bieten sie nicht an. Prüfen Sie die Unterstützung immer vorher mit 'contacts' in navigator und navigator.contacts.getProperties(), ob 'address' verfügbar ist.
navigator.contacts.select() funktioniert nur in einem sicheren Kontext (HTTPS), nur im obersten Browsing-Kontext (nicht in iframes) und nur nach einer Nutzeraktion wie einem Klick. Sonst wird das Promise abgelehnt (SecurityError bzw. InvalidStateError).
Fehlt der Ort, ist city ein leerer String und nicht null. Kontakte ohne Adresse können außerdem ein leeres address-Array haben. Greifen Sie deshalb mit Optional Chaining darauf zu.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird still ignoriert bzw. löst im Strict Mode einen TypeError aus. Um den Wert zu ändern, kopieren Sie ihn in ein eigenes Objekt.
Die Werte stammen aus dem Adressbuch des Nutzers und sind nicht geprüft. Validieren Sie sie vor der Weiterverarbeitung und fügen Sie sie nicht ungeprüft per innerHTML ein (XSS-Gefahr). Nutzen Sie stattdessen textContent.
Adressdaten sind personenbezogen. Übertragen oder speichern Sie sie nur, wenn es nötig ist und die Datenschutzregeln (z. B. DSGVO) das erlauben.

Siehe auch

ContactAddress.country ContactAddress.phone ContactAddress.region ContactAddress.recipient ContactAddress.postalCode