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

注意

术语“toast 通知”将替换为“应用通知”。 这些术语都指 Windows 的相同功能，但随着时间的推移，我们将逐步淘汰文档中的“Toast 通知”的使用。

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

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

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

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

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

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

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

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

每个应用通知必须至少有一个文本元素，并且可以包含两个附加的文本元素，所有文本元素的类型均为 AdaptiveText。

自 Windows 10 周年更新起，可使用文本的 HintMaxLines 属性控制显示的文本行数。 标题文本的默认（及最大）行数最多为 2 行，两个额外的说明元素（第二个和第三个 AdaptiveText）的行数最多为 4 行（合并后）。

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

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

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

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

周年更新中的新增功能：应用通知可以显示一个主图图像，这是一个特色 ToastGenericHeroImage ，在 Toast 横幅内和通知中心内突出显示。 图像尺寸在 100% 缩放时为 364x180 像素。

Toast 通知中使用的图像可源自以下位置...

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

如果图像超过此文件大小、无法下载或超时，则该图像将被删除，但通知的剩余部分会显示。

周年更新中的新增功能：如果你需要引用你的内容源，可以使用署名文本。 此文本始终显示在任何文本元素下方，但显示在内联图像上方。 文本使用比标准文本元素略小一些的大小来帮助区分常规文本元素。

在不支持署名文本的旧 Windows 版本中，该文本仅显示为另一文本元素（假设你还没有达到最多的三个文本元素）。

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

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

创意者更新中的新增功能：可以在应用通知上提供进度栏，使用户随时了解下载等操作的进度。

若要详细了解如何使用进度栏，请参阅 Toast 进度栏。

创意者更新中的新增功能：可以在通知中心内的标题下对通知进行分组。 例如，你可以将群聊中的组消息分到一个标题下，或将常见主题的通知分到一个标题下等等。

若要详细了解如何使用标题，请参阅 Toast 标题。

周年更新中的新增功能：除了上面指定的内容外，你还可以显示在展开 Toast 时可见的附加自适应内容。

这些附加内容是用 Adaptive 指定的，阅读自适应磁贴文档可了解更多内容。

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

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

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

若要详细了解如何端到端操控按钮，请参阅发送本地 Toast。

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

注意

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

可向按钮添加图标。 这些图标在 100% 缩放时为白色透明的 16x16 像素图像，且图像本身不应包含任何填充。 如果选择在一条 Toast 通知上提供图标，则必须为该通知中的所有按钮提供图标，因为该操作会将按钮样式转换为图标按钮。

注意

为实现辅助功能，请务必添加“白对比色”版本的图标（白色背景的黑色图标），以便用户在打开高对比度白色模式时，图标清晰可见。 有关详细信息，请参阅 对语言、缩放和高对比度的磁贴和 Toast 通知支持。

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

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

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

注意

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

添加 (的其他上下文菜单操作，例如“将群组聊天设为静音 1 小时”) 显示在两个默认系统条目上方。

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

注意

其他关联菜单项计入 Toast 按钮（数量上限为 5 个）。

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

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

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

还可使用一个（或多个）输入，在输入下方显示正常按钮。

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

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

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

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

若要使用系统推迟和消除操作：

移动版始终支持自定义音频，桌面版本 1511 (内部版本 10586) 或更高版本支持自定义音频。 可通过以下路径引用自定义音频：

或者，你可以从 ms winsoundevents 列表中选择，它始终在两种平台上受支持。

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

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

在提醒方案中，通知将一直在屏幕上，直到用户将其关闭或执行操作。 在 Windows 移动版上，应用通知也会显示预展开。 将播放提醒声音。 必须在应用通知上提供至少一个按钮。 否则，通知将被视为正常通知。

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

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

重要

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

重要通知允许用户更好地控制哪些第一方和第三方应用可以向他们发送高优先级应用通知 (紧急/重要) ，这些通知可以突破焦点助手 (请勿打扰) 。 这可以在通知设置中修改。

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

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