Краткое руководство: использование библиотеки NotificationsExtensions в коде приложения (HTML)

Статья
12/12/2015

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]

Примечание Не используете JavaScript? Подробнее: Краткое руководство: использование библиотеки NotificationsExtensions в коде приложения (XAML).

Библиотека объектной модели NotificationsExtensions позволяет предоставлять XML-содержимое шаблонов плитки, индикатора событий и всплывающего уведомления без использования модели DOM XML. Это более простой, наглядный и прямой способ предоставления содержимого уведомлений. Использование данной библиотеки в Microsoft Visual Studio дает следующие преимущества.

Intellisense перечисляет доступные теги и атрибуты как свойства объекта, что позволяет не обращаться к документации по схеме в поисках информации о структуре и элементах.
Функция фабрики для создания схематичных уведомлений, которые затем заполняются содержимым.
Упрощенный способ включения нескольких размеров плиток в полезные данные уведомления (рекомендуется).
Полезный способ поиска и заполнения атрибутов текста и изображения, имена которых предоставляют дополнительную информацию относительно их предполагаемого использования, размера или положения в шаблоне.

Примечание Библиотека NotificationsExtensions выпущена под лицензией Microsoft Limited Public License (MS-LPL). Вы можете повторно использовать библиотеку в своем приложении Магазина Windows или веб-службе, а также при необходимости настроить ее под приложение.

Необходимые условия

Практические знания в области концепций и терминов плиток и уведомлений. Подробнее: Плитки, индикаторы событий и уведомления.
Умение создавать простые приложения Магазина Windows на JavaScript с использованием API среды выполнения Windows. Подробнее: Создание первого приложения Магазина Windows на JavaScript.
Основные знания XML помогут вам лучше понять, какие возможности дает библиотека NotificationsExtensions.

Инструкции

1. Получение библиотеки NotificationsExtensions

Библиотека NotificationsExtensions включена в несколько скачиваемых примеров плиток, уведомлений и всплывающих уведомлений. Ее можно скопировать оттуда для собственного использования. Для данной процедуры мы воспользуемся основным примером плиток и индикаторов событий.

Примечание NotificationsExtensions — это библиотека C#, но ее можно использовать в проектах JavaScript, C#, C++ и Microsoft Visual Basic.

Скачайте Образец плиток приложения и индикаторов событий из Центра разработки для Windows.
Распакуйте файл App tiles and badges sample.zip в папку по вашему выбору.
Перейдите к папке, в которую вы распаковали пример. Скопируйте папку NotificationsExtensions из примера в собственный каталог проекта на том же уровне, что и SLN-файл вашего проекта.

2. Включение библиотеки в проект

Запустите Visual Studio и откройте свой проект.
В обозревателе проектов правой кнопкой мыши щелкните решение вверху дерева.
Выберите пункты Добавить > Существующий проект.
Перейдите в папку NotificationsExtensions своего проекта и выберите файл NotificationsExtensions.csproj.
В каждом проекте в решении правой кнопкой мыши щелкните пункт Ссылки и выберите команду Добавить ссылку.
В диспетчере ссылок в разделе Решение выберите NotificationsExtensions и нажмите кнопку ОК. Теперь библиотека NotificationsExtensions готова к использованию.

Примечание Если вы не хотите включать весь проект NotificationsExtensions в свое решение, то можете выполнить сборку NotificationsExtensions в качестве автономного проекта и просто включить файл NotificationsExtensions.winmd в свой проект в виде ссылки.

3. Включение библиотеки на сервере приложений

Вы также можете применять NotificationsExtensions в серверном коде приложения, если вы используете ASP.NET для отправки push-уведомлений в службу push-уведомлений Windows (WNS) или реализуете службу ASP.NET для обработки запросов периодического обновления плитки или индикатора событий. Необходимо только добавить символ сборки компиляции WINRT_NOT_PRESENT в свойства проекта NotificationsExtensions.

Перейдите к каталогу, в который вы распаковали пример. Откройте папку примера и скопируйте его папку NotificationsExtensions в новое место по своему выбору.
Выберите файл NotificationsExtensions.csproj для открытия проекта в Visual Studio.
В меню Проект выберите Свойства NotificationsExtensions.
Измените значение параметра Тип вывода на "Библиотека классов", чтобы создать DLL-файл.
В свойствах NotificationsExtensions перейдите на вкладку Сборка.
В категории Общие добавьте "WINRT_NOT_PRESENT" в поле Символы условной компиляции. Если поле уже содержит другие символы, добавьте точку с запятой в качестве разделителя перед "WINRT_NOT_PRESENT".
Нажмите клавишу F7 или выберите пункты Сборка > Собрать решение для сборки проекта.
Скопируйте собранный файл NotificationsExtensions.dll из своей папки (в каталоге \NotificationsExtensions\bin\Debug\) в серверный код вашего приложения.

4. Использование библиотеки в коде

NotificationsExtensions теперь можно использовать как объект в коде. Он содержит три составляющих, которые стоит упомянуть:

BadgeContent
TileContent
ToastContent

Каждый из этих типов содержимого, в свою очередь, содержит члены, которые обозначают элементы и атрибуты для каждого типа.

В следующем примере NotificationsExtensions используется для присвоения значения числовому индикатору событий и последующей передачи его плитке.


