Guida introduttiva: Selezione dei contatti dell'utente (HTML)
[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]
Con lo spazio dei nomi Windows.ApplicationModel.Contacts hai a disposizione varie opzioni per la selezione dei contatti. In questo articolo ti mostreremo come selezionare uno o più contatti e come configurare la selezione contatti in modo da recuperare solo le informazioni sui contatti di cui la tua app ha bisogno.
Prerequisiti
- Ti consigliamo di avere già familiarità con Microsoft Visual Studio e i modelli associati.
- Ti consigliamo di avere già familiarità con Javascript.
Impostare la selezione contatti
Crea un'istanza di Windows.ApplicationModel.Contacts.ContactPicker e assegnala a una variabile.
var picker = Windows.ApplicationModel.Contacts.ContactPicker();
Specificare un nome per il pulsante di conferma
Il pulsante di conferma è il pulsante usato dagli utenti per confermare il contatto selezionato. Imposta il nome del pulsante con Windows.ApplicationModel.Contacts.CommitButtonText.
picker.commitButtonText = "Select";
Impostare la modalità di selezione (facoltativo)
Per impostazione predefinita, la selezione contatti recupera tutti i dati disponibili relativi ai contatti selezionati dall'utente. La proprietà selectionMode ti permette di configurare la selezione contatti in modo che recuperi solo i campi di dati necessari all'app. È un modo più efficiente di usare la selezione contatti nei casi in cui hai bisogno solo di un sottoinsieme delle informazioni sui contatti disponibili.
Per iniziare, imposta la proprietà selectionMode su fields.
picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.fields;
Usa quindi la proprietà desiredFieldsWithContactFieldType per specificare i campi che devono essere recuperati dalla selezione contatti. L'esempio seguente configura la selezione contatti in modo da recuperare gli indirizzi email:
picker.desiredFieldsWithContactFieldType.append(Windows.ApplicationModel.Contacts.ContactFieldType.email);
Avviare la selezione contatti
A questo punto puoi avviare la selezione contatti. Usa pickContactAsync se vuoi che l'utente selezioni solo un contatto. Per elaborare il contatto selezionato dall'utente, usa done per chiamare una funzione che elabori il contatto restituito dalla selezione contatti.
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));
Usa pickContactsAsync se vuoi che l'utente selezioni uno o più contatti. Per elaborare i contatti selezionati dall'utente, usa done per chiamare una funzione che elabori i contatti restituiti dalla selezione contatti.
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";
});
Esempio completo (contatto singolo)
Questo esempio usa la selezione contatti per recuperare il nome, gli indirizzi email, i numeri di telefono e gli indirizzi di un singolo contatto.
(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;
}
})();
Esempio completo (più contatti)
Questo esempio usa la selezione contatti per recuperare più contatti e visualizzarne i nomi.
(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");
}
});
}
})();
Riepilogo e passaggi successivi
Ora hai acquisito le conoscenze di base sull'uso della selezione contatti per recuperare le informazioni sui contatti. Scarica l'esempio di app di selezione contatti dalla Code Gallery per vedere altri esempi di uso dei contatti e della selezione contatti.