Windows 应用通知：Microsoft.Toolkit.Uwp.Notifications

Windows 通知系统是现代应用程序与用户进行有效沟通的关键组成部分。它允许应用程序在用户不直接使用应用时，也能及时传递重要信息，例如更新、提醒或即时消息。为了简化和增强 Windows 通知的开发过程，Microsoft 提供了 Microsoft.Toolkit.Uwp.Notifications 库。本文将深入探讨该库的使用方法，旨在帮助开发者充分利用其功能，构建更具吸引力和互动性的 Windows 通知。

1. 快速入门：安装 NuGet 包

在开始使用 Microsoft.Toolkit.Uwp.Notifications 之前，首先需要将其添加到项目之中。这可以通过 NuGet 包管理器轻松完成。在 Visual Studio 中，开发者可以打开 NuGet 包管理器控制台，并执行以下命令：

 Install-Package Microsoft.Toolkit.Uwp.Notifications

或者，开发者也可以通过 NuGet 包管理器图形界面搜索并安装 Microsoft.Toolkit.Uwp.Notifications 包。

2. 构建基础通知：纯文本通知

最简单的通知形式是纯文本通知。Microsoft.Toolkit.Uwp.Notifications 提供了流畅的 API 来创建此类通知。以下代码示例展示了如何构建并显示一个包含单行文本的 Toast 通知：

 using Microsoft.Toolkit.Uwp.Notifications;
 
 // ... 在应用程序代码中 ...
 
 private static void SendSimpleTextNotification()
 {
     new ToastContentBuilder()
         .AddText("这是一条简单的文本通知。")
         .Show(); // 显示通知
 }

代码解析：

using Microsoft.Toolkit.Uwp.Notifications;：引入必要的命名空间，以便访问库中的类。
new ToastContentBuilder()：创建 ToastContentBuilder 类的实例，该类负责构建通知的内容。
.AddText("这是一条简单的文本通知。")：使用 AddText 方法添加一行文本内容到通知中。可以多次调用此方法以添加多行文本。
.Show()：调用 Show 方法，将构建好的 Toast 通知发送并显示给用户。

3. 丰富通知内容：添加标题与副标题

为了更好地组织和呈现信息，可以在通知中添加标题和副标题。通过使用 hintStyle 参数，可以将文本设置为标题样式，使其在视觉上更为突出。

 private static void SendTitleSubtitleNotification()
 {
     new ToastContentBuilder()
         .AddText("主标题", hintStyle: AdaptiveTextStyle.Header) // 设置主标题样式
         .AddText("副标题内容，提供更详细的说明。")
         .Show();
 }

代码解析：

hintStyle: AdaptiveTextStyle.Header： AddText 方法的 hintStyle 参数允许开发者指定文本的样式。AdaptiveTextStyle.Header 枚举值指示将该行文本渲染为标题样式。

4. 提升互动性：添加操作按钮

Toast 通知的强大之处在于其互动性。通过添加操作按钮，用户可以直接在通知中执行操作，无需打开应用程序。

 private static void SendNotificationWithButtons()
 {
     new ToastContentBuilder()
         .AddText("您收到了一条新消息。")
         .AddButton(new ToastButton()
             .SetContent("查看")
             .AddArgument("action", "view") // 添加参数，用于识别操作
         )
         .AddButton(new ToastButton()
             .SetContent("忽略")
             .AddArgument("action", "dismiss")
         )
         .Show();
 }

代码解析：

.AddButton(new ToastButton()...)：使用 AddButton 方法添加操作按钮。
.SetContent("查看")：设置按钮上显示的文本内容。
.AddArgument("action", "view")：为按钮添加参数。这些参数将在用户点击按钮时传递回应用程序，用于区分不同的操作。

5. 处理按钮点击事件：应用程序激活

