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

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

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

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

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

См. эту функцию в действии в нашей серии Функции приложений от А до Я: Пользовательский интерфейс Магазина Windows от А до Я

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

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

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

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

Инструкции

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

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

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

var notifications = Windows.UI.Notifications;

2. Выбор шаблона плитки и получение его XML-содержимого

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

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

var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

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

Примечание  При вызове метода getTemplateContent в Windows 8 он возвращает шаблон версии 1. Когда вызов этого метода происходит в системе Windows 8.1, он возвращает шаблон версии 2 или шаблон версии 3 только для Windows Phone. Если совместимость с Windows 8 объявлена в манифесте приложения, этот метод возвращает шаблон версии 1 независимо от версии Windows. В этом разделе мы будем использовать шаблон версии 2.

<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</tile>

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

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

var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

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

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

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

var tileImageAttributes = tileXml.getElementsByTagName("image");

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В этом примере определяется текстовое уведомление среднего формата при помощи той же строки, которая использовалась в широком уведомлении.

       
var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

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

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

После выполнения этих шагов мы получим два элемента binding в одном элементе visual в полезных данных XML:

<tile>
    <visual visual="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src="ms-appx:///images/redWide.png"/>
            <text id="1">Hello World! My very own tile notification</text>
        </binding>

        <binding template="TileSquare150x150Text04" fallback="TileSquareText04">
            <text id="1">Hello World! My very own tile notification</text>
        </binding>
    </visual>
</tile>

6. Создание уведомления на основе указанного XML-содержимого

var tileNotification = new notifications.TileNotification(tileXml);

7. Задание времени окончания срока действия уведомления

По умолчанию локальные уведомления на плитках и индикаторах событий не истекают, а запланированные, периодические и push-уведомления истекают через три дня. Рекомендуется устанавливать разумное время окончания срока действия, особенно для всех локальных уведомлений на плитках и индикаторах событий вашего приложения. Содержимое плитки следует удалять сразу же после того, как оно станет неактуальным. В нашем случае уведомление теряет актуальность и удаляется из плитки через десять минут.

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

8. Отправка уведомления в плитку приложения

notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

9. Дополнительный этап: очистка уведомления

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

notifications.TileUpdateManager.createTileUpdaterForApplication().clear();

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

Обратите внимание, что очистить уведомление из облака не удастся. Локальный вызов метода clear очистит плитку вне зависимости от источника уведомлений, но периодические или push-уведомления могут только обновить содержимое плитки.

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

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

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

var notifications = Windows.UI.Notifications;

var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "ms-appx:///assets/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

var tileNotification = new notifications.TileNotification(tileXml);

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

Теперь, когда вы выполнили первое обновление плитки, вы можете расширить функциональность своей плитки, включив очередь уведомлений.

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

Связанные разделы

Примеры плиток приложений и индикаторов событий

Размеры изображений для плиток и всплывающих уведомлений

Обзор плиток и уведомлений на плитках

Руководство и контрольный список для плиток

Создание расписания уведомления на плитке

Краткое руководство: настройка периодических уведомлений

Краткое руководство: создание плитки по умолчанию с помощью редактора манифестов Visual Studio

Каталог шаблонов плиток

Схема XML плитки

Windows.UI.Notifications