应用通知内容

项目
08/09/2024

应用通知是具有文本、图像和按钮/输入的灵活通知。本文介绍可在应用通知中使用的 UI 元素，并提供用于生成应用通知的 XML 格式的代码示例。

注意

术语“toast 通知”替换为“应用通知”。两个术语指的是 Windows 的相同功能，但随着时间的推移，我们将逐步取消在文档中使用“toast 通知”。

使用入门

应用通知是使用由应用通知架构定义的 XML 有效负载定义的。目前，有三种方法为应用通知生成 XML 有效负载。本文中的代码示例展示了所有三种方法：

Microsoft.Windows.AppNotifications.Builder API - Windows 应用 SDK 1.2 中引入，此命名空间提供 API，使你可以轻松地以编程方式生成通知的 XML 有效负载，而无需担心 XML 格式的具体细节。使用这些 API 的代码示例位于标记为“Windows 应用 SDK”的选项卡中。
Microsoft.Toolkit.Uwp.Notifications 生成器语法 - 这些 API 是 UWP 社区工具包的一部分，为 UWP 应用提供支持。尽管这些 API 还可用于 Windows 应用 SDK 应用，并继续受支持，但我们建议新实现使用 Microsoft.Windows.AppNotifications.Builder API。若要使用社区工具包 API，请将 UWP 社区工具包通知 nuget 包添加到项目中。本文中提供的 C# 示例使用 NuGet 程序包的版本 7.0.0。使用这些 API 的代码示例位于标记为“Windows 社区工具包”的选项卡中。
原始 XML - 如果需要，可以创建自己的自定义代码，以按所需格式生成 XML 字符串。原始 XML 示例位于标记为“XML”的选项卡中。

安装通知可视化工具。 此免费 Windows 应用通过在你编辑时提供 toast 的即时可视预览来帮助你设计交互应用通知，类似于 Visual Studio 的 XAML 编辑器/设计视图。有关详细信息，请参阅通知可视化工具，或从 Microsoft Store 下载通知可视化工具。

本文仅介绍如何创建应用通知内容。有关生成 XML 有效负载后发送通知的信息，请参阅发送本地应用通知。

应用通知结构

应用通知 XML 有效负载的一些重要高级组件包括：

toast：此元素的“启动”属性定义当用户单击 toast 时将传递回应用的参数，使你可以深入了解 toast 显示的正确内容。若要了解详细信息，请参阅发送本地应用通知。
视觉对象：此元素表示 toast 的可视部分，包括包含文本和图像的泛型绑定。
操作：此元素表示 toast 的交互式部分，包括输入和操作。
音频：此元素指定向用户显示 toast 时播放的音频。

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", "9813")

    .AddText("Some text")

    .AddButton(new AppNotificationButton("Archive")
        .AddArgument("action", "archive"))

    .SetAudioUri(new Uri("ms-appx:///Sound.mp3"));

var builder = new ToastContentBuilder()
    .AddArgument("conversationId", 9813)

    .AddText("Some text")

    .AddButton(new ToastButton()
        .SetContent("Archive")
        .AddArgument("action", "archive"))

    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast launch='conversationId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Some text</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
    <actions>
        <action content='Archive' arguments='action=archive'/>
    </actions>
</toast>

下面是应用通知内容的视觉对象表示：

应用通知的屏幕截图，且附带顶部显示应用图标和应用名称“通知可视化工具”的属性区域的对应标签。Toast 的中间部分被标记为可视区域，其中包括三行文本。Toast 的底部部分被标记为操作区域，并包含标记为“接受”和“拒绝”的两个按钮。

属性区域

属性区域位于应用通知的顶部。从 Windows 11 开始，应用的名称和图标显示在此区域中。属性区域还包括一个关闭按钮，允许用户快速关闭通知，以及一个省略号菜单，允许用户快速禁用应用的通知或转到应用通知的 Windows 设置页面。属性区域由 shell 配置，无法在 toast XML 有效负载中重写，但应用可以将项添加到属性区域关联菜单。有关详细信息，请参阅关联菜单操作。

