Объявления в манифесте
Поставщики средства выбора контактов
Со стороны поставщика, что так же показано в примере "Приложение для выбора контактов" ( http://code.msdn.microsoft.com/windowsapps/Contact-Picker-App-sample-fc6677a1) мы видим тот же шаблон, что и для поставщиков средства выбора файла. Во-первых, приложению-поставщику нужно объявить контракт Выбор контактов (Contact Picker) в манифесте, где задаётся Начальная страница (Start page) для загрузки в контексте средства выбора контактов. В примере начальная страница – это contactPicker.html, которая, в свою очередь, загружает html/contactPickerScenario.html (со связанными с ней файлами JavaScript):
Как и в случае со средством выбора файлов, отдельная начальная страница подразумевает наличие отдельного обработчика активации, в данном случае он ищет вид активации contactPicker (js/contactPicker.js):
function activated(eventObject) {
if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.contactPicker)
{ contactPickerUI = eventObject.detail.contactPickerUI;
eventObject.setPromise(WinJS.UI.processAll().then(function () {
// ...
}));
}
}
Здесь eventObject.detail является объектом ContactPickerActivatedEventArgs (http://msdn.microsoft.com/library/windows/apps/windows.applicationmodel.activation.contactpickeractivatedeventargs.aspx) (эти имена длинные, но, по крайней мере, предсказуемые!). Как и в случае со всеми соыбытиями активации, он содержит свойства kind, previousExecutionState, и splashScreen для обычных целей. Его свойство contactPickerUI, типа ContactPickerUI (http://msdn.microsoft.com/library/windows/apps/windows.applicationmodel.contacts.provider.contactpickerui.aspx), в свою очередь, содержит информацию, специфичную для контракта средства выбора контакта:
- Свойства selectionMode и desiredFields предоставляются вызывающим приложением.
- Три метода: addContact, removeContact, и containsContact —для управления тем, что будет возвращено в вызываемое приложение. Эти методы соответствуют действиям типичного пользовательского интерфейса для выбора объектов.
- Одно событие, contactsRemoved, которое сообщает поставщику, когда пользователь удаляет элемент из корзины объектов, которая расположена вдоль нижней части экрана (вернитесь к рис. 3.10).
Внутри поставщика каждый контакт представлен объектом Windows.ApplicationModel.Contacts.Contact. Поставщик создаст объект для каждого предоставляемого им контакта. В примере (js/contactPickerScenario.js), есть массив, который называется sampleContacts и имитирует то, что обычно поступает из базы данных. Этот массив содержит простые JSON-записи, вроде этих:
{
name: "David Jaffe",
homeEmail: "david@contoso.com",
workEmail: "david@cpandl.com",
workPhone: "",
homePhone: "248-555-0150",
mobilePhone: "",
address: {
full: "3456 Broadway Ln, Los Angeles, CA",
street: "",
city: "",
state: "", zipCode: ""
},
id: "761cb6fb-0270-451e-8725-bb575eeb24d5"
},
Каждая запись представлена в интерфейсе примера в виде поля с флагом (сгенерировано функцией createContactUI), что является быстрым и простым способом отображения списка элементов, поддерживающего выбор! Конечно, ваше приложение-поставщик, вероятнее всего, будет использовать для этих целей ListView. В примере лишь сделана попытка сделать всё как можно более простым, чтобы вы могли видеть, что происходит с самим контрактом.
Когда пользователь выбирает контакт, вызывается функция примера addContactToBasket. Это тот самый момент, когда мы создаём реальный объект Contact и вызываем ContactPickerUI.addContact. За обработкой каждого поля следует цепочка вызовов других функций, поэтому посмотрим, как это работает для одного поля homeEmail в записи источника, начиная с addContactToBasket (опять же, в js/contactPickerScenario.js). Оставшиеся значения полей обрабатываются, в значительной мере, тем же способом.
function addContactToBasket(sampleContact) {
var contact = new Windows.ApplicationModel.Contacts.Contact();
contact.name = sampleContact.name;
appendEmail(contact.fields, sampleContact.homeEmail, Windows.ApplicationModel.Contacts.ContactFieldCategory.home);
// добавить другие поля...
// Добавить контакт в корзину
switch (contactPickerUI.addContact(sampleContact.id, contact)) {
// Показать различные сообщения, основанные на результате, который имеет тип
// Windows.ApplicationModel.Contacts.Provider.AddContactResult
}
}
Как вы можете видеть, поле homeEmail передается в функцию, которая называется appendEmail, первый аргумент которой – это вектор (Contact.fields), в который добавляются поля, а третий параметр – это категория (home). Затем эти данные передаются другой функции общего назначения, appendField, где типы полей объединяются, все они используются для создания объекта ContactField, и он добавляется к контакту:
function appendEmail(fields, email, category) {
// Добавляет новый адрес электронной почты к вектору полей контакта
appendField(fields, email,
Windows.ApplicationModel.Contacts.ContactFieldType.email, category);
}
function appendField(fields, value, type, category) {
// Добавляет новое поле нужного типа, либо адрес электронной почты, либо номер телефона
if (value) {
fields.append(new Windows.ApplicationModel.Contacts.ContactField(value,
type, category));
}
}
Коротко говоря, это главным образом касается того, как собраны все поля в контакте, одно за один раз.
Теперь, когда с элемента в списке снято выделение, нужно удалить его из корзины:
function removeContactFromBasket(sampleContact) {
// Программным путём удаляет контакт из корзины элементов
if (contactPickerUI.containsContact(sampleContact.id)) {
contactPickerUI.removeContact(sampleContact.id);
}
}
Похожим образом, когда пользователь удаляет элемент из корзины, поставщик контакта нуждается в обновлении интерфейса, отражающего выделение контактов, что выполняется путём обработки события contactremoved:
contactPickerUI.addEventListener("contactremoved", onContactRemoved, false);
function onContactRemoved(e) {
// Добавьте любой код, который вызывается, когда пользователь удаляет контакт из корзины
var contactElement = document.getElementById(e.id);
var sampleContact = sampleContacts[contactElement.value];
contactElement.checked = false;
}
Вы могли заметить, что мы ничего не сказали о закрытии пользовательского интерфейса, и, на самом деле объект ContactPickerUI не имеет событий для этого. Проще говоря, когда пользователь нажимает на кнопку подтверждения (с любым текстом, предоставленным вызывающим приложением), он получает всё, что поставщик добавил в корзину. Если пользователь нажмёт на кнопку отмены, операция возвратит контакт null. В обоих случаях, приложение-поставщик будет приостановлено, если оно не было запущено до того, как было активировано для получения контакта, будет автоматически закрыто.
Отметим, что как и в случае с поставщиками выбора файла, поставщик контактов должен быть котов к тому, чтобы сохранить состояние сеанса при приостановке, так, чтобы он мог восстановить это состояние при повторном запуске с previousExecutionState установленном в terminated. Хотя это не показано в примере, настоящему приложению-поставщику следует сохранять текущее выделение и позицию просмотра списка, вместе с чем угодно другим, касающимся состояния сеанса, и восстанавливать всё это, когда нужно, в обработчике activated.
Что мы только что изучили
- Контракты в Windows 8 предоставляют возможность расширять функциональность системы любому количеству приложений, а так же – расширять функциональность других приложений. Посредством контрактов, установка большего количества приложений, поддерживающих их, создаёт более богатое возможностями общее окружение для пользователей.
- Контракт Общий доступ предоставляет удобные средства, с помощью которых данные из одного приложения могут быть оправлены в другое, избегая множества промежуточных шагов и не уводя пользователя из контекста того же самого приложения. Приложение-источник упаковывает данные, которые оно может предоставить в общий доступ, когда активируется чудо-кнопка Общий доступ. Целевое приложение принимает эти данные, часто копируя их куда-либо, например, в сообщение электронной почты, текстовое сообщение, в сервис социальной сети и так далее.
- Целевое приложение общего доступа предоставляет средства для отложенного рендеринга элементов (таких, как изображения), для операций, выполняющихся длительное время (как, например, таких, когда нужно отправить файлы с данными большого объёма на удаленный сервис), и для обеспечения быстрых ссылок на конкретные цели внутри этого приложения (такие, как люди, которым пользователь часто пишет электронные письма).
- Контракт Поиск обеспечивают интеграцию между приложением и чудо-кнопкой Поиск. Из интерфейса чудо-кнопки пользователь может выполнять поиск по текущему приложению, как и по любым другим, которые поддерживают этот контракт, удобно просматривать результаты из других приложений без необходимости вручную запускать их или переключаться на них. Поисковый контракт так же позволяет приложениям предоставлять предложение вариантов поискового запроса и результатов поиска.
- Сопоставления типов файлов и схем URI это способ, с помощью которого приложения могут запускать другие приложения. Сопоставления приложения объявляются в его манифесте, что позволяет приложению запуститься для обслуживания этих сопоставлений. Сопоставления схемы URI – это отличный способ, с помощью которого приложение может предоставить сервисы рабочих процессов другим приложениям.
- Приложения, которые реализуют передающую сторону контракта средства выбора файлов появляются в качестве вариантов выбора в интерфейсе средства выбора файлов. Это способ, с помощью которого приложения могут представлять источники данных, которыми управляют, так, как будто они являются частью локальной файловой системы, если даже эти данные существуют в базе данных, на удалённом сервисе или в другом подобном расположении. Особенности реализации передачи данных прозрачные для пользователя, посредством контракта средства обновления кэшированных файлов приложение-поставщик так же может обрабатывать синхронизацию локальных и удалённых копий файла.
- Работа контракта для Контактов похожа на работу контакта средства выбора файлов, но с использованием информации о людях. Приложение-приемник может легко активировать пользовательский интерфейс выбора контакта, любое количество приложений-поставщиков могут реализовать другую сторону контракта для представления адресной книги, базы данных или другого источника с помощью своего пользовательского интерфейса.