Отправка локального всплывающего уведомления Send a local toast notification
Всплывающее уведомление — это сообщение, которое приложение может создавать и доставлять пользователю, когда он или она в настоящее время не находится в вашем приложении. A toast notification is a message that an app can construct and deliver to the user while they are not currently inside your app. В этом руководстве описаны действия для создания, доставки и отображения всплывающего уведомления с новыми адаптивными шаблонами и интерактивными действиями Windows 10. This Quickstart walks you through the steps to create, deliver, and display a Windows 10 toast notification with the new adaptive templates and interactive actions. Описанные действия демонстрируются на примере локальных уведомлений, которые реализуются проще всего. These actions are demonstrated through a local notification, which is the simplest notification to implement.
Приложения Win32 (включая Упакованные приложения MSIX , приложения, использующие разреженные пакеты для получения удостоверений пакетов и классические приложения Win32 без пакетов) имеют разные шаги для отправки уведомлений и обработки активации. Win32 applications (including packaged MSIX apps, apps that use sparse packages to obtain package identity, and classic non-packaged Win32 apps) have different steps for sending notifications and handling activation. Дополнительные сведения о реализации всплывающих уведомлений см. в документации по приложениям Win32 . Please see the Win32 apps documentation to learn how to implement toasts.
Шаг 1. Установка пакета NuGet Step 1: Install NuGet package
Установите пакет NuGet Microsoft. Toolkit. UWP. Notifications. Install the Microsoft.Toolkit.Uwp.Notifications NuGet package. Этот пакет будет использоваться в нашем примере кода. Our code sample will use this package. В конце статьи мы предоставим «простые» фрагменты кода, которые не используют пакеты NuGet. At the end of the article we’ll provide the «plain» code snippets that don’t use any NuGet packages. Этот пакет позволяет создавать всплывающие уведомления без использования XML. This package allows you to create toast notifications without using XML.
Шаг 2. Добавление объявлений пространств имен Step 2: Add namespace declarations
Windows.UI.Notifications включает API-интерфейсы всплывающих уведомлений. Windows.UI.Notifications includes the toast APIs.
Шаг 3. отправка всплывающего уведомления Step 3: Send a toast
В Windows 10 содержимое всплывающего уведомления описано с помощью адаптивного языка, который обеспечивает большую гибкость вида уведомления. In Windows 10, your toast notification content is described using an adaptive language that allows great flexibility with how your notification looks. Дополнительные сведения см. в документации по содержимому всплывающего уведомления. See the toast content documentation for more information.
Начнем с простого текстового уведомления. We’ll start with a simple text-based notification. Создайте содержимое уведомления (с помощью библиотеки уведомлений) и отобразите уведомление. Construct the notification content (using the Notifications library), and show the notification!
Шаг 4. Обработка активации Step 4: Handling activation
Когда пользователь щелкает уведомление (или кнопку на уведомлении с активацией переднего плана) , будет вызвана app.XAML.CS приложения. When the user clicks your notification (or a button on the notification with foreground activation), your app’s App.xaml.cs OnActivated will be invoked.
App.xaml.cs App.xaml.cs
Вам необходимо инициализировать кадр и активировать окно вашего так же, как ваш код OnLaunched. You must initialize your frame and activate your window just like your OnLaunched code. OnLaunched не вызывается, если пользователь нажимает на всплывающего уведомления, даже если ваше приложение было закрыто и запуск в первый раз. OnLaunched is NOT called if the user clicks on your toast, even if your app was closed and is launching for the first time. Часто рекомендуется комбинировать OnLaunched и OnActivated в методе OnLaunchedOrActivated , так как такая же инициализация должна произойти в обоих. We often recommend combining OnLaunched and OnActivated into your own OnLaunchedOrActivated method since the same initialization needs to occur in both.
Глубина активации Activation in depth
Первым шагом в создании уведомлений является добавление в уведомление некоторых запускаемых аргументов, чтобы ваше приложение знало, что следует запускать, когда пользователь щелкает уведомление (в данном случае мы видим некоторые сведения, которые позже сообщают нам о том, что нужно открыть беседу). The first step in making your notifications actionable is to add some launch args to your notification, so that your app can know what to launch when the user clicks the notification (in this case, we’re including some information that later tells us we should open a conversation, and we know which specific conversation to open).
Мы рекомендуем установить пакет NuGet Querystring.NET , чтобы упростить создание и анализ строк запроса для аргументов уведомления, как показано ниже. We recommend installing the QueryString.NET NuGet package to help construct and parse query strings for your notification arguments, as seen below.
Ниже приведен более сложный пример обработки активации. Here’s a more complex example of handling activation.
App.xaml.cs App.xaml.cs
Добавление изображений Adding images
К уведомлениям можно добавлять большое количество содержимого. You can add rich content to notifications. Мы добавим образ встроенного изображения и профиль (переопределение эмблемы приложения). We’ll add an inline image and a profile (app logo override) image.
В уведомлении можно использовать изображения из пакета приложения, локального хранилища приложения или из Интернета. Images can be used from the app’s package, the app’s local storage, or from the web. Начиная с обновления Fall Creators Update размер веб-изображений может быть до 3 МБ для обычных подключений и до 1 МБ для лимитных подключений. As of the Fall Creators Update, web images can be up to 3 MB on normal connections and 1 MB on metered connections. На устройствах без Fall Creators Update размер веб-изображений не должен превышать 200 КБ. On devices not yet running the Fall Creators Update, web images must be no larger than 200 KB.
Образы HTTP поддерживаются только в приложениях UWP/MSIX/sparse, имеющих возможности Интернета в манифесте. Http images are only supported in UWP/MSIX/sparse apps that have the internet capability in their manifest. Приложения Win32 без MSIX и разреженные не поддерживают образы HTTP. необходимо загрузить образ в данные локального приложения и ссылаться на него локально. Win32 non-MSIX/sparse apps do not support http images; you must download the image to your local app data and reference it locally.
Добавление кнопок и входных данных Adding buttons and inputs
Вы можете добавить кнопки и входные данные, чтобы сделать уведомления интерактивными. You can add buttons and inputs to make your notifications interactive. Кнопки могут запускать приложение переднего плана, протокол или фоновую задачу. Buttons can launch your foreground app, a protocol, or your background task. Мы добавим текстовое поле ответа, кнопку «Like» и кнопку «вид», открывающую изображение. We’ll add a reply text box, a «Like» button, and a «View» button that opens the image.
Активация кнопок переднего плана обрабатывается таким же образом, как и основной текст всплывающего уведомления (будет вызвана App.xaml.csная активация). The activation of foreground buttons are handled in the same way as the main toast body (your App.xaml.cs OnActivated will be called).
Обработка активации фона Handling background activation
При указании активации фона всплывающего уведомления (или кнопка внутри всплывающего уведомления), фоновая задача будет выполнен вместо активация приложения переднего плана. When you specify background activation on your toast (or on a button inside the toast), your background task will be executed instead of activating your foreground app.
Подробнее об использовании фоновых задач см. в разделе Поддержка приложения с помощью фоновых задач. For more information on background tasks, please see Support your app with background tasks.
Если вы используете сборки 14393 или более поздней версии, можно использовать в процесс фоновой задачи, которые значительно упрощают вещи. If you are targeting build 14393 or higher, you can use in-process background tasks, which greatly simplify things. Обратите внимание, что в процессе фоновые задачи не сможет запуститься в более старых версиях Windows. Note that in-process background tasks will fail to run on older versions of Windows. Мы будем использовать фоновую задачу в процессе в этом примере кода. We’ll use an in-process background task in this code sample.
Затем в App.xaml.cs Переопределите метод Онбаккграундактиватед. Then in your App.xaml.cs, override the OnBackgroundActivated method. Затем можно получить предварительно определенные аргументы и ввод пользователя, аналогично активации на переднем плане. You can then retrieve the pre-defined arguments and user input, similar to the foreground activation.
App.xaml.cs App.xaml.cs
Задание времени окончания срока действия Set an expiration time
В Windows 10 все всплывающие уведомления поступают в центр уведомлений после их закрытия или игнорируется пользователем, поэтому пользователь может просмотреть в уведомления, когда всплывающее окно исчезнет. In Windows 10, all toast notifications go in Action Center after they are dismissed or ignored by the user, so users can look at your notification after the popup is gone.
Тем не менее, если сообщение в уведомлении релевантно только для определенного периода времени, необходимо задать время окончания срока действия для всплывающего уведомления, пользователи не смогут увидеть устаревшие сведения из вашего приложения. However, if the message in your notification is only relevant for a period of time, you should set an expiration time on the toast notification so the users do not see stale information from your app. Например, если повышение действует только 12 часов, задайте истечение срока действия, равный 12 часам. For example, if a promotion is only valid for 12 hours, set the expiration time to 12 hours. В следующем коде мы задаем время окончания срока действия, 2 дня. In the code below, we set the expiration time to be 2 days.
По умолчанию и максимальное время окончания срока действия для локального всплывающего уведомления — 3 дня. The default and maximum expiration time for local toast notifications is 3 days.
Предоставить первичный ключ для всплывающего уведомления Provide a primary key for your toast
Если вы хотите удалить или заменить уведомление, которое вы отправляете программным способом, необходимо использовать свойство Tag (и при необходимости свойство Group) для предоставления первичного ключа для уведомления. If you want to programmatically remove or replace the notification you send, you need to use the Tag property (and optionally the Group property) to provide a primary key for your notification. Затем можно использовать этот ключ в будущем для удаления или замены уведомления. Then, you can use this primary key in the future to remove or replace the notification.
Чтобы просмотреть дополнительные сведения о замене или удалении уже доставленного всплывающего уведомления, см. раздел краткое руководство: управление всплывающими уведомлениями в центре уведомлений (XAML). To see more details on replacing/removing already delivered toast notifications, please see Quickstart: Managing toast notifications in action center (XAML).
Tag и Group объединены в качестве составного первичного ключа. Tag and Group combined act as a composite primary key. Группа — это более общий идентификатор, которой можно назначить группам, например «wallPosts», «сообщения», «friendRequests», и т. д. Выберите тег уникальной идентификации уведомления из группы. Group is the more generic identifier, where you can assign groups like «wallPosts», «messages», «friendRequests», etc. And then Tag should uniquely identify the notification itself from within the group. С помощью универсальной группы вы можете удалить все уведомления из группы с помощью RemoveGroup API . By using a generic group, you can then remove all notifications from that group by using the RemoveGroup API.
Очистка уведомлений Clear your notifications
Приложения UWP несут ответственность за удаление и очистку уведомлений. UWP apps are responsible for removing and clearing their own notifications. При запуске приложения, мы не очистить автоматически уведомления. When your app is launched, we do NOT automatically clear your notifications.
Windows автоматически удалит уведомление, если пользователь явно нажмет уведомление. Windows will only automatically remove a notification if the user explicitly clicks the notification.
Вот пример того, как приложение для обмена сообщениями должно делать. Here’s an example of what a messaging app should do…
- Пользователь получает несколько всплывающих уведомлений о новых сообщениях беседы User receives multiple toasts about new messages in a conversation
- Пользователь выбирает одно из этих всплывающих уведомлений, чтобы открыть диалог User taps one of those toasts to open the conversation
- Приложение открывает беседу, а затем удаляет все всплывающие уведомления для этой беседы (с помощью RemoveGroup в группе приложения для этой беседы) The app opens the conversation and then clears all toasts for that conversation (by using RemoveGroup on the app-supplied group for that conversation)
- Центр уведомлений пользователя теперь правильно отражает состояние уведомления, так как слева в центре уведомлений нет устаревших уведомлений для этой беседы. User’s Action Center now properly reflects the notification state, since there are no stale notifications for that conversation left in Action Center.
Подробные сведения о том, как очистить все уведомления или удалить определенные уведомления, см. в разделе краткое руководство: управление всплывающими уведомлениями в центре уведомлений (XAML). To learn about clearing all notifications or removing specific notifications, see Quickstart: Managing toast notifications in action center (XAML).
Фрагменты кода с обычным кодом Plain code snippets
Если вы не используете библиотеку уведомлений в NuGet, вы можете вручную создать XML-код, как показано ниже, для создания тоастнотификатион. If you’re not using the Notifications library from NuGet, you can manually construct your XML as seen below to create a ToastNotification.