Toast 内容
借助自适应和交互式 toast 通知，可使用文本、图像和按钮/输入创建灵活的通知。
重要的 API：UWP 社区工具包通知 NuGet 程序包
入门
可以使用 XML 或 Microsoft.Toolkit.Uwp.Notifications 生成器语法定义通知的内容。 若要使用 XML，请按照下面的 XML 示例选项卡进行操作，并引用 Toast 通知 XML 架构。 若要使用 Microsoft.Toolkit.Uwp.Notification C# 生成器语法，请安装 NuGet 包 Microsoft.Toolkit.Uwp.Notifications，请按照下面的 Builder 语法 示例选项卡进行操作，并引用 Toast 内容架构。 本文中提供的 C# 示例使用 NuGet 程序包的版本 7.0.0。
安装通知可视化工具。 此免费 Windows 应用通过在你编辑时提供 toast 的即时可视预览来帮助你设计交互 toast 通知，类似于 Visual Studio 的 XAML 编辑器/设计视图。 请参阅通知可视化工具了解详细信息，或从 Microsoft Store 下载通知可视化工具。
发送 toast 通知
要了解如何发送通知，请参阅发送本地 Toast。 本文档仅介绍如何创建 Toast 内容。
Toast 通知结构
Toast 通知是某些数据属性（如标记/组，用于标识通知）与 Toast 内容的组合。
Toast 内容的核心组件有
- launch：定义当用户单击你的 Toast 时将传回应用的参数，允许你深层链接到 Toast 所显示的正确内容。 有关详细信息，请参阅发送本地 Toast。
- visual：toast 的可视部分，包括带有文本和图像的通用绑定。
- actions：toast 的交互部分，包括输入和操作。
- audio：控制向用户显示 Toast 时播放的音频。
Toast 内容在原始 XML 中定义，但你可以使用我们的 NuGet 库获取 C#（或 C++）对象模型来构造 Toast 内容。 本文介绍了 Toast 内容中的所有内容。
new ToastContentBuilder()
.AddArgument("conversationId", 9813)
.AddText("Some text")
.AddButton(new ToastButton()
.SetContent("Archive")
.AddArgument("action", "archive")
.SetBackgroundActivation())
.AddAudio(new Uri("ms-appx:///Sound.mp3"));
下面是 Toast 内容的可视化表示形式：
属性区域
属性区域位于 Toast 通知的顶部。 从Windows 11开始，应用的名称和图标会显示在此区域中。 属性区域还包括一个关闭按钮，允许用户快速关闭通知和省略号菜单，允许用户快速禁用应用的通知或转到应用的通知的 Windows 设置页面。 属性区域由 shell 配置，无法在 Toast XML 有效负载中重写，尽管应用可以将项添加到属性区域上下文菜单。 有关详细信息，请参阅 上下文菜单操作。
视觉对象
每个 toast 均必须指定一个 visual，此处必须包含带文本、图像等的通用 toast 绑定。 这些元素将在各种 Windows 设备上呈现，包括桌面设备、手机、平板电脑和 Xbox。
有关可视部分支持的所有属性及其子元素，请参阅架构文档。
文本元素
每个 toast 均必须具有至少一个文本元素，此外还可包含两个文本元素，类型均为 AdaptiveText。
自 Windows 10 周年更新起，可使用文本的 HintMaxLines 属性控制显示的文本行数。 标题文本的默认（及最大）行数最多为 2 行，两个额外的说明元素（第二个和第三个 AdaptiveText）的行数最多为 4 行（合并后）。
new ToastContentBuilder()
.AddText("Adaptive Tiles Meeting", hintMaxLines: 1)
.AddText("Conf Room 2001 / Building 135")
.AddText("10:00 AM - 10:30 AM");
内联图像
默认情况下，图像以内联方式显示在任何文本元素之后，填充视觉区域的完整宽度。
new ToastContentBuilder()
...
.AddInlineImage(new Uri("https://picsum.photos/360/202?image=1043"));
应用徽标替代
指定 appLogoOverride 的放置值将导致图像显示在视觉区域左侧的正方形中。 此属性的名称反映了早期版本的 Windows 中的行为，其中图像将替换默认应用徽标图像。 在Windows 11中，应用徽标显示在属性区域中，因此应用徽标不会被 appLogoOverride 图像放置覆盖。
图像尺寸在 100% 缩放时为 48x48 像素。 通常建议每个图标资产每个比例因子提供一个版本：100%、125%、150%、200% 和400%。
new ToastContentBuilder()
...
.AddAppLogoOverride(new Uri("https://picsum.photos/360/202?image=1043"), NotificationAppLogoCrop.Circle);
提示裁剪
Microsoft 样式指南建议使用圆形图像来表示个人资料图片，以便跨应用和 shell 提供人员一致的表示形式。 将 HintCrop 属性设置为 Circle ，以使用圆形裁剪呈现图像。
new ToastContentBuilder()
...
.AddAppLogoOverride(new Uri("https://picsum.photos/48?image=883"), NotificationAppLogoCrop.Circle);
主图
周年更新中的新增功能：Toast 可以显示一个英雄图像，这是一个特色 ToastGenericHeroImage ，在 Toast 横幅中和通知中心内突出显示。 图像尺寸在 100% 缩放时为 364x180 像素。
new ToastContentBuilder()
...
.AddHeroImage(new Uri("https://picsum.photos/364/180?image=1043"));
图像大小限制
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 上的自定义时间戳。
new ToastContentBuilder()
...
.AddCustomTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));
进度条
创意者更新的新增功能：可在 Toast 通知中提供进度栏，让用户时刻了解操作进度，例如下载进度。
若要详细了解如何使用进度栏，请参阅 Toast 进度栏。
标头
创意者更新中的新增功能：可以在通知中心内的标头下对通知进行分组。 例如，你可以将群聊中的组消息分到一个标题下，或将常见主题的通知分到一个标题下等等。
若要详细了解如何使用标题，请参阅 Toast 标题。
自适应内容
周年更新中的新增功能：除了上面指定的内容外，你还可以显示在展开 Toast 时可见的附加自适应内容。
这些附加内容是用 Adaptive 指定的，阅读自适应磁贴文档可了解更多内容。
请注意，任何自适应内容都必须包含在 AdaptiveGroup 中。 否则将不会使用自适应呈现。
列和文本元素
下面的示例使用了列和高级自适应文本元素。 由于文本元素位于 AdaptiveGroup 中，因此它们支持所有富自适应样式属性。
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 可交互，让用户无需中断其当前工作流即可就你的 Toast 通知采取快速操作。 例如，用户可以直接从 Toast 内回复邮件，甚至在不打开电子邮件应用的情况下删除电子邮件。 按钮显示在通知的扩展部分。
若要详细了解如何端到端操控按钮，请参阅发送本地 Toast。
按钮可执行以下不同操作...
- 通过可用于导航到特定页面/内容的参数在前台激活应用。
- 激活应用的后台任务以便快速回复或类似的场景。
- 通过协议启动激活另一个应用。
- 执行系统操作，如推迟或取消通知。
注意
最多只能具有 5 个按钮（包括我们稍后将讨论的关联菜单项）。
new ToastContentBuilder()
...
.AddButton(new ToastButton()
.SetContent("See more details")
.AddArgument("action", "viewDetails"))
.AddButton(new ToastButton()
.SetContent("Remind me later")
.AddArgument("action", "remindLater")
.SetBackgroundActivation());
带图标的按钮
可向按钮添加图标。 这些图标在 100% 缩放时为白色透明的 16x16 像素图像，且图像本身不应包含任何填充。 如果选择在一条 Toast 通知上提供图标，则必须为该通知中的所有按钮提供图标，因为该操作会将按钮样式转换为图标按钮。
注意
为实现辅助功能，请务必添加“白对比色”版本的图标（白色背景的黑色图标），以便用户在打开高对比度白色模式时，图标清晰可见。 有关详细信息，请参阅 Toast 辅助功能页面。
new ToastContentBuilder()
...
.AddButton(new ToastButton()
.SetContent("Dismiss")
.AddArgument("action", "dismiss")
.SetImageUri(new Uri("Assets/NotificationButtonIcons/Dismiss.png", UriKind.Relative))
.SetBackgroundActivation());
Windows 11更新中的新增功能：可以使用 XML 中的 HintToolTip 属性向图标添加工具提示。 如果你的按钮有图标但没有内容，这很理想，因为这将确保你可以传递 Windows 讲述人可以阅读的文本。 但是，如果存在内容，则无论工具提示中传递的内容，讲述人都会读取内容。
带有颜色的按钮
Windows 11更新中的新增功能：通过将 useButtonStyle 属性添加到 toast XML 元素，将 hint-buttonStyle 属性添加到操作 XML 元素，从而向按钮添加红色或绿色颜色，如下所示。
具有待更新激活的按钮
Fall Creators Update 的新增功能：在后台激活按钮上，可使用 PendingUpdate 的激活后行为在 Toast 通知中创建多步骤的交互。 用户单击按钮后，将激活后台任务，此时 Toast 处于“等待更新”状态。该状态下，屏幕上始终显示 Toast，直到后台任务将其替换为新的 Toast。
若要了解如何实现此操作，请参阅 Toast 等待更新。
关联菜单操作
周年更新中的新增功能：可以将其他上下文菜单操作添加到用户右键单击 Toast 通知或选择上下文菜单图标时显示的现有上下文菜单。
注意
在较旧的设备上，上述其他关联菜单操作仅显示为 Toast 上的正常按钮。
添加 (的其他上下文菜单操作（例如“1 小时静音群组聊天”）) 显示在两个默认系统条目上方。
生成器语法不支持上下文菜单操作，因此建议使用初始值设定项语法。
ToastContent content = new ToastContent()
{
...
Actions = new ToastActionsCustom()
{
ContextMenuItems =
{
new ToastContextMenuItem("Mute group chat for 1 hour", "action=muteId")
}
}
};
注意
其他关联菜单项计入 Toast 按钮（数量上限为 5 个）。
其他关联菜单项的激活方式与 Toast 按钮的相同。
输入
输入是在 toast 的 toast 区域的 actions 区域中指定的，这表示它们仅在 toast 展开时可见。
快速回复文本框
要启用快速回复文本框（例如，在消息应用程序中），请添加文本输入和按钮，并引用文本输入字段的 ID，以便按钮显示在输入字段旁边。 按钮的可选图标（如果提供）应为 32x32 像素图像，没有填充、白色像素设置为透明和 100% 缩放。
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")
.SetBackgroundActivation());
使用按钮栏的输入
还可使用一个（或多个）输入，在输入下方显示正常按钮。
new ToastContentBuilder()
...
.AddInputTextBox("tbReply", "Type a reply")
.AddButton(new ToastButton()
.SetContent("Reply")
.AddArgument("action", "reply")
.SetBackgroundActivation())
.AddButton(new ToastButton()
.SetContent("Video call")
.AddArgument("action", "videoCall"));
选择输入
除文本框外，还可使用选择菜单。
new ToastContentBuilder()
...
.AddToastInput(new ToastSelectionBox("time")
{
DefaultSelectionBoxItemId = "lunch",
Items =
{
new ToastSelectionBoxItem("breakfast", "Breakfast"),
new ToastSelectionBoxItem("lunch", "Lunch"),
new ToastSelectionBoxItem("dinner", "Dinner")
}
})
.AddButton(...)
.AddButton(...);
推迟/消除
使用一个选择菜单和两个按钮，可创建利用系统推迟和消除操作的提醒通知。 请确保将方案设置为“提醒”以便通知像提醒那样工作。
！[Toast 的屏幕截图，其中包含描述会议时间和位置的文本行。 选择框已选中“15 分钟”，并且有标记为“暂停和关闭”的按钮。 (图像/toast-content-snooze-dismiss.png) 我们使用 toast 按钮的 SelectionBoxId 属性将“推迟”按钮链接到选择菜单输入。
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());
若要使用系统推迟和消除操作：
- 指定 ToastButtonSnooze 或 ToastButtonDismiss
- （可选）指定一个自定义内容字符串：
- 如果你不提供字符串，我们将自动使用“推迟”和“消除”的本地化字符串。
- 选择指定 SelectionBoxId：
- 如果你不希望用户选择推迟间隔，而只是希望你的通知仅在系统定义的时间间隔内推迟一次（这在整个操作系统上都一致），则不要构建任何 <input>。
- 如果你希望提供推迟间隔选择：
- 在推迟操作中指定 SelectionBoxId
- 将输入的 ID 与推迟操作的 SelectionBoxId 匹配
- 将 ToastSelectionBoxItem 的值指定为一个以分钟为单位表示推迟间隔的 nonNegativeInteger。
音频
移动始终支持自定义音频，在桌面版本 1511 (内部版本 10586) 或更高版本中受支持。 可通过以下路径引用自定义音频：
- ms-appx:///
- ms-appdata:///
或者，你可以从 ms winsoundevents 列表中选择，它始终在两种平台上受支持。
若要了解 toast 通知中的音频，请参阅音频架构页面。 若要了解如何使用自定义音频发送 toast，请参阅 toast 中的自定义音频。
方案
若要创建重要通知、警报、提醒和传入呼叫通知，只需使用分配有 方案 值的普通 Toast 通知。 此方案调整了一些行为，以创建一致的统一用户体验。 有四个可能 的方案 值：
- 提示
- 警报
- IncomingCall
- 紧急
提醒
在提醒方案中，通知将保留在屏幕上，直到用户将其关闭或执行操作。 在 Windows 移动版上，该 Toast 还会以预先展开的形式显示。 将播放提醒声音。 必须在 Toast 通知上提供至少一个按钮。 否则，该 Toast 将被视为正常 Toast。
警报
警报的行为与提醒相同，但警报将额外循环使用默认警报声音的音频。 必须在 Toast 通知上提供至少一个按钮。 否则，该 Toast 将被视为正常 Toast。
传入调用
传入呼叫通知以特殊呼叫格式预展开，并停留在用户的屏幕上，直到关闭。 默认情况下，铃声音频将循环。 在 Windows Mobile 设备上，它们全屏显示。
重要通知
重要
要求：必须运行Windows Insider Preview内部版本 22546 或更高版本才能使用重要通知。
重要通知允许用户更好地控制第一方和第三方应用可以向其发送高优先级 Toast 通知 (紧急/重要) ，这些通知可以突破焦点辅助 (请勿打扰) 。 这可以在通知设置中修改。
本地化和辅助功能
磁贴和 toast 可加载为显示语言、显示比例系数、高对比度和其他运行时上下文定制的字符串和图像。 有关详细信息，请参阅磁贴和 toast 通知的语言、比例和高对比度支持。
处理激活
要了解如何处理 Toast 激活（用户单击你的 Toast 或 Toast 上的按钮），请参阅发送本地 Toast。