当用户点击通知上的操作按钮时，应用程序将被激活。开发者需要在应用程序的 App.xaml.cs (或 App.xaml.vb) 文件中的 OnActivated 方法中处理 ToastNotification 类型的激活事件，并根据按钮参数执行相应的操作。

 // App.xaml.cs
 
 protected override void OnActivated(IActivatedEventArgs args)
 {
     base.OnActivated(args);
 
     if (args.Kind == ActivationKind.ToastNotification)
     {
         var toastArgs = args as ToastNotificationActivatedEventArgs;
         if (toastArgs != null)
         {
             var arguments = toastArgs.Argument; // 获取通知参数
 
             if (arguments.Contains("action=view"))
             {
                 // 用户点击了 "查看" 按钮，执行查看消息的操作
                 System.Diagnostics.Debug.WriteLine("用户点击了 查看 按钮");
                 // 在此处添加导航到消息详情页面的代码
             }
             else if (arguments.Contains("action=dismiss"))
             {
                 // 用户点击了 "忽略" 按钮，执行忽略操作
                 System.Diagnostics.Debug.WriteLine("用户点击了 忽略 按钮");
                 // 在此处添加忽略操作的代码
             }
         }
     }
 
     // 确保窗口被激活
     if (Window.Current.Content == null)
     {
         Frame rootFrame = new Frame();
         rootFrame.NavigationFailed += OnNavigationFailed;
         Window.Current.Content = rootFrame;
         rootFrame.Navigate(typeof(MainPage)); // 替换为应用程序的主页
     }
     Window.Current.Activate();
 }

代码解析：

OnActivated(IActivatedEventArgs args)：应用程序激活事件处理方法。
args.Kind == ActivationKind.ToastNotification：检查激活类型是否为 Toast 通知。
args as ToastNotificationActivatedEventArgs：将 IActivatedEventArgs 转换为 ToastNotificationActivatedEventArgs 类型，以便访问通知相关的参数。
toastArgs.Argument：获取通知的参数字符串。
arguments.Contains("action=view") 和 arguments.Contains("action=dismiss")：通过检查参数字符串，判断用户点击了哪个按钮。
在相应的条件分支中，开发者可以根据不同的按钮操作执行不同的应用程序逻辑。
Window.Current.Activate()：确保应用程序窗口被激活并显示在前台。

6. 收集用户反馈：添加输入框

除了操作按钮，Toast 通知还可以包含输入框，允许用户直接在通知中输入文本并提交反馈或其他信息。

 private static void SendNotificationWithInput()
 {
     new ToastContentBuilder()
         .AddText("请提供您的反馈意见。")
         .AddInputTextBox("feedbackTextBox", "在此输入...") // 添加文本输入框
         .AddButton(new ToastButton()
             .SetContent("提交")
             .AddArgument("action", "submitFeedback")
         )
         .Show();
 }

代码解析：

.AddInputTextBox("feedbackTextBox", "在此输入...")：添加一个文本输入框。
- "feedbackTextBox"：输入框的 ID，用于在应用程序激活时检索用户输入的内容。
- "在此输入..."：输入框的占位符文本。

7. 获取用户输入：处理应用程序激活

在 OnActivated 方法中，需要获取用户在输入框中输入的内容。

 // App.xaml.cs (OnActivated 方法中)
 
 if (toastArgs != null)
 {
     var arguments = toastArgs.Argument;
     var userInput = toastArgs.UserInput; // 获取用户输入
 
     if (arguments.Contains("action=submitFeedback"))
     {
         string feedback = userInput["feedbackTextBox"] as string; // 获取 "feedbackTextBox" 输入框的值
         if (!string.IsNullOrEmpty(feedback))
         {
             // 处理用户反馈，例如发送到服务器或保存到本地
             System.Diagnostics.Debug.WriteLine($"用户反馈: {feedback}");
             // 在此处添加处理用户反馈的代码
         }
     }
 }

代码解析：

toastArgs.UserInput：获取用户输入值的字典。字典的键是输入框的 ID，值是用户输入的字符串。
userInput["feedbackTextBox"] as string：通过输入框的 ID "feedbackTextBox" 获取用户输入的字符串值。

8. 视觉增强：添加图片

为了使通知更具吸引力，可以添加图片。Microsoft.Toolkit.Uwp.Notifications 支持两种类型的图片添加：

应用程序徽标覆盖 (App Logo Override)：替换通知左侧默认的应用程序徽标。
内联图片 (Inline Image)：在通知内容区域添加图片。

添加应用程序徽标覆盖：

 private static void SendNotificationWithAppLogo()
 {
     new ToastContentBuilder()
         .SetAppLogoOverride(new Uri("ms-appx:///Assets/StoreLogo.png"), ToastGenericAppLogoCrop.Circle) // 设置应用程序徽标覆盖
         .AddText("自定义应用程序徽标的通知。")
         .Show();
 }

