Краткое руководство: выбор контактов пользователя (HTML)
[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]
С помощью пространства имен Windows.ApplicationModel.Contacts вы можете выбирать контакты несколькими способами. В этой статье описано, как выбрать один или несколько контактов, и показано, как настроить окно выбора контактов, чтобы получать только необходимые вашему приложению сведения о контактах.
Необходимые условия
- Рекомендуется освоить программу Microsoft Visual Studio и связанные с ней шаблоны.
- Рекомендуется также иметь навыки разработки на языке JavaScript.
Настройка окна выбора контактов
Создайте экземпляр Windows.ApplicationModel.Contacts.ContactPicker и назначьте его переменной.
var picker = Windows.ApplicationModel.Contacts.ContactPicker();
Указание имени для кнопки фиксации
Кнопка фиксации — это кнопка, которую нажимает пользователь, чтобы подтвердить выбор контакта. Задайте имя кнопки с помощью Windows.ApplicationModel.Contacts.CommitButtonText.
picker.commitButtonText = "Select";
Настройка режима выбора (необязательно)
По умолчанию окно выбора контактов извлекает все доступные данные о контактах, выбранных пользователем. Свойство selectionMode позволят настроить окно выбора контактов так, чтобы получать только поля данных, необходимые вашему приложению. Этот способ использования окна выбора контактов более эффективен, если нужна только часть доступных сведений контакта.
Сначала задайте для свойства selectionMode значение fields:
picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.fields;
Затем при помощи свойства desiredFieldsWithContactFieldType укажите поля, которые должно извлекать окно выбора контактов. В данном примере окно выбора контактов настроено на получение адресов электронной почты:
picker.desiredFieldsWithContactFieldType.append(Windows.ApplicationModel.Contacts.ContactFieldType.email);
Запуск окна выбора контактов
Теперь вы можете запустить окно выбора контактов. Если вы хотите, чтобы пользователь выбрал только один контакт, используйте pickContactAsync. Чтобы обработать данные выбранного пользователем контакта, используйте done для вызова функции обработки контакта, возвращенного окном выбора.
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));
Если вы хотите, чтобы пользователь выбрал один или несколько контактов, используйте pickContactsAsync. Чтобы обработать данные выбранных пользователем контактов, используйте done для вызова функции обработки контактов, возвращенных окном выбора.
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";
});
Полный пример (один контакт)
В данном примере окно выбора контактов извлекает имя, адреса электронной почты, номера телефонов и адреса одного контакта.
(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;
}
})();
Полный пример (несколько контактов)
В данном примере окно выбора контактов извлекает несколько контактов и отображает их имена.
(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");
}
});
}
})();
Краткая сводка и дальнейшие действия
Теперь вы имеете представление об использовании окна выбора контактов для получения контактных данных. Скачайте пример приложения с окном выбора контактов из коллекции исходных кодов, чтобы ознакомиться с другими примерами использования контактов и окна выбора контактов.