var badgeContent = NotificationsExtensions.BadgeContent.BadgeNumericNotificationContent(85);
var badgeNotification = badgeContent.createNotification();

Windows.UI.Notifications.BadgeUpdateManager.createBadgeUpdaterForApplication().update(badgeNotification);

Для сравнения в следующем примере показана та же процедура, но без NotificationsExtensions, с использованием прямых манипуляций с моделью DOM XML.


var notifications = Windows.UI.Notifications;                        
var badgeXml = notifications.BadgeUpdateManager.getTemplateContent(notifications.BadgeTemplateType.badgeNumber);
var badgeAttributes = badgeXml.getElementsByTagName("badge");
badgeAttributes[0].setAttribute("value", "85");
var badgeNotification = new notifications.BadgeNotification(badgeXml);

BadgeUpdateManager.createBadgeUpdaterForApplication().update(badgeNotification);

В следующем примере NotificationsExtensions используется для предоставления текста в уведомлении на плитке. На первом шаге применяется функция TileContentFactory NotificationsExtensions для создания объекта на основе определенного шаблона. Для каждого шаблона есть отдельная функция создания. Просто присоедините слово "create" к имени шаблона, например "createTileWide310x150ImageAndText01".

Затем объект на основе шаблона при помощи Intellisense выводит элементы, доступные в этом шаблоне, в виде свойств с именами, соответствующими их функциям, например textHeading, textBodyWrap, textBody1 или textColumn1Row4. Это позволяет точно определить, какой элемент вы назначаете.

После того, как вы назначили значения свойствам, отправьте уведомление на плитке обычным способом.


var tileContent = NotificationsExtensions.TileContent.TileContentFactory.createTileSquare150x150Text01();

tileContent.textHeading.text = "Hello!";
tileContent.textBody1.text = "One";
tileContent.textBody2.text = "Two";
tileContent.textBody3.text = "Three";

var tileNotification = tileContent.createNotification();

Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

В этом примере NotificationsExtensions используется для назначения уведомлению текста и изображения. Как и текстовые элементы, элементы изображения представлены в виде свойств, названных в соответствии со своей функцией в шаблоне, например imageMain или imageSmallColumn2Row2.


var tileContent = NotificationsExtensions.TileContent.TileContentFactory.createTileWide310x150ImageAndText01();

tileContent.textCaptionWrap.text = "This tile notification uses ms-appx images";

tileContent.image.src = "ms-appx:///images/redWide.png";
tileContent.image.alt = "A red rectangle";

В этом примере NotificationsExtensions используется для определения полного уведомления на плитке. Пример демонстрирует одну из особенностей данной библиотеки — важность порядка, в котором вы добавляете размеры шаблонов в полезные данные.

Мелкий шаблон (square71 x 71 — только для Windows Phone 8.1) можно добавить только к среднему шаблону.
Средний шаблон (square150 x 150) можно добавить только к широкому шаблону.
Широкий шаблон можно добавить только к крупному шаблону (square310 x 310 — только для Windows).

Если попытаться изменить этот порядок, необходимые свойства будут недоступны.


var tileLargeContent = NotificationsExtensions.TileContent.TileContentFactory.createTileSquare310x310Text09();
tileLargeContent.textHeadingWrap.text = "Lorem ipsum dolor sit amet, consectetur";
tileLargeContent.textHeading1.text = "Lorem ipsumo";
tileLargeContent.textHeading2.text = "Lorem ipsumo";
tileLargeContent.textBody1.text = "VivAmus tincidunt convallis urn";
tileLargeContent.textBody2.text = "VivAmus tincidunt convallis urn";

var tileWideContent = NotificationsExtensions.TileContent.TileContentFactory.createTileWide310x150Text04();
tileWideContent.textBodyWrap.text = "Lorem ipsum dolor sit amet, consectetur";

var tileMediumContent = NotificationsExtensions.TileContent.TileContentFactory.createTileSquare150x150Block();
tileMediumContent.textBlock.text = "24";
tileMediumContent.textSubBlock.text = "Aliquam";
        
tileWideContent.square150x150Content = tileMediumContent;
tileLargeContent.wide310x150Content = tileWideContent;

var tileNotification = tileLargeContent.createNotification();

Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

В данном примере NotificationsExtensions используется для предоставления содержимого для всплывающего уведомления, включая текст, изображение, звук, продолжительность и параметры запуска.


var toastContent = NotificationsExtensions.ToastContent.ToastContentFactory.createToastImageAndText01();

toastContent.textBodyWrap.text = "Lorem ipsum dolor sit amet";

toastContent.image.src = "ms-appx:///images/redWide.png";
toastContent.image.alt = "A red rectangle";

toastContent.audio.content = NotificationsExtensions.ToastContent.ToastAudioContent.loopingAlarm;
toastContent.audio.loop = true;

toastContent.duration = NotificationsExtensions.ToastContent.ToastDuration.long;

toastContent.launch = '{"type":"toast","param1":"12345","param2":"67890"}';

var toast = toastContent.createNotification();
Windows.UI.Notifications.ToastNotificationManager.createToastNotifier().show(toast);

Сводка

В этом разделе было продемонстрировано, как использовать NotificationsExtensions, чтобы упростить создание уведомлений индикатора событий, уведомлений на плитке и всплывающих уведомлений. Этот способ заполнения шаблона проще, чем работа непосредственно с моделью DOM XML.