Краткое руководство: отправка всплывающего уведомления (HTML)

Статья
12/12/2015

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

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

Всплывающее уведомление — это всплывающий элемент пользовательского интерфейса, который появляется на экране и обеспечивает взаимодействие приложения с пользователем, когда пользователь совершает какие-либо действия в другом приложении, на начальном экране или, в случае Windows, на рабочем столе. Это краткое руководство описывает этапы определения и отображения содержимого всплывающего уведомления. Описанные действия демонстрируются на примере локальных уведомлений, которые реализуются проще всего. Мы рассмотрим следующие этапы:

Выбор шаблона для уведомления
Получение пустого содержимого шаблона в формате XML
Добавление текста в уведомление
Добавление изображения в уведомление
Настройка длительности уведомления
Указание звукового сопровождения для уведомления
Предоставление контекстных сведений, используемых при активации приложения уведомлением
Отправка всплывающего уведомления как локального уведомления

Примечание В этом кратком руководстве мы работаем с содержимым уведомления непосредственно через модель DOM XML. Кроме того, это можно делать и через библиотеку NotificationsExtensions, в которой XML-содержимое представлено в форме свойств объекта, включая свойства Intellisense. Подробнее: Краткое руководство: использование библиотеки NotificationsExtensions в коде. Чтобы увидеть код в этом кратком руководстве с помощью NotificationsExtensions, см. пример Toast notifications.

Примечание При проверке функциональности кода всплывающих уведомлений с помощью Microsoft Visual Studio необходимо использовать параметр отладки "Локальный компьютер" или "Удаленный компьютер" на компьютере с ОС Windows x86, x64 или средой выполнения Windows. Использовать функцию отладки имитатора Visual Studio невозможно — код будет компилироваться и выполняться в имитаторе, но всплывающее уведомление не отобразится.

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

Для понимания этого раздела вам понадобится:

Хорошее знание концепций и терминов всплывающих уведомлений. Подробнее об этом см. в Обзор всплывающих уведомлений.
Чтобы отправлять или получать всплывающие уведомления, в манифесте вашего приложения параметру Всплывающие уведомления нужно присвоить значение"true". В редакторе манифестов Visual Studio необходимо выбрать значение "Да". См. также: Согласие на всплывающие уведомления.
Хорошее понимание XML и работы с XML через API объектной модели документа (DOM).
Хорошее понимание схемы XML всплывающих уведомлений. Подробнее об этом см. в Схема всплывающих уведомлений.
Умение создавать простые приложения Магазина Windows на JavaScript с помощью API среды выполнения Windows. Дополнительные сведения см. в разделе Создание первого приложения Магазина Windows на JavaScript.

Инструкции

1. Дополнительно: объявление переменной пространства имен

На этом этапе создается короткое имя, которое будет использоваться вместо полного имени пространства имен. Это эквивалент оператора "using" в C# или оператора "Imports" в Visual Basic. Оно позволяет упростить код.

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


var notifications = Windows.UI.Notifications;

2. Выбор шаблона всплывающего уведомления и получение его XML-содержимого

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

Примечание В Windows Phone 8.1 поддерживается только вариация шаблона toastText02. Она принимает две текстовые строки, при этом первая преобразуется в полужирный текст, но обе располагаются на одной строке, поэтому следует использовать только одну короткую строку или две очень короткие строки, чтобы избежать сцепления.

В этом примере для работы с Windows используется шаблон toastImageAndText01, для которого требуются одно изображение и одна строка текста. Пример:

ToastImageAndText01


var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

Метод getTemplateContent возвращает объект XmlDocument. Приведенный выше код извлекает следующую основу XML, для которой вы будете предоставлять сведения на следующих этапах с помощью стандартных функций модели DOM:


<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</toast>

3. Добавление текстового содержимого в уведомление

Этот пример сначала извлекает все элементы в шаблоне с именем тега "text". Шаблон toastImageAndText01 содержит только одну текстовую строку, которую назначает код. Эта строка может заключать не более трех строк, так что следует установить нужную длину строки, чтобы не допустить усечения.

   
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].appendChild(toastXml.createTextNode("Hello World!"));

4. Добавление изображения в уведомление

Сначала этот код извлекает все элементы в шаблоне с именем тега "image". Шаблон всплывающего уведомления, такой как toastImageAndText01, содержит максимум одно изображение. Обратите внимание, что не все шаблоны всплывающих уведомлений содержат изображения: некоторые из них включают только текст.


var toastImageElements = toastXml.getElementsByTagName("image");

В уведомлении можно использовать изображения из пакета приложения, локального хранилища приложения или из Интернета. Этот этап рассматривается для всех источников изображений. Размер изображений не должен превышать 200 КБ и 1024 x 1024 пикселей. См. также: Размеры изображений для плиток и всплывающих уведомлений.

В следующем коде используется локальное изображение из пакета приложения. Изображения такого типа включены в ваш файл решения Visual Studio и входят в состав вашего приложения. Для доступа к таким изображениям используется префикс ms-appx:///. Рекомендуется также добавить замещающий текст для поддержки специальных возможностей, например программ чтения с экрана.

Важно Используемое здесь изображение "redWide.png" — только пример, оно не включено в проект Microsoft Visual Studio. Необходимо заменить "redWide.png" именем фактического изображения, которое вы добавили в проект, перед отправкой этого всплывающего уведомления.


toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

