Inicio rápido: seleccionar contactos de usuarios (HTML)
[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente
Mediante el espacio de nombres de Windows.ApplicationModel.Contacts, tienes varias opciones para seleccionar contactos. Aquí te mostraremos cómo seleccionar un único contacto o varios contactos, y aprenderás a configurar el selector de contactos para recuperar solamente la información de contacto que necesita tu aplicación.
Requisitos previos
- Te recomendamos que estés familiarizado con Microsoft Visual Studio y sus plantillas asociadas.
- Te recomendamos que estés familiarizado con JavaScript.
Configuración del selector de contactos
Crea una instancia de Windows.ApplicationModel.Contacts.ContactPicker y asígnale una variable.
var picker = Windows.ApplicationModel.Contacts.ContactPicker();
Asignación de un nombre para el botón de confirmación
El botón de confirmación es el botón que el usuario presiona para confirmar el contacto seleccionado. Establece el nombre de este botón mediante Windows.ApplicationModel.Contacts.CommitButtonText.
picker.commitButtonText = "Select";
Establecer el modo de selección (opcional)
De manera predeterminada, el selector de contactos recupera todos los datos disponibles para los contactos que selecciona el usuario. La propiedad selectionMode permite configurar el selector de contactos para recuperar únicamente los campos de datos que necesita la aplicación. Esta es una forma más eficaz de usar el selector de contactos si solo necesitas un subconjunto de los datos de contacto disponibles.
Primero, establece la propiedad selectionMode en fields.
picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.fields;
Después, usa la propiedad desiredFieldsWithContactFieldType para especificar los campos que quieres que recupere el selector de contactos. En este ejemplo se configura el selector de contactos para que recupere direcciones de correo electrónico:
picker.desiredFieldsWithContactFieldType.append(Windows.ApplicationModel.Contacts.ContactFieldType.email);
Inicio del selector
Ahora, puedes iniciar el selector. Usa pickContactAsync si quieres que el usuario seleccione solo un contacto. Si deseas procesar los contactos que selecciona el usuario, usa done para llamar a una función para procesar los contactos que devuelve el selector.
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 si quieres que el usuario seleccione uno o varios contactos. Si deseas procesar los contactos que selecciona el usuario, usa done para llamar a una función para procesar los contactos que devuelve el selector.
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";
});
Ejemplo completo (contacto único)
En este ejemplo se usa el selector de contactos para recuperar el nombre, las direcciones de correo electrónico, los números de teléfono y las direcciones de un solo contacto.
(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;
}
})();
Ejemplo completo (varios contactos)
En este ejemplo se usa el selector de contactos para recuperar varios contactos y se muestran los nombres del contacto.
(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");
}
});
}
})();
Resumen y siguientes pasos
Con esto deberías tener nociones básicas sobre cómo usar el selector de contactos para recuperar información de contacto. Descarga la muestra de una aplicación de selector de contactos de la galería de código para ver más ejemplos de cómo usar contactos y el selector de contactos.