Отправка локального уведомления на плиткеSend a local tile notification

Основные плитки приложений в Windows 10 определяются в манифесте приложения, а вспомогательные плитки создаются программно и определяются кодом приложения.Primary app tiles in Windows 10 are defined in your app manifest, while secondary tiles are programmatically created and defined by your app code. В этой статье описывается, как с помощью шаблонов адаптивных плиток отправлять локальное уведомление на плитке на основную и вспомогательную плитку.This article describes how to send a local tile notification to a primary tile and a secondary tile using adaptive tile templates. (Локальное уведомление — это уведомление, отправляемое из кода приложения, тогда как уведомление другого типа отправляется принудительно (push-уведомление) или поступает с веб-сервера).(A local notification is one that's sent from app code as opposed to one that's pushed or pulled from a web server.)

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

 

Установка пакета NuGetInstall the NuGet package

Мы рекомендуем устанавливать пакет библиотеки уведомлений NuGet, который упрощает процесс за счет создания полезных данных плитки с объектами вместо необработанных XML-данных.We recommend installing the Notifications library NuGet package, which simplifies things by generating tile payloads with objects instead of raw XML.

Примеры встроенного кода в этой статье предназначены для C# с использованием библиотеки уведомлений.The inline code examples in this article are for C# using the Notifications library. (Описание процесса создания собственного кода XML с его примерами без библиотеки уведомлений см. в конце статьи).(If you'd prefer to create your own XML, you can find code examples without the Notifications library toward the end of the article.)

Добавление объявлений пространств именAdd namespace declarations

Чтобы получить доступ к API для работы с плитками, добавьте пространство имен Windows.UI.Notifications.To access the tile APIs, include the Windows.UI.Notifications namespace. Мы также рекомендуем добавлять пространство имен Microsoft.Toolkit.Uwp.Notifications, чтобы можно было использовать вспомогательные API для работы с плитками (чтобы получить доступ к этим API, необходимо установить пакет NuGet Библиотеки уведомлений).We also recommend including the Microsoft.Toolkit.Uwp.Notifications namespace so that you can take advantage of our tile helper APIs (you must install the Notifications library NuGet package to access these APIs).

using Windows.UI.Notifications;
using Microsoft.Toolkit.Uwp.Notifications; // Notifications library

Создание содержимого уведомленияCreate the notification content

В Windows 10 полезные данные плитки определяются с помощью шаблонов адаптивных плиток, которые позволяют создавать собственные визуальные макеты для уведомлений.In Windows 10, tile payloads are defined using adaptive tile templates, which allow you to create custom visual layouts for your notifications. (Дополнительные сведения об операциях, которые можно выполнять с адаптивными плитками, см. в статье Создание адаптивных плиток).(To learn what's possible with adaptive tiles, see Create adaptive tiles.)

В этом примере кода создается содержимое адаптивной плитки для средних и широких плиток.This code example creates adaptive tile content for medium and wide tiles.

// In a real app, these would be initialized with actual data
string from = "Jennifer Parker";
string subject = "Photos from our trip";
string body = "Check out these awesome photos I took while in New Zealand!";
 
 
// Construct the tile content
TileContent content = new TileContent()
{
    Visual = new TileVisual()
    {
        TileMedium = new TileBinding()
        {
            Content = new TileBindingContentAdaptive()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = from
                    },

                    new AdaptiveText()
                    {
                        Text = subject,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    },

                    new AdaptiveText()
                    {
                        Text = body,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            }
        },

        TileWide = new TileBinding()
        {
            Content = new TileBindingContentAdaptive()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = from,
                        HintStyle = AdaptiveTextStyle.Subtitle
                    },

                    new AdaptiveText()
                    {
                        Text = subject,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    },

                    new AdaptiveText()
                    {
                        Text = body,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            }
        }
    }
};

При отображении на средней плитке содержимое уведомления выглядит следующим образом:The notification content looks like the following when displayed on a medium tile:

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

Создание уведомления на плиткеCreate the notification

После создания содержимого уведомления необходимо создать новое уведомление TileNotification.Once you have your notification content, you'll need to create a new TileNotification. Конструктор TileNotification принимает объект XmlDocument среды выполнения Windows, который можно получить из метода TileContent.GetXml с использованием Библиотеки уведомлений.The TileNotification constructor takes a Windows Runtime XmlDocument object, which you can obtain from the TileContent.GetXml method if you're using the Notifications library.

