应用通知内容

本文介绍可在应用通知中使用的 UI 元素，并提供用于生成通知内容的代码示例。有关应用通知的详细信息，请参阅应用通知概述。有关实现应用通知的演练，请参阅快速入门：Windows 应用 SDK 中的应用通知。

入门

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

Microsoft.Windows.AppNotifications.Builder API - Windows 应用 SDK 1.2 中引入的此命名空间提供 API，使你可以通过编程方式轻松生成通知的 XML 有效负载，而无需担心 XML 格式的具体细节。使用这些 API 的代码示例位于标记为“Windows 应用 SDK”的选项卡中。
原始 XML - 如果需要，可以创建自己的自定义代码，以按所需格式生成 XML 字符串。原始 XML 示例位于标记为“XML”的选项卡中。

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

本文仅介绍如何创建应用通知内容。有关发送通知的信息，请参阅应用通知概述。

应用通知结构

应用通知 XML 数据负载中的一些重要的高级组件包括：

toast：此元素的 launch 属性定义了当用户单击 toast 时，将传递回你应用的参数。这使你能够进行深度链接到 toast 显示的正确内容。若要了解详细信息，请参阅应用通知概述。
视觉对象：此元素表示 toast 的可视部分，包括包含文本和图像的泛型绑定。
操作：该元素代表 toast 的交互部分，包括输入和操作。
音频：此元素指定在向用户显示 toast 时播放的音频。

Windows 应用 SDK
XML

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

    .AddText("Some text")

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

    .SetAudioUri(new Uri("ms-appx:///Sound.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>

下面是应用通知内容的可视表示形式：

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

归属区域

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

视觉

每个应用通知都必须指定一个 视觉对象 元素，其中必须提供一个通用 Toast 绑定，其中包含文本和图像。这些元素将在各种Windows设备上呈现，包括台式机、手机、平板电脑和Xbox。

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

文本元素

每个应用通知必须至少包含一个文本元素，并且可以包含另外两个文本元素，所有这些都是类型为 AdaptiveText。文本元素支持数据绑定，这样就可以在显示通知后更新文本内容。有关详细信息，请参阅应用通知进度栏和数据绑定。

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

可以使用 AppNotificationTextProperties.SetMaxLines 方法控制显示的文本行数。默认（和最大值）标题最多为 2 行文本，两个附加描述元素（第二个和第三个 AdaptiveText）组合最多为 4 行。

Windows 应用 SDK
XML

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");

<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>

内联图像

默认情况下，图像在任意文本元素之后内联显示，填充视觉区域的完整宽度。使用 AppNotificationBuilder.SetInlineImage 添加内联图像。

一张应用通知的屏幕截图，显示默认图像内联放置，填满了视觉区域的整个宽度。

Windows 应用 SDK
XML

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

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

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

应用徽标替代

指定“appLogoOverride”的定位值将使图像显示在可视区域左侧的正方形中。使用 AppNotificationBuilder.SetAppLogoOverride 设置此映像。此属性的名称反映了以前版本的 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"));

提示剪裁功能

Microsoft 样式指南建议使用圆形图像来表示头像，以便在应用和外壳之间提供一致的人物表示形式。将 AppNotificationImageCrop.Circle 传递给 SetAppLogoOverride ，以使用圆形裁剪呈现图像。

应用通知的截图，显示应用程序徽标的图像被裁剪成圆形并放置于提示框视觉区域的左侧。

Windows 应用 SDK
XML

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);

<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>

英雄图像

应用通知可以显示一张显著的特色图，这是在 Toast 横幅和通知中心内醒目展示的 ToastGenericHeroImage。使用 AppNotificationBuilder.SetHeroImage 添加主图。图像尺寸为 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"));

图像大小限制

应用通知中使用的图像可以从...

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

对于 http 和 https 远程 Web 映像，每个图像的文件大小有限制。正常连接限制为 3 MB，按流量计费的连接限制为 1 MB。

正常连接	按流量计费的连接
3 兆字节	1 MB

如果图像超过文件大小限制、无法下载或超时，图像将被删除，通知的其余部分将显示。

属性文本

如果需要引用内容源，可以使用属性文本。使用 AppNotificationBuilder.SetAttributionText 设置属性文本。此文本始终显示在任何文本元素下方，但高于内联图像。文本使用比标准文本元素稍小一些的大小来帮助区分常规文本元素。

在不支持说明文本的旧版本 Windows 上，文本将仅作为另一个文本元素显示（假设你还没有达到最多三个文本元素的限制）。

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

Windows 应用 SDK
XML

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"));

<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>

自定义时间戳

可以使用自己的时间戳替代系统提供的时间戳，该时间戳准确表示生成消息/信息/内容的时间。此时间戳在通知中心内可见。

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

若要了解有关使用自定义时间戳的详细信息，请参阅应用通知上的自定义时间戳。

Windows 应用 SDK
XML

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));

<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>

进度栏

可以在应用通知上提供进度栏，让用户了解下载等操作的进度。进度栏支持数据绑定，这使你可以在显示通知后动态更新进度值。

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

若要了解有关使用进度栏的详细信息，请参阅应用通知进度栏和数据绑定。

标题

可以在通知中心内的标头下对通知进行分组。例如，您可以在一个标题下将群聊中的消息进行分组，或在一个标题下按常见主题将通知进行分组，还可以有更多方式。

一张操作中心的截图，显示了应用程序“通知查看器”的多个通知，这些通知被归类在一个标记为“露营！”的标题下。

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

自适应内容

除了上面指定的内容之外，还可以显示扩展 Toast 时可见的其他自适应内容。

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

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

列和文本元素

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

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