В следующем коде используется локальное изображение из локального хранилища приложения. Изображения такого типа сохраняются вашим приложением в локальном хранилище. Его расположение возвращается свойством Windows.Storage.ApplicationData.current.localFolder. Для доступа к таким изображениям используется префикс ms-appdata:///local/. Здесь мы тоже добавим замещающий текст для поддержки специальных возможностей, например программ чтения с экрана.


toastImageElements[0].setAttribute("src", "ms-appdata:///local/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

В следующем примере используется изображение, размещенное в Интернете. Для доступа к таким изображениям используется протокол http://, позволяющий определить путь к изображению. Также можно использовать протокол https://.


toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

Чтобы указать путь к корневому каталогу, например https://www.microsoft.com/, можно использовать атрибут baseUri в сочетании с любым относительным URI, указанным в атрибуте src изображения. Этот атрибут можно задать в элементе visual (чтобы применить ко всему уведомлению) или в элементе binding (чтобы применить к данной привязке). Если установить baseUri в обоих местах, значение в binding будет иметь приоритет над значением в visual.

Если для baseUri было задано значение "https://www.microsoft.com/", то строку в коде примера

toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");

можно сократить до следующего вида:

toastImageElements[0].setAttribute("src", "redWide.png");

5. Дополнительно: указание продолжительности всплывающего уведомления

Дополнительно можно задать продолжительность отображения всплывающего уведомления. Имеется два значения: "short" (по умолчанию) и "long". Используйте "long", только если ваше уведомление является частью такого сценария, как входящий звонок или напоминание о встрече. Подробнее см. в разделе Обзор всплывающих уведомлений.

Примечание В Windows Phone 8.1 не поддерживаются различные значения продолжительности. Все всплывающие уведомления имеют одинаковую длительность. Если во всплывающее уведомление на телефоне включается этот атрибут, он пропускается.

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


var toastNode = toastXml.selectSingleNode("/toast");
toastNode.setAttribute("duration", "long");

6. Дополнительно: указание звукового сопровождения всплывающего уведомления

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

По умолчанию Windows проигрывает короткий звук при отображении всплывающего уведомления. По желанию можно указать другой звук из набора предоставляемых системой звуков или отсутствие звука. На Windows Phone 8.1 можно установить настраиваемый звук. Подробнее см. в разделе Каталог параметров звука для всплывающих уведомлений.

Шаблон, полученный с помощью метода getTemplateContent, не содержит элемента audio, поэтому вы должны определить этот элемент и добавить его в свои полезные данные XML. Звуковой файл указывается с помощью префикса "ms-winsoundevent:", а на устройстве Windows Phone 8.1 путь, который использует префикс "ms-appx:///" или "ms-appdata:///". В этом примере создается элемент audio и выбирается элемент toast, который будет его родительским элементом.


var toastNode = toastXml.selectSingleNode("/toast");                        
var audio = toastXml.createElement("audio");

В этом примере указывается звук, отличный от звука по умолчанию.

audio.setAttribute("src", "ms-winsoundevent:Notification.IM");

В этом примере указывается отсутствие звука.

audio.setAttribute("silent", "true");

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

Примечание Так как Windows Phone 8.1 не поддерживает длительные всплывающие уведомления, повторяющийся звук тоже не поддерживается.


toastNode.setAttribute("duration", "long");

var audio = toastXml.createElement("audio");
audio.setAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm");
audio.setAttribute("loop", "true");

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

toastNode.appendChild(audio);

7. Укажите параметры запуска приложения

Щелкая всплывающее уведомление, пользователь ожидает, что приложение будет запущено в том виде, который предполагает содержимое уведомления. Чтобы это реализовать, используйте атрибут launch для элемента всплывающего уведомления, добавляющий строку, которая передается от всплывающего уведомления в приложение при запуске через уведомление. Эта строка не имеет специальной формы и зависит от приложения. Каждый раз при активации ваше приложение должно проверять данную строку в качестве аргумента и соответствующим образом корректировать свою работу или представление.


toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');

Примечание В Windows Phone Silverlight 8.1 значение строки запуска связано с URI страницы запуска по умолчанию. Например, если указать строку запуска "?conversation=71", это приведет к созданию URI /MainPage.xaml?conversation=71. Поэтому строка запуска должна всегда быть допустимой строкой запроса, иначе выводится исключение.

8. Создайте всплывающее уведомление на основе выбранного вами содержимого XML

var toast = new notifications.ToastNotification(toastXml);

9. Отправьте всплывающее уведомление

 
 var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
 toastNotifier.show(toast);

Примечание В Windows Phone Silverlight 8.1 всплывающее уведомление не отображается, если текущее фоновое приложение является вызывающим абонентом метода ToastNotifier.Show. В этом случае всплывающее уведомление должно главным образом использоваться фоновым агентом.

Примечание.: Цвет фона всплывающего уведомления будет таким же, какой вы объявили в манифесте для плитки приложения. Подробнее об этом см. Краткое руководство: создание плитки по умолчанию с помощью редактора манифестов Visual Studio.

Краткая сводка и дальнейшие действия

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

В этом кратком руководстве показано, как отправить всплывающее уведомление в качестве локального уведомления (самый простой способ реализации уведомлений), что позволяет быстро увидеть результаты. Далее следует изучить другие методы доставки всплывающих уведомлений: запланированные и push-уведомления. Подробнее об этом см. в статье Доставка уведомлений.