可视

每个应用通知都必须指定一个“视觉对象”元素，其中必须提供一个泛型 toast 绑定，并且其可以包含文本和图像。这些元素将在各种 Windows 设备上呈现，包括桌面、手机、平板电脑和 Xbox。

有关视觉对象部分及其子元素支持的所有属性，请参阅应用通知架构。

文本元素

每个应用通知必须至少有一个文本元素，并且可以包含另外两个文本元素，所有元素都需要是类型 AdaptiveText。

应用通知（包含三行文本）的屏幕截图。最上一行文本为粗体。

自 Windows 10 周年更新起，你可以使用文本上的 HintMaxLines 属性控制显示的文本行数。标题默认（和最大值）为最多 2 行文本，另外两个描述元素（第二和第三个 AdaptiveText）最多为 4 行（合计）。

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", 9813)
    .AddText("Adaptive Tiles Meeting", new AppNotificationTextProperties().SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

var builder = new ToastContentBuilder()
    .AddArgument("meetingId", 9813)
    .AddText("Adaptive Tiles Meeting", hintMaxLines: 1)
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

<toast launch='meetingId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

内联图像

默认情况下，图像在任意文本元素之后内联显示，填充视觉对象区域的完整宽度。

应用通知的屏幕截图，其中显示了默认图像放置、内联以及填充视觉区域的整个宽度。

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

AppNotificationManager.Default.Show(builder.BuildNotification());

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image src='ms-appx:///Images/InlineImage.png'/>
        </binding>
    </visual>
</toast>

应用徽标替代

指定“appLogoOverride”的“放置”值将导致图像显示在视觉对象区域左侧的正方形中。此属性的名称反映了早期版本的 Windows 中的行为，其中图像将替换默认应用徽标图像。在 Windows 11 中，应用徽标显示在属性区域中，因此它不会被 appLogoOverride 图像放置覆盖。

图像尺寸为 48x48 像素，缩放比例为 100%。通常建议每个图标资产每个比例因子提供一个版本：100%、125%、150%、200% 和400%。

应用通知的屏幕截图，其中显示了应用徽标覆盖图像在通知的视觉区域左侧正方形内的放置位置。

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/AppLogo.png'/>
        </binding>
    </visual>
</toast>

提示剪切

Microsoft 样式指南建议使用圆形图像来表示个人资料图片，以便跨应用和 shell 提供一致的人员表示形式。将 HintCrop 属性设置为 Circle，以使用圆形剪切呈现图像。

应用通知的屏幕截图，其中显示了应用徽标覆盖图像在 toast 的视觉区域左侧圆形内裁剪后的放置位置。

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), AppNotificationImageCrop.Circle);

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), ToastGenericAppLogoCrop.Circle);

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/Profile.png' hint-crop='circle'/>
        </binding>
    </visual>
</toast>

主图

周年更新中的新增功能：应用通知可以显示一个主图，这是一个特别推荐的 ToastGenericHeroImage，在 toast 横幅中突出显示，也显示于通知中心内。图像尺寸为 364x180 像素，缩放比例为 100%。

应用通知的屏幕截图，其中显示了主图位置（位于属性区域上方）。

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Mary Anne</text>
            <text>Check out where we camped last night!</text>
            <image placement='hero' src='ms-appx:///Images/HeroImage.png'/>
        </binding>
    </visual>
</toast>

图像大小限制

toast 通知中使用的图像可以获取自...

http://
ms-appx:///
ms-appdata:///

对于 http 和 https 远程 Web 映像，每个图像的文件大小具有限制。在 Fall Creators Update (16299) 中，我们将正常连接上的限制提升至 3 MB，按流量计费的连接上的限制提升至 1 MB。在此之前，图像始终限制为 200 KB。

正常连接	计量连接	Fall Creators Update 以前
3 MB	1 MB	200 KB