Windows 应用 SDK
XML

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

<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>

按钮

按钮使 Toast 交互，让用户在应用通知上快速执行作，而不会中断其当前工作流。例如，用户可以直接从 Toast 内回复邮件，或删除电子邮件，甚至无需打开电子邮件应用。按钮会出现在通知栏的展开部分。使用 AppNotificationButton 定义按钮， AppNotificationBuilder.AddButton 将其添加到通知。

若要详细了解如何端到端实现按钮，请参阅应用通知概述。

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

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

注释

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

应用通知的屏幕截图，显示一行文本，后面跟着一行包含两个由动作元素构成的按钮。

Windows 应用 SDK
XML

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");

<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>

带有图标的按钮

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

注释

为了提高可访问性，请确保包括图标的白色对比版本（适用于白色背景的黑色图标），以便在用户启用高对比度白色模式时，你的图标依然可见。有关详细信息，请参阅磁贴和 toast 通知支持的语言、缩放和高对比度。

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")));

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

Windows 应用 SDK
XML

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);

<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的新增功能：可以使用AppNotificationButton.SetButtonStyle与AppNotificationButtonStyle向按钮添加红色或绿色。在 XML 中，将 useButtonStyle 属性添加到 toast 元素，并将 hint-buttonStyle 属性添加到操作元素，如下所示。

Windows 应用 SDK
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"));

<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>

可以将其他上下文菜单操作添加到用户右键单击应用通知或选择上下文菜单图标时显示的现有上下文菜单。使用 AppNotificationButton.SetContextMenuPlacement 在上下文菜单中放置按钮，而不是操作栏。

注释

在较旧的设备上，这些附加的上下文菜单操作只会显示为通知上的普通按钮。

添加的其他上下文菜单作（如“1 小时静音群组聊天”）显示在两个默认系统条目上方。

Windows 应用 SDK
XML

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());

<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 按钮相同。

输入

输入在应用通知的操作区中指定，这意味着这些输入仅在通知展开时可见。

快速答复文本框

若要启用快速答复文本框（例如，在消息应用中），请使用 AppNotificationBuilder.AddTextBox 和按钮添加文本输入，并引用文本输入字段的 ID，以便按钮显示在输入字段旁边。按钮的可选图标（如果提供）应为 32x32 像素图像，且不填充、白色像素设置为透明，以及 100 个% 刻度。

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

Windows 应用 SDK
XML

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

<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>

带有按钮栏的输入框

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

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

Windows 应用 SDK
XML

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

<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>

选择输入

除了文本框，还可以将选择菜单与 AppNotificationBuilder.AddComboBox 配合使用。

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

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());

Snooze/dismiss

使用选择菜单和两个按钮，我们可以创建一个利用系统暂停和消除操作的提醒通知。请确保将场景设置为“提醒”，这样通知的行为就像提醒一样。

一个应用程序通知的屏幕截图，其中包含描述会议时间和位置的文本行。选择框中选择了“15 分钟”，并且有标记为“稍后提醒”和“忽略”的按钮。

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

Microsoft.Windows。AppNotifications.Builder 语法目前不支持系统激活。但是，Windows 应用 SDK应用支持此方案，可以使用原始 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 raw XML.

若要使用系统暂停和消除操作，请执行以下操作：

指定 ToastButtonSnooze 或 ToastButtonDismiss
（可选）指定自定义内容字符串：
如果未提供字符串，我们将自动将本地化字符串用于“暂停”和“消除”。
（可选）指定 SelectionBoxId：
如果你不希望用户选择延迟间隔，而只是希望通知只在整个系统中一致的系统定义的时间间隔里延迟一次，那么就不要构造任何 <输入>。
如果想提供打盹间隔选择：- 在打盹操作中指定 SelectionBoxId - 将输入的 ID 与打盹操作的 SelectionBoxId 匹配 - 指定 ToastSelectionBoxItem的值，该值须是非负整数，表示打盹间隔（以分钟为单位）。

音频

使用 AppNotificationBuilder.SetAudioUri 指定自定义音频文件，或使用 AppNotificationBuilder.SetAudioEvent 选择系统声音。可以通过以下路径引用自定义音频：

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

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

或者，您可以从列表中的 ms-winsoundevents进行选择，这些项目在两个平台上一直都受支持。

Windows 应用 SDK
XML

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

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

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

场景

若要创建重要通知、警报、提醒和传入呼叫通知，请使用 AppNotificationBuilder.SetScenario 和 AppNotificationScenario 值。此方案调整了一些行为，以创建一致的统一用户体验。有四种可能的方案值：

Reminder
Alarm
IncomingCall
Urgent

提醒事项

在提醒场景中，通知将保持在屏幕上，直到用户将其消除或采取行动。在Windows移动版上，应用通知也会显示预扩展。将播放提醒声音。必须在应用通知上至少提供一个按钮。否则，通知将被视为普通通知。

Windows 应用 SDK
XML

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

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

警报

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

Windows 应用 SDK
XML

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Alarm)
    .AddButton(new AppNotificationButton("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移动设备上，显示全屏。

来电应用通知

Windows 应用 SDK
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("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"));

<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>

重要通知

重要

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

重要通知使用户能够更好地控制哪些第一方和第三方应用可以向他们发送高优先级的应用通知（紧急/重要），这些通知能够突破专注模式（请勿打扰）。这可以在通知设置中修改。

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

Windows 应用 SDK
XML

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);
}

<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 通知支持语言、缩放和高对比度。

处理激活

若要了解如何处理应用激活（用户单击通知或通知上的按钮），请参阅应用通知概述。

反馈

此页面是否有帮助？

Last updated on 2026-04-21