В этом примере кода создается уведомление для новой плитки.This code example creates a notification for a new tile.

// Create the tile notification
var notification = new TileNotification(content.GetXml());

Задание времени окончания срока действия уведомления (необязательно)Set an expiration time for the notification (optional)

По умолчанию локальные уведомления на плитках и индикаторах событий не истекают, тогда как запланированные, периодические и push-уведомления истекают через три дня.By default, local tile and badge notifications don't expire, while push, periodic, and scheduled notifications expire after three days. Так как содержание плитки не должно сохраняться дольше, чем нужно, рекомендуется установить срок действия на все уведомления на плитках и индикаторах событий, используя время, значимое для вашего приложения.Because tile content shouldn't persist longer than necessary, it's a best practice to set an expiration time that makes sense for your app, especially on local tile and badge notifications.

В этом примере кода создается уведомление, срок действия которого истекает через десять минут, после чего оно удаляется из плитки.This code example creates a notification that expires and will be removed from the tile after ten minutes.

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddMinutes(10);

Отправка уведомленияSend the notification

Несмотря на то, что локальная отправка уведомления плитки является простым процессом, отправка уведомления на основную или вспомогательную плитку выполняется несколько иначе.Although locally sending a tile notification is simple, sending the notification to a primary or secondary tile is a bit different.

Основная плиткаPrimary tile

Чтобы отправить уведомление на основную плитку, используйте TileUpdateManager для создания средства обновления основной плитки и отправьте уведомление, вызвав метод «Update».To send a notification to a primary tile, use the TileUpdateManager to create a tile updater for the primary tile, and send the notification by calling "Update". Независимо от того, отображается основная плитка приложения или нет, она всегда существует, таким образом на нее можно отправлять уведомления, даже если она не закреплена.Regardless of whether it's visible, your app's primary tile always exists, so you can send notifications to it even when it's not pinned. Когда пользователь закрепит основную плитку, тогда и отобразятся отправленные вами уведомления.If the user pins your primary tile later, the notifications that you sent will appear then.

В этом примере кода уведомление отправляется на основную плитку.This code example sends a notification to a primary tile.

// Send the notification to the primary tile
TileUpdateManager.CreateTileUpdaterForApplication().Update(notification);

Вторичная плиткаSecondary tile

Чтобы отправить уведомление на вспомогательную плитку, сначала убедитесь, что вспомогательная плитка существует.To send a notification to a secondary tile, first make sure that the secondary tile exists. Если создать средство обновления плитки для вспомогательной плитки, которой не существует (например, если пользователь открепил вспомогательную плитку), будет выдано исключение.If you try to create a tile updater for a secondary tile that doesn't exist (for example, if the user unpinned the secondary tile), an exception will be thrown. Вы можете использовать SecondaryTile.Exists(tileId), чтобы определить, закреплена ли вспомогательная плитка, а затем создать средство обновления плитки для вспомогательной плитки и отправить уведомление.You can use SecondaryTile.Exists(tileId) to discover if your secondary tile is pinned, and then create a tile updater for the secondary tile and send the notification.

В этом примере кода уведомление отправляется на вспомогательную плитку.This code example sends a notification to a secondary tile.

// If the secondary tile is pinned
if (SecondaryTile.Exists("MySecondaryTile"))
{
    // Get its updater
    var updater = TileUpdateManager.CreateTileUpdaterForSecondaryTile("MySecondaryTile");
 
    // And send the notification
    updater.Update(notification);
}

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

Очистка уведомлений на плитке (необязательно)Clear notifications on the tile (optional)

В большинстве случаев после взаимодействия пользователя с этим содержимым уведомление необходимо очистить.In most cases, you should clear a notification once the user has interacted with that content. Например, когда пользователь запускает ваше приложение, может потребоваться удалить все уведомления с плитки.For example, when the user launches your app, you might want to clear all the notifications from the tile. Если уведомления зависят от времени, рекомендуется задать время окончания срока действия уведомления, а не выполнять непосредственно очистку уведомления.If your notifications are time-bound, we recommend that you set an expiration time on the notification instead of explicitly clearing the notification.