如果图像超出文件大小、无法下载或超时，则会删除图像，并显示通知的其余部分。

属性文本

周年更新中的新增功能：如果需要引用内容的源，可以使用属性文本。此文本始终显示在任意文本元素下方，但高于内联图像。文本使用比标准文本元素稍小一些的尺寸，以便将之与常规文本元素区分开来。

在不支持属性文本的较早版本的 Windows 上，文本将仅显示为另一个文本元素（假设你还没有达到三个文本元素的最大值）。

Toast 通知的屏幕截图，其中显示了 toast 视觉区域中其他文本行下方的属性文本“通过短信”。

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetAttributionText("via SMS");
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddAttributionText("Via SMS");
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>  
  <visual>
    <binding template="ToastGeneric">
      <image src="ms-appx:///Images/HeroImage.png"/>
      <text>Mary Anne</text>
      <text>Check out where we camped last night!</text>
      <text placement="attribution">Via SMS</text>
    </binding>
  </visual>
</toast>

自定义时间戳

创建者更新中的新增功能：现在可以使用自己的时间戳替代系统提供的时间戳，该时间戳准确表示生成消息/信息/内容的时间。此时间戳在通知中心内可见。

通知中心内附带自定义时间戳的通知的屏幕截图

若要详细了解如何使用自定义时间戳，请参阅 toast 上的自定义时间戳。

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddCustomTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

<toast displayTimestamp='2017-04-15T12:45:00-07:00'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
        </binding>
    </visual>
</toast>

进度条

Creators Update 中的新增功能：可在应用通知中提供进度栏，让用户时刻了解操作进度，例如下载进度。

显示进度栏的 toast 通知的屏幕截图。

若要了解有关使用进度栏的详细信息，请参阅 toast 进度栏。

标头

创建者更新中的新增功能：可以在通知中心内的标题下对通知进行分组。例如，可以在标题下从群聊对消息进行分组，也可以对标题下常见主题的通知进行分组，或者执行其他操作。

操作中心的屏幕截图，其中显示了以标题“露营！”进行组织的应用程序“通知查看器”的多个通知。

若要了解有关使用标题的详细信息，请参阅 toast 标头。

自适应内容

周年更新中的新增功能：除了上面指定的内容外，还可以显示扩展 toast 时可见的其他自适应内容。

此附加内容是使用“自适应”指定的，可以通过阅读自适应磁贴文档了解详细信息。

请注意，任何自适应内容都必须包含在 AdaptiveGroup 中。否则，不会使用自适应呈现它。

列和文本元素

下面是使用列和一些高级自适应文本元素的示例。由于文本元素位于 AdaptiveGroup 中，因此它们支持所有富自适应样式属性。

Toast 通知的屏幕截图，其中显示了与 toast 视觉区域左侧和右侧对齐的文本元素组。

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support adaptive text elements.

new ToastContentBuilder()
    ...
    
    .AddVisualChild(new AdaptiveGroup()
    {
        Children =
        {
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "52 attendees",
                        HintStyle = AdaptiveTextStyle.Base
                    },
                    new AdaptiveText()
                    {
                        Text = "23 minute drive",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            },
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "1 Microsoft Way",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    },
                    new AdaptiveText()
                    {
                        Text = "Bellevue, WA 98008",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    }
                }
            }
        }
    });

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Reminder: Windows Launch Party</text>
      <text>4:00 PM, 10/21/2021</text>
      <group>
        <subgroup>
          <text hint-style="base">52 attendees</text>
          <text hint-style="captionSubtle">23 minute drive</text>
        </subgroup>
        <subgroup>
          <text hint-style="captionSubtle" hint-align="right">1 Microsoft Way</text>
          <text hint-style="captionSubtle" hint-align="right">Bellevue, WA 98008</text>
        </subgroup>
      </group>
    </binding>
  </visual>
</toast>

Buttons

按钮使 toast 获得交互性，让用户在应用通知上快速执行操作，而不会中断其当前工作流。例如，用户可以直接从 toast 内回复消息，或在无需打开电子邮件应用的情况下删除电子邮件。按钮显示在通知的展开部分。

