Signatur
Beschreibung
Die Eigenschaft region eines ContactAddress-Objekts enthält die oberste Verwaltungseinheit unterhalb der Landesebene, also z. B. ein deutsches Bundesland ("Bayern"), einen US-Bundesstaat ("CA" oder "California"), eine kanadische Provinz oder eine japanische Präfektur. Welche Einheit gemeint ist, hängt vom Adressformat des jeweiligen Landes ab.
ContactAddress-Objekte bekommt man ausschließlich über die Contact Picker API: Ruft man navigator.contacts.select() mit der Eigenschaft 'address' auf, enthält jeder zurückgegebene Kontakt ein Array address mit ContactAddress-Einträgen. Die Eigenschaft ist schreibgeschützt und spiegelt nur wider, was im Adressbuch des Geräts hinterlegt ist.
Praktisch nutzt man region beim Vorausfüllen von Adress- oder Versandformularen, etwa zum Befüllen eines Feldes „Bundesland/Region“. Da viele Länder keine Region angeben und Nutzer das Feld oft leer lassen, sollte man stets mit einer leeren Zeichenfolge rechnen und den Wert nicht als Pflichtangabe voraussetzen.
Rückgabewert
"".Beispiele
Region des ersten Adresseintrags auslesen
const button = document.querySelector('#kontakt-waehlen');
button.addEventListener('click', async () => {
// Contact Picker nur nach Nutzergeste aufrufbar
const [kontakt] = await navigator.contacts.select(['name', 'address']);
const adresse = kontakt?.address?.[0];
if (adresse) {
console.log(`Region: ${adresse.region || '(keine Angabe)'}`);
}
});Versandformular vorausfüllen mit Feature-Erkennung
const unterstuetzt = 'contacts' in navigator && 'ContactsManager' in window;
const formularAusfuellen = async () => {
if (!unterstuetzt) {
console.warn('Contact Picker API nicht verfügbar');
return;
}
const verfuegbar = await navigator.contacts.getProperties();
if (!verfuegbar.includes('address')) return;
const [kontakt] = await navigator.contacts.select(['address']);
const adr = kontakt?.address?.[0];
if (!adr) return;
document.querySelector('#plz').value = adr.postalCode;
document.querySelector('#ort').value = adr.city;
document.querySelector('#region').value = adr.region;
document.querySelector('#land').value = adr.country;
};
document.querySelector('#adresse-uebernehmen')
.addEventListener('click', formularAusfuellen);Alle Regionen mehrerer Kontakte sammeln
document.querySelector('#mehrere').addEventListener('click', async () => {
const kontakte = await navigator.contacts.select(['name', 'address'], { multiple: true });
const regionen = new Set(
kontakte
.flatMap((k) => k.address ?? [])
.map((a) => a.region)
.filter(Boolean) // leere Zeichenfolgen verwerfen
);
console.log([...regionen]);
});// Wichtig · Fallstricke
- Experimentell und kaum unterstützt: Die Contact Picker API gibt es praktisch nur in Chrome für Android (ab 80). Desktop-Browser, Firefox und Safari (dort nur hinter Flag) bieten sie nicht an. Immer vorher per Feature-Erkennung prüfen (
'contacts' in navigator) und mitnavigator.contacts.getProperties()klären, ob'address'unterstützt wird. - Voraussetzungen: Sichere Verbindung (HTTPS), Aufruf im obersten Browsing-Kontext und nur nach einer Nutzergeste (z. B. Klick). Sonst wird das Promise von
select()abgelehnt. - Kein einheitliches Format:
regionkann ein voller Name ("California") oder ein Kürzel ("CA") sein, je nachdem, was der Nutzer gespeichert hat. Nicht gegen feste Listen prüfen, ohne vorher zu normalisieren. - Der Wert ist oft leer, weil viele Länder (oder Nutzer) keine Region angeben. Leere Zeichenfolge nicht mit fehlender Adresse verwechseln.
- Datenschutz: Adressdaten sind personenbezogen. Nur die Eigenschaften anfragen, die wirklich gebraucht werden, und die Daten nicht ungefragt an den Server schicken.