В этом примере кода выполняется очистка уведомления плитки для основной плитки.This code example clears the tile notification for the primary tile. То же самое можно сделать для дополнительных плиток, создав для них средство обновления плитки.You can do the same for secondary tiles by creating a tile updater for the secondary tile.

TileUpdateManager.CreateTileUpdaterForApplication().Clear();

Если для плитки включена очередь уведомлений, в которой имеются элементы, вызов метода Clear приводит к очистке очереди.For a tile with the notification queue enabled and notifications in the queue, calling the Clear method empties the queue. Тем не менее уведомление нельзя очистить с помощью сервера приложений; уведомления может очищать только локальный код приложения.You can't, however, clear a notification via your app's server; only the local app code can clear notifications.

Периодические или push-уведомления могут только добавлять новые уведомления или заменять существующие уведомления.Periodic or push notifications can only add new notifications or replace existing notifications. Локальный вызов метода Clear очистит плитку независимо от типа уведомлений (push-уведомления, периодические или локальные уведомления).A local call to the Clear method will clear the tile whether or not the notifications themselves came via push, periodic, or local. Запланированные уведомления, которые еще не появлялись, не очищаются с помощью этого метода.Scheduled notifications that haven't yet appeared are not cleared by this method.

плитка с уведомлением и плитка после ее очищения

Дальнейшие действияNext steps

Использование очереди уведомленийUsing the notification queue

Теперь, когда вы выполнили первое обновление плитки, вы можете расширить функциональность своей плитки, включив очередь уведомлений.Now that you have done your first tile update, you can expand the functionality of the tile by enabling a notification queue.

Другие методы доставки уведомленийOther notification delivery methods

В этой статье описывается процесс отправки обновления плитки в виде уведомления.This article shows you how to send the tile update as a notification. Чтобы изучить другие методы доставки уведомлений, включая запланированные, периодические и push-уведомления, см. раздел Доставка уведомлений.To explore other methods of notification delivery, including scheduled, periodic, and push, see Delivering notifications.

Метод доставки XmlEncodeXmlEncode delivery method

Если вы не используете Библиотеку уведомлений, этот метод доставки уведомлений является альтернативным решением.If you're not using the Notifications library, this notification delivery method is another alternative.

public string XmlEncode(string text)
{
    StringBuilder builder = new StringBuilder();
    using (var writer = XmlWriter.Create(builder))
    {
        writer.WriteString(text);
    }

    return builder.ToString();
}

Примеры кода без библиотеки уведомленийCode examples without Notifications library

Если вы предпочитаете работать с необработанным кодом XML, а не с пакетом NuGet Библиотеки уведомлений, вместо первых трех примеров кода, приведенных в этой статье, используйте следующие альтернативные примеры кода.If you prefer to work with raw XML instead of the Notifications library NuGet package, use these alternate code examples to first three examples provided in this article. Остальные примеры кода можно использовать с Библиотекой уведомлений или с необработанным кодом XML.The rest of the code examples can be used either with the Notifications library or with raw XML.

Добавление объявлений пространств именAdd namespace declarations

using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

Создание содержимого уведомленияCreate the notification content

// In a real app, these would be initialized with actual data
string from = "Jennifer Parker";
string subject = "Photos from our trip";
string body = "Check out these awesome photos I took while in New Zealand!";
 
 
// TODO - all values need to be XML escaped
 
 
// Construct the tile content as a string
string content = $@"
<tile>
    <visual>
 
        <binding template='TileMedium'>
            <text>{from}</text>
            <text hint-style='captionSubtle'>{subject}</text>
            <text hint-style='captionSubtle'>{body}</text>
        </binding>
 
        <binding template='TileWide'>
            <text hint-style='subtitle'>{from}</text>
            <text hint-style='captionSubtle'>{subject}</text>
            <text hint-style='captionSubtle'>{body}</text>
        </binding>
 
    </visual>
</tile>";

Создание уведомления на плиткеCreate the notification

// Load the string into an XmlDocument
XmlDocument doc = new XmlDocument();
doc.LoadXml(content);
 
// Then create the tile notification
var notification = new TileNotification(doc);