Schnellstart: Auswählen von Benutzerkontakten (HTML)
[ Dieser Artikel richtet sich an Windows 8.x- und Windows Phone 8.x-Entwickler, die Windows-Runtime-Apps schreiben. Wenn Sie für Windows 10 entwickeln, finden Sie weitere Informationen unter neueste Dokumentation]
Mit dem Windows.ApplicationModel.Contacts-Namespace verfügen Sie über mehrere Optionen zum Auswählen von Kontakten. Wir zeigen Ihnen hier, wie Sie einen einzelnen Kontakt oder mehrere Kontakte auswählen und wie Sie die Kontaktauswahl so konfigurieren, dass nur die von der App benötigten Kontaktinformationen abgerufen werden.
Voraussetzungen
- Wir empfehlen Ihnen, sich mit Microsoft Visual Studio und den zugehörigen Vorlagen vertraut zu machen.
- Außerdem ist es ratsam, sich mit JavaScript vertraut machen.
Einrichten des Kontaktauswahlfensters
Erstellen Sie eine Instanz von Windows.ApplicationModel.Contacts.ContactPicker, und weisen Sie diese einer Variablen zu.
var picker = Windows.ApplicationModel.Contacts.ContactPicker();
Angeben eines Namens für die Bestätigungstaste
Die Bestätigungstaste ist die Taste, die der Benutzer drückt, um den ausgewählten Kontakt zu bestätigen. Legen Sie den Namen dieser Schaltfläche mit Windows.ApplicationModel.Contacts.CommitButtonText fest.
picker.commitButtonText = "Select";
Festlegen des Auswahlmodus (optional)
Standardmäßig ruft die Kontaktauswahl alle verfügbaren Daten für die von Benutzern ausgewählten Kontakte ab. Mithilfe der selectionMode-Eigenschaft können Sie die Kontaktauswahl so konfigurieren, dass nur die von der App benötigten Datenfelder abgerufen werden. Diese effiziente Verwendungsweise der Kontaktauswahl eignet sich besonders dann, wenn Sie nur einen Teil der verfügbaren Kontaktdaten benötigen.
Legen Sie zunächst die selectionMode-Eigenschaft auf fields fest.
picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.fields;
Geben Sie dann mithilfe der desiredFieldsWithContactFieldType-Eigenschaft die Felder an, die von der Kontaktauswahl abgerufen werden sollen. In diesem Beispiel wird die Kontaktauswahl so konfiguriert, dass E-Mail-Adressen abgerufen werden:
picker.desiredFieldsWithContactFieldType.append(Windows.ApplicationModel.Contacts.ContactFieldType.email);
Starten der Auswahl
Nun können Sie die Auswahl starten. Verwenden Sie pickContactAsync, wenn es dem Benutzer nur möglich sein soll, einen Kontakt auszuwählen. Verwenden Sie zum Verarbeiten des vom Benutzer gewählten Kontakts done. Rufen Sie damit eine Funktion auf, die den von der Auswahl zurückgegebenen Kontakt verarbeitet.
picker.pickContactAsync().done(function (contact) {
if (contact !== null) {
// Create UI to display the contact information for the selected contact
var contactElement = document.createElement("div");
contactElement.className = "contact";
// Display the name
contactElement.appendChild(createTextElement("h3", contact.displayName));
Verwenden Sie pickContactsAsync, wenn es dem Benutzer möglich sein soll, einen oder mehrere Kontakte auszuwählen. Verwenden Sie zum Verarbeiten der vom Benutzer gewählten Kontakte done. Rufen Sie damit eine Funktion auf, die den von der Auswahl zurückgegebenen Kontakt verarbeitet.
picker.pickContactsAsync().done(function (contacts) {
if (contacts.length > 0) {
// Display the selected contact names
var output = "Selected contacts:\n";
contacts.forEach(function (contact) {
output += contact.displayName + "\n";
});
Vollständiges Beispiel (einzelner Kontakt)
In diesem Beispiel werden mithilfe der Kontaktauswahl der Name, E-Mail-Adressen, Telefonnummern und Adressen eines einzelnen Kontakts abgerufen.
(function () {
"use strict";
var page = WinJS.UI.Pages.define("/html/scenarioSingle.html", {
ready: function (element, options) {
// Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
element.querySelector("#open").addEventListener("click", pickContact, false);
}
});
function pickContact() {
// Clean scenario output
WinJS.log && WinJS.log("", "sample", "status");
// Create the picker
var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
picker.commitButtonText = "Select";
// Open the picker for the user to select a contact
picker.pickContactAsync().done(function (contact) {
if (contact !== null) {
// Create UI to display the contact information for the selected contact
var contactElement = document.createElement("div");
contactElement.className = "contact";
// Display the name
contactElement.appendChild(createTextElement("h3", contact.displayName));
// Add the different types of contact data
if (contact.emails.length > 0) {
contactElement.appendChild(createTextElement("h4", "Emails:"));
contact.emails.forEach(function (email) {
switch (email.kind) {
case Windows.ApplicationModel.Contacts.ContactEmailKind.personal:
contactElement.appendChild(createTextElement("div", email.address + " (personal)"));
break;
case Windows.ApplicationModel.Contacts.ContactEmailKind.work:
contactElement.appendChild(createTextElement("div", email.address + " (work)"));
break;
case Windows.ApplicationModel.Contacts.ContactEmailKind.other:
contactElement.appendChild(createTextElement("div", email.address + " (other)"));
break;
}
});
}
if (contact.phones.length > 0) {
contactElement.appendChild(createTextElement("h4", "Phone Numbers:"));
contact.phones.forEach(function (phone) {
switch (phone.kind) {
case Windows.ApplicationModel.Contacts.ContactPhoneKind.home:
contactElement.appendChild(createTextElement("div", phone.number + " (home)" ));
break;
case Windows.ApplicationModel.Contacts.ContactPhoneKind.work:
contactElement.appendChild(createTextElement("div", phone.number + " (work)" ));
break;
case Windows.ApplicationModel.Contacts.ContactPhoneKind.mobile:
contactElement.appendChild(createTextElement("div", phone.number + " (mobile)" ));
break;
case Windows.ApplicationModel.Contacts.ContactPhoneKind.other:
contactElement.appendChild(createTextElement("div", phone.number + " (other)" ));
break;
}
});
}
if (contact.addresses.length > 0) {
contactElement.appendChild(createTextElement("h4", "Addresses:"));
contact.addresses.forEach(function (address) {
switch (address.kind) {
case Windows.ApplicationModel.Contacts.ContactAddressKind.home:
contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (home)" ));
break;
case Windows.ApplicationModel.Contacts.ContactAddressKind.work:
contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (work)"));
break;
case Windows.ApplicationModel.Contacts.ContactAddressKind.other:
contactElement.appendChild(createTextElement("div", getUnstructuredAddress(address) + " (other)"));
break;
}
});
}
// Add the contact element to the page
document.getElementById("output").appendChild(contactElement);
} else {
// The picker was dismissed without selecting a contact
WinJS.log && WinJS.log("No contact was selected", "sample", "status");
}
});
}
function createTextElement(tag, text) {
var element = document.createElement(tag);
element.className = "singleLineText";
element.innerText = text;
return element;
}
function getUnstructuredAddress(contactAddress) {
var unstructuredAddress = contactAddress.streetAddress + ", " + contactAddress.locality + ", " + contactAddress.region + ", " + contactAddress.postalCode;
return unstructuredAddress;
}
})();
Vollständiges Beispiel (mehrere Kontakte)
In diesem Beispiel werden mithilfe der Kontaktauswahl mehrere Kontakte abgerufen und dann die Kontaktnamen angezeigt.
(function () {
"use strict";
var page = WinJS.UI.Pages.define("/html/scenarioMultiple.html", {
ready: function (element, options) {
// Use element.querySelector() instead of document.getElementById() to ensure that the correct default.html page is targeted.
element.querySelector("#open").addEventListener("click", pickContacts, false);
}
});
function pickContacts() {
// Clean scenario output
WinJS.log && WinJS.log("", "sample", "status");
// Create the picker
var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
picker.commitButtonText = "Select";
// Open the picker for the user to select contacts
picker.pickContactsAsync().done(function (contacts) {
if (contacts.length > 0) {
// Display the selected contact names
var output = "Selected contacts:\n";
contacts.forEach(function (contact) {
output += contact.displayName + "\n";
});
WinJS.log && WinJS.log(output, "sample", "status");
} else {
// The picker was dismissed without selecting any contacts
WinJS.log && WinJS.log("No contacts were selected", "sample", "status");
}
});
}
})();
Zusammenfassung und nächste Schritte
Sie verfügen jetzt über grundlegende Kenntnisse der Verwendung der Kontaktauswahl zum Abrufen von Kontaktinformationen. Laden Sie die Beispiel-App für die Kontaktauswahl aus der Codegalerie herunter, wenn Sie weitere Beispiele für die Verwendung von Kontakten und der Kontaktauswahl sehen möchten.