若要详细了解如何端到端实现按钮，请参阅发送本地 toast。

按钮可以通过以下方式激活应用：

应用在前台激活，其中包含可用于导航到特定页面/上下文的参数。
另一个应用通过协议启动激活。
UWP 应用显式支持后台激活。对于 Windows 应用 SDK 应用，应用始终在前台启动。应用可以调用 AppInstance.GetActivatedEventArgs 来检测激活是否由通知启动，并从传递的参数中确定是完全启动前台应用还是只处理通知和退出。
UWP 应用和 Windows 应用 SDK 都支持推迟或关闭通知等系统操作。 AppNotificationBuilder API 不支持此方案，但 Windows 应用 SDK 应用可以使用 Microsoft.Windows.AppNotifications.Builder API 或原始 XML 实现此方案。

注意

最多只能有 5 个按钮（包括稍后讨论的关联菜单项）。

Toast 通知的屏幕截图，其中显示了一行文本后跟一行内容（其中包含由操作元素定义的两个按钮）。

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("New product in stock!")
        .AddButton(new AppNotificationButton("See more details")
            .AddArgument("action", "viewDetails"))
            .AddArgument("contentId", "351")
        .AddButton(new AppNotificationButton("Remind me later")
            .AddArgument("action", "remindLater"))
            .AddArgument("contentId", "351");

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("See more details")
        .AddArgument("action", "viewDetails"))

    .AddButton(new ToastButton()
        .SetContent("Remind me later")
        .AddArgument("action", "remindLater"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>New product in stock!</text>
        </binding>
    </visual>
      <actions>
          <action content='See more details' arguments='action=viewDetails;contentId=351'/>
          <action content='Remind me later' arguments='action=remindLater;contentId=351'/>
      </actions>
</toast>

带有图标的按钮

你可以向按钮添加图标。这些图标是白色透明 16x16 像素图像，缩放比例为 100%，并且不应在图像本身中包含填充。如果选择在 toast 通知上提供图标，则必须为通知中的所有按钮提供图标，因为它将按钮的样式转换为图标按钮。

注意

对于辅助功能，请确保包含图标的 contrast-white 版本（白色背景的黑色图标），以便当用户打开高对比度白色模式时，你的图标可见。有关详细信息，请参阅磁贴和 toast 通知的语言、比例和高对比度支持。

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("Return books to the library.")
        .AddButton(new AppNotificationButton("Accept")
            .AddArgument("action", "accept")
            .SetIcon(new Uri("ms-appx:///Images/Accept.png")))
        .AddButton(new AppNotificationButton("Snooze")
            .AddArgument("action", "snooze")
            .SetIcon(new Uri("ms-appx:///Images/Snooze.png")))
        .AddButton(new AppNotificationButton("Dismiss")
            .AddArgument("action", "dismiss")
            .SetIcon(new Uri("ms-appx:///Images/Dismiss.png")));

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("Accept")
        .AddArgument("action", "accept")
        .SetImageUri(new Uri("ms-appx:///Images/Accept.png")))
    .AddButton(new ToastButton()
        .SetContent("Snooze")
        .AddArgument("action", "snooze")
        .SetImageUri(new Uri("ms-appx:///Images/Snooze.png")))
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss")
        .SetImageUri(new Uri("ms-appx:///Images/Dismiss.png")));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Return books to the library.</text>
        </binding>
    </visual>
    <actions>
        <action content='Accept' arguments='action=accept' imageUri='ms-appx:///Assets/Accept.png'/>
        <action content='Snooze' arguments='action=snooze' imageUri='ms-appx:///Assets/Snooze.png'/>
        <action content='Dismiss' arguments='action=dismiss' imageUri='ms-appx:///Assets/Dismiss.png'/>
    </actions>
</toast>