添加内联图片：

private static void SendNotificationWithInlineImage()
{
    new ToastContentBuilder()
        .AddInlineImage(new Uri("ms-appx:///Assets/InlineImage.png")) // 添加内联图片
        .AddText("包含内联图片的通知。")
        .Show();
}

图片资源路径说明：

ms-appx:///：用于访问应用程序包内部的资源，例如 Assets 文件夹中的图片。
ms-appdata:///local/：用于访问应用程序的本地应用数据存储。
ms-appdata:///roaming/：用于访问应用程序的漫游应用数据存储。
http:// 或 https://：用于访问 Web 上的图片资源 (需要应用程序具备网络访问权限)。

9. 听觉提示：添加音频

为了进一步吸引用户的注意，可以为 Toast 通知添加音频提示。

private static void SendNotificationWithAudio()
{
    new ToastContentBuilder()
        .SetAudio(ToastAudio.Default) // 使用默认音频
        .AddText("包含音频提示的通知。")
        .Show();
}

代码解析：

.SetAudio(ToastAudio.Default)：设置通知音频为默认音频。
ToastAudio 类提供了预定义的音频选项，例如 ToastAudio.Default (默认声音), ToastAudio.Mail (邮件提示音), ToastAudio.Reminder (提醒提示音) 等。开发者也可以使用自定义音频文件，但需要将其包含在应用程序包中，并使用 ms-appx:/// 协议指定音频文件路径。

10. 高级功能与选项

Microsoft.Toolkit.Uwp.Notifications 还提供了诸多高级功能和选项，以满足更复杂的需求：

Scenario (场景)：通过 SetScenario 方法设置通知的场景类型，例如 Default, Alarm, Reminder, IncomingCall。不同的场景类型可能会影响通知的行为和优先级。
Expiration Time (过期时间)：使用 SetExpirationTime 方法设置通知的过期时间，超过该时间后通知将自动从通知中心移除。
Tag 和 Group (标签和分组)：利用 Tag 和 Group 属性对通知进行管理。相同的 Tag 可以用于替换之前的通知，而相同的 Group 可以将多个通知分组显示。
Custom Payload (自定义 Payload)：对于需要更精细控制的场景，开发者可以直接构建自定义 XML payload，并使用 ToastContent 类来显示通知。

示例：设置 Scenario 和 Expiration Time

private static void SendAdvancedNotification()
{
    new ToastContentBuilder()
        .SetScenario(ToastScenario.Reminder) // 设置场景为提醒
        .SetExpirationTime(DateTime.Now.AddMinutes(10)) // 设置 10 分钟后过期
        .AddText("这是一个提醒通知，将在 10 分钟后过期。")
        .Show();
}

最佳实践与注意事项

确保通知的相关性与价值：发送的通知应与用户相关，并提供实际价值。避免发送不必要的或过于频繁的通知，以免造成用户反感。
适度使用通知：过度使用通知可能会导致用户关闭应用程序的通知权限。应谨慎控制通知的频率和数量。
保持内容清晰简洁：通知内容应简洁明了，突出关键信息，方便用户快速理解。
精心设计操作按钮：操作按钮的文本应明确指示用户可以执行的操作，并与用户的预期相符。
进行充分的测试：在不同版本的 Windows 系统和设备上测试通知的显示效果和功能，确保其兼容性和稳定性。
考虑后台任务：如果需要在用户点击通知按钮后执行耗时操作，可以考虑使用后台任务 (Background Tasks) 来避免阻塞主线程。

总结

Microsoft.Toolkit.Uwp.Notifications 库极大地简化了 Windows Toast 通知的开发流程，并提供了丰富的功能，使得开发者能够创建更具吸引力、互动性和实用性的通知。通过合理运用该库提供的 API 和功能，开发者可以显著提升 Windows 应用程序的用户体验，并实现更有效的用户沟通。建议开发者深入研究该库的文档和示例，以便充分挖掘其潜力，构建更优秀的 Windows 应用程序。

#C#

Windows 应用通知：Microsoft.Toolkit.Uwp.Notifications

http://localhost:8090/archives/microsoft_toolkit_uwp_notifications

作者

Administrator

发布于

2025年07月07日

许可协议

模型特性和操作上一篇

机器学习线代入门下一篇