Signatur
Beschreibung
Die Methode getProperties() der Schnittstelle ContactsManager (erreichbar über navigator.contacts) ermittelt, welche Kontakt-Eigenschaften der Browser bzw. das Betriebssystem liefern kann. Das Promise wird mit einem Array von Zeichenketten erfüllt. Mögliche Werte sind "address", "email", "icon", "name" und "tel".
Die Methode ruft man vor ContactsManager.select() auf. Wenn select() eine Eigenschaft anfordert, die nicht unterstützt wird, wird das Promise mit einem TypeError abgelehnt. Mit getProperties() kann man die Anfrage also vorher auf die verfügbaren Eigenschaften einschränken und die Oberfläche passend anpassen, etwa ein Adressfeld nur anzeigen, wenn Adressen auch geliefert werden können.
Anders als select() braucht getProperties() weder eine Nutzergeste noch zeigt es einen Auswahldialog. Die Methode gibt keine persönlichen Daten preis, sondern nur die Fähigkeiten des Geräts.
Rückgabewert
Promise, das mit einem Array der unterstützten Eigenschaftsnamen erfüllt wird, z. B. ["email", "name", "tel"]. Mögliche Einträge: "address", "email", "icon", "name", "tel".Beispiele
Unterstützte Eigenschaften ermitteln
const logSupportedProperties = async () => {
if (!('contacts' in navigator && 'ContactsManager' in window)) {
console.log('Contact Picker API wird nicht unterstützt');
return;
}
const props = await navigator.contacts.getProperties();
console.log(props);
};
logSupportedProperties();Nur verfügbare Eigenschaften mit select() anfordern
const pickButton = document.querySelector('#kontakt-waehlen');
pickButton.addEventListener('click', async () => {
const wanted = ['name', 'email', 'tel', 'address'];
const supported = await navigator.contacts.getProperties();
// Nur Eigenschaften anfragen, die das Gerät kennt – sonst TypeError
const props = wanted.filter((p) => supported.includes(p));
try {
const contacts = await navigator.contacts.select(props, { multiple: false });
console.log(contacts[0]?.name?.[0] ?? 'Keine Auswahl');
} catch (err) {
console.error('Auswahl fehlgeschlagen:', err);
}
});Formular abhängig von den Fähigkeiten anpassen
const setupContactForm = async () => {
const addressField = document.querySelector('#adresse-uebernehmen');
if (!('contacts' in navigator)) {
addressField.hidden = true;
return;
}
const supported = await navigator.contacts.getProperties();
// Button "Adresse aus Kontakten" nur zeigen, wenn Adressen verfügbar sind
addressField.hidden = !supported.includes('address');
};
setupContactForm();// Wichtig · Fallstricke
- Experimentell und kaum unterstützt: Die Contact Picker API gibt es bisher nur in Chromium-Browsern unter Android (ab Version 80). Desktop-Browser, Firefox und Safari (bei Safari auf iOS allenfalls hinter einem Flag) unterstützen sie nicht. Vorher immer prüfen, z. B. mit
'contacts' in navigator && 'ContactsManager' in window. - Sicherer Kontext: Die API steht nur über HTTPS (oder
localhost) und nur im obersten Browsing-Kontext zur Verfügung, also nicht in Cross-Origin-iframes. - Welche Eigenschaften zurückkommen, hängt vom Browser und vom Betriebssystem ab. Die Liste deshalb nicht fest einprogrammieren, sondern bei jedem Aufruf auswerten.
- Ein unterstützter Eintrag bedeutet nicht, dass jeder Kontakt dafür auch Daten hat. Leere Arrays im Ergebnis von
select()einplanen. "address"und"icon"sind später dazugekommen als"name","email"und"tel"und fehlen auf älteren Versionen.