Windows 11 更新中的新增功能：可以使用 XML 中的 HintToolTip 属性向图标添加工具提示。如果你的按钮具有图标，但没有内容，这是理想的选择，因为这样可以确保你可以传递 Windows 讲述人可以朗读的文本。但是，如果存在内容，则无论在工具提示中传递什么内容，讲述人都会朗读内容。

var button = new AppNotificationButton("Reply")
    .AddArgument("action", "reply");

if (AppNotificationButton.IsToolTipSupported())
{
    button.ToolTip = "Click to reply.";
}

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .AddButton(button);

// The Community Toolkit builder syntax does not currently support icon tooltips.

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Reply' arguments='action=reply' hint-toolTip='Click to reply'/>
    </actions>
</toast>

带有颜色的按钮

Windows 11 更新中的新增功能：通过将 useButtonStyle 属性添加到 toast XML 元素，将 hint-buttonStyle 属性添加到操作 XML 元素，可向按钮添加红色或绿色，如下所示。

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .AddText("Incoming Call - Mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///Images/Profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Video Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Video.png"))
        .AddArgument("videoId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Phone Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Call.png"))
        .AddArgument("callId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Hang Up")
        .SetButtonStyle(AppNotificationButtonStyle.Critical)
        .SetIcon(new Uri("ms-appx:///Images/HangUp.png"))
        .AddArgument("hangUpId", "123"));

// The WIndows Community Toolkit builder syntax does not currently support red and green button colors.

<toast scenario='incomingCall' useButtonStyle='true'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>Incoming Call - Mobile</text>
            <image src='ms-appx:///Images/InlineImage.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='' 
            arguments='videoId=123' 
            imageUri='ms-appx:///Images/Video.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Video Call'/>
        <action 
            content='' 
            arguments='callId=123' 
            imageUri='ms-appx:///Images/Call.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Phone Call'/>
        <action 
            content='' 
            arguments='hangUpId=123' 
            imageUri='ms-appx:///Images/HangUp.png' 
            hint-buttonStyle='Critical' 
            hint-toolTip='Hang Up'/>
    </actions>
</toast>

周年更新中的新增功能：可以将其他关联菜单操作添加到用户右键单击 toast 通知或选择关联菜单图标时显示的现有关联菜单。

注意

在较旧的设备上，这些附加的关联菜单操作只会显示为通知上的正常按钮。

添加的其他关联菜单操作（如“将群聊静音 1 小时”）显示在两个默认系统项的上方。

var builder = new AppNotificationBuilder()
    .AddText("Camping this weekend?")
    .SetAppLogoOverride(new Uri("ms-appx:///images/Reply.png"), AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Mute group chat for 1 hour")
        .AddArgument("action", "mute")
        .SetContextMenuPlacement());

Windows 社区工具包生成器语法目前不支持上下文菜单操作，因此建议使用初始值设定项语法。

ToastContent content = new ToastContent()
{
    ...
 
    Actions = new ToastActionsCustom()
    {
        ContextMenuItems =
        {
            new ToastContextMenuItem("Mute group chat for 1 hour", "action=muteId")
        }
    }
};

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Camping this weekend?</text>
            <image placement='appLogoOverride' src='ms-appx:///images/Reply.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action content='Mute group chat for 1 hour' arguments='action=mute' placement='contextMenu'/>
    </actions>
</toast>

注意

其他关联菜单项计入 toast 上 5 个按钮的总限值。

其他关联菜单项的激活处理方式与 toast 按钮相同。

输入

输入在应用通知的“操作”区域中指定，这意味着它们仅在展开通知时才可见。

快速回复文本框

要启用快速回复文本框（例如，在消息应用程序中），请添加文本输入和按钮，并引用文本输入字段的 ID，以便按钮显示在输入字段旁边。此按钮的可选图标（如提供）应为 32x32 像素图像，无填充，像素设置为透明，比例为 100%。

包含个人资料图片和某些文本行的 toast 通知的屏幕截图。其中还包含用于直接键入到 toast 的文本框，以及用于发送回复的按钮。

var builder = new AppNotificationBuilder()
    .AddTextBox("textBox", "Type a reply", "Reply")
    .AddButton(AppNotificationButton("Send")
        .AddArguments("action", "Send")
        .SetInputId("textBox"))
    .BuildNotification();

var builder = new ToastContentBuilder()
    .AddInputTextBox("tbReply", "Type a reply")
        .AddButton(new ToastButton()
        .SetContent("Reply")
        .SetTextBoxId("tbReply") // To place button next to text box, reference text box's id
        .SetImageUri(new Uri("Assets/Reply.png", UriKind.Relative))
        .AddArgument("action", "reply"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Send"
      arguments="action=reply&amp;convId=9318"
      hint-inputId="textBox"
      imageUri="Assets/Reply.png"/>
  </actions>
</toast>

带有按钮栏的输入

还可以有一个（或多个）输入，其中普通按钮显示在输入下方。

应用通知的屏幕截图，其中显示了一行文本、一个文本框和一行内容（其中包含标记为“回复”和“视频通话”的两个按钮）。

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support quick reply text boxes.

new ToastContentBuilder()
    ...
    
    .AddInputTextBox("tbReply", "Type a reply")

    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply"))

    .AddButton(new ToastButton()
        .SetContent("Video call")
        .AddArgument("action", "videoCall"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Reply"
      arguments="action=reply&amp;threadId=9218"/>
    <action
      content="Video call"
      arguments="action=videocall&amp;threadId=9218"
      activationType="foreground"/>
  </actions>
</toast>

选项输入

除了文本框，还可以使用选择菜单。

应用通知的屏幕截图，其中显示了一行文本、一个将“午餐”作为选定项的选择输入，以及一行内容（其中包含标记为“预订”和“呼叫餐厅”的两个按钮）。

var builder = new AppNotificationBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddComboBox(new AppNotificationComboBox("time")
        .SetTitle("Select an item:")
        .AddItem("breakfast", "Breakfast")
        .AddItem("lunch", "Lunch")
        .AddItem("dinner", "Dinner")
        .SetSelectedItem("lunch"))
    .AddButton(new AppNotificationButton("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement())
    .AddButton(new AppNotificationButton("Call restaurant")
        .AddArgument("action", "videocall")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement());

var builder = new ToastContentBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddToastInput(new ToastSelectionBox("time")
    {
        DefaultSelectionBoxItemId = "lunch",
        Items =
            {
                new ToastSelectionBoxItem("breakfast", "Breakfast"),
                new ToastSelectionBoxItem("lunch", "Lunch"),
                new ToastSelectionBoxItem("dinner", "Dinner")
            }
    })
    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218"))
    .AddButton(new ToastButton()
        .SetContent("Call restaurant")
        .AddArgument("action", "videoCall")
        .AddArgument("threadId", "9218"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>4th coffee?</text>
            <text>When do you plan to come in tomorrow?</text>
        </binding>
    </visual>
    <actions>
        <input id='time' type='selection' title='Select an item:' defaultInput='lunch'>
            <selection id='breakfast' content='Breakfast'/><selection id='dinner' content='Dinner'/>
            <selection id='lunch' content='Lunch'/>
        </input>
        <action content='Reply' arguments='action=reply;threadId=9218' placement='contextMenu'/>
        <action content='Call Restaurant' arguments='action=videocall;threadId=9218' placement='contextMenu'/>
    </actions>
</toast>

暂停/取消

使用选择菜单和两个按钮，我们可以创建一个利用系统推迟和关闭操作的提醒通知。请确保将方案设置为“提醒”，令通知的行为类似于提醒。

应用通知的屏幕截图，其中包含用于描述某一会议的时间和位置的文本行。某一选择框选择了“15 分钟”，且有标记为“推迟”和“取消”的按钮。

我们使用 toast 按钮上的 SelectionBoxId 属性将“推迟”按钮链接到选择菜单输入。

Microsoft.Windows.AppNotifications.Builder 语法当前不支持系统激活。但是，Windows 应用 SDK 应用支持此方案，可以使用 Microsoft.Toolkit.Uwp.Notifications API 或原始 XML 为此方案生成通知。

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support system activation. 
// But this scenario is supported for Windows App SDK apps, and you can build notifications for this 
// scenario using the `Microsoft.Toolkit.Uwp.Notifications` APIs or raw XML.

new ToastContentBuilder()
    .SetToastScenario(ToastScenario.Reminder)
    
    ...
    
    .AddToastInput(new ToastSelectionBox("snoozeTime")
    {
        DefaultSelectionBoxItemId = "15",
        Items =
        {
            new ToastSelectionBoxItem("5", "5 minutes"),
            new ToastSelectionBoxItem("15", "15 minutes"),
            new ToastSelectionBoxItem("60", "1 hour"),
            new ToastSelectionBoxItem("240", "4 hours"),
            new ToastSelectionBoxItem("1440", "1 day")
        }
    })

    .AddButton(new ToastButtonSnooze() { SelectionBoxId = "snoozeTime" })
    .AddButton(new ToastButtonDismiss());

<toast>
  <visual>
    <binding template="ToastGeneric">
      <text hint-maxLines="1">Adaptive Tiles Meeting</text>
      <text>Conf Room 2001 / Building 135</text>
      <text>10:00 AM - 10:30 AM</text>
    </binding>
  </visual>
  <actions>
    <input id="snoozeTime" type="selection" defaultInput="15">
      <selection id="1" content="1 minute"/>
      <selection id="15" content="15 minutes"/>
      <selection id="60" content="1 hour"/>
      <selection id="240" content="4 hours"/>
      <selection id="1440" content="1 day"/>
    </input>
    <action activationType="system" arguments="snooze" hint-inputId="snoozeTime" content="" />
    <action activationType="system" arguments="dismiss" content=""/>
  </actions>
</toast>

若要使用系统推迟和关闭操作：

指定 ToastButtonSnooze 或 ToastButtonDismiss
（可选）指定自定义内容字符串：
如果未提供字符串，我们将自动将本地化字符串用于“推迟”和“关闭”。
（可选）指定 SelectionBoxId：
如果你不希望用户选择推迟间隔，而只是希望通知只推迟一次系统定义的时间间隔（在 OS 中保持一致），则不要构造任何“输入”<>。
如果要提供推迟间隔选择：- 在推迟操作中指定 SelectionBoxId - 将输入的 ID 与推迟操作的 SelectionBoxId 匹配 - 将 ToastSelectionBoxItem 的值指定为 nonNegativeInteger，表示以分钟为单位的推迟间隔。

音频

自定义音频始终在移动版上受支持，且在桌面版本 1511（版本 10586）或更高版本中受支持。可以通过以下路径引用自定义音频：

ms-appx:///
ms-appdata:///

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioUri(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
</toast>

或者，可以从 ms-winsoundevents 列表中进行选择，该列表始终在两类平台上受支持。

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioEvent(AppNotificationSoundEvent.Alarm, AppNotificationAudioLooping.Loop);

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-winsoundevent:Notification.Looping.Alarm"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-winsoundevent:Notification.Looping.Alarm' loop='true'/>
</toast>

有关应用通知中的音频的信息，请参阅音频架构页。若要了解如何发送使用自定义音频的应用通知，请参阅 toast 上的自定义音频。

方案

若要创建重要通知、警报、提醒和传入呼叫通知，只需使用分配有“方案”值的普通应用通知。此方案调整了一些行为，以创建一致且统一的用户体验。可以有四个“应用场景”值：

Reminder
Alarm
IncomingCall
Urgent

Reminders

在提醒方案中，通知将保持在屏幕上，直到用户将其关闭或采取操作。在 Windows Mobile 上，应用通知还会显示预展开。将播放提醒声音。必须在应用通知上提供至少一个按钮。否则，通知将被视为普通通知。

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Reminder);

var builder = new ToastContentBuilder()
    .AddText("Notification text.")
    .SetToastScenario(ToastScenario.Reminder)

<toast scenario='reminder'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
</toast>

警报

警报的行为与提醒相同，但警报将额外循环使用默认警报声音的音频。必须在应用通知上提供至少一个按钮。否则，通知将被视为普通通知。

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Alarm)
    .AddButton(new AppNotificationButton("Dismiss")
        .AddArgument("action", "dismiss"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .SetToastScenario(ToastScenario.Alarm)
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss"));

<toast scenario='alarm'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Dismiss' arguments='action=dismiss'/>
    </actions>
</toast>

来电

传入呼叫通知以特殊呼叫格式预展开显示，并停留在用户的屏幕上，直到关闭。默认情况下，铃声音频将循环播放。在 Windows Mobile 设备上，它们全屏显示。

来电 toast 通知。

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
    .AddText("incoming call - mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///images/profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Text reply")
        .SetToolTip("Text reply")
        .SetIcon(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new AppNotificationButton("Reminder")
        .SetToolTip("Reminder")
        .SetIcon(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new AppNotificationButton("Ignore")
        .SetToolTip("Ignore")
        .SetIcon(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new AppNotificationButton("Answer")
        .SetToolTip("Answer")
        .SetIcon(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

var builder = new ToastContentBuilder()
    .SetToastScenario(ToastScenario.IncomingCall)
    .AddText("Andrew Bares")
    .AddText("incoming call - mobile")
    .AddInlineImage(new Uri("ms-appx:///images/profile.png"), 
        "Andrew Bares",
        null,
        AdaptiveImageCrop.Circle)
    .AddButton(new ToastButton()
        .SetContent("Text reply")
        .SetImageUri(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Reminder")
        .SetImageUri(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Ignore")
        .SetImageUri(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Answer")
        .SetImageUri(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

<toast scenario='incomingCall'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>incoming call - mobile</text>
            <image src='ms-appx:///images/profile.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='Text reply' 
            arguments='textId=123' 
            imageUri='ms-appx:///images/reply.png' 
            hint-toolTip='Text reply'/>
        <action 
                content='Reminder' 
                arguments='reminderId=123' 
                imageUri='ms-appx:///images/reminder.png' 
                hint-toolTip='Reminder'/>
        <action 
                content='Ignore' 
                arguments='ignoreId=123' 
                imageUri='ms-appx:///images/ignore.png' 
                hint-toolTip='Ignore'/>
        <action 
            content='Answer' 
            arguments='answerId=123' 
            imageUri='ms-appx:///images/answer.png' 
            hint-toolTip='Answer'/>
    </actions>
</toast>

重要通知

重要

要求：必须运行 Windows Insider Preview 版本 22546 或更高版本才能使用重要通知。

重要通知允许用户更好地控制第一方和第三方应用可以向自己发送什么高优先级应用通知（紧急/重要），这些通知可以突破专注助手（请勿打扰）。这可以在通知设置中修改。

紧急应用通知的屏幕截图，而该通知在应用名称旁的属性区域中显示有感叹号。该图像还显示了系统启动的应用通知，而该通知为用户提供了用于允许或禁止来自该应用的紧急通知的按钮。

var builder = new AppNotificationBuilder()
    .AddText("Adaptive Tiles Meeting", 
        new AppNotificationTextProperties()
            .SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

if (AppNotificationBuilder.IsUrgentScenarioSupported())
{
    builder.SetScenario(AppNotificationScenario.Urgent);
}

// The builder syntax does not support important notifications yet.

<toast scenario='urgent'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

本地化和辅助功能

磁贴和应用通知可以加载为显示语言、显示比例系数、高对比度和其他运行时上下文定制的字符串和图像。有关更多信息，请参阅磁贴和 toast 通知的语言、比例和高对比度支持。

处理激活

若要了解如何处理应用激活（用户单击 toast 或 toast 上的按钮），请参阅发送本地 toast。

通过