Toast 内容架构

  • 项目

以下内容介绍了 Toast 内容中的所有属性和元素。

如果希望使用原始 XML 而非通知库，请参阅 XML 架构。

ToastContent

ToastContent

ToastContent 是描述通知内容（包括视觉、操作和音频）的顶级对象。

properties 类型 必需 说明
Launch string false Toast 激活应用程序时传递给应用程序的字符串。 此字符串的格式和内容由应用自行定义，供其自己使用。 当用户点击或单击 Toast 以启动其关联的应用时，启动字符串会向应用提供上下文，该上下文使应用能够向用户显示与 Toast 内容相关的视图，而不是以默认方式启动。
视觉对象 ToastVisual true 描述 Toast 通知的视觉部分。
操作 IToastActions false （可选）使用按钮和输入创建自定义操作。
音频 ToastAudio false 描述 Toast 通知的音频部分。
ActivationType ToastActivationType false 指定当用户单击此 Toast 正文时将使用的激活类型。
ActivationOptions ToastActivationOptions false 创意者更新中的新增功能：有关激活 Toast 通知的其他选项。
方案 ToastScenario false 声明 Toast 的使用场景，例如警报或提醒。
DisplayTimestamp DateTimeOffset? false 创意者更新中的新增功能：使用自定义时间戳替代默认时间戳，该时间戳表示实际传递通知内容的时间，而不是 Windows 平台接收通知的时间。
页眉 ToastHeader false 创意者更新中的新增功能：将自定义标头添加到通知，以在操作中心内将多个通知组合在一起。

ToastScenario

指定 Toast 表示的场景。

值 含义
默认值 正常的 Toast 行为。
Reminder 提醒通知。 提醒通知将预展开显示，并保留在用户的屏幕上，直到关闭。
Alarm 警报通知。 提醒通知将预展开显示，并保留在用户的屏幕上，直到关闭。 默认情况下，音频将循环，并将使用警报音频。
IncomingCall 来电通知。 来电通知将以特殊呼叫格式预展开显示，并停留在用户的屏幕上，直到关闭。 默认情况下，音频将循环，并使用铃声音频。

ToastVisual

Toast 的视觉部分包含绑定，其中包含文本、图像、自适应内容等。

properties 类型 必需 说明
BindingGeneric ToastBindingGeneric true 可在所有设备上呈现的通用 Toast 绑定。 此绑定是必需的，不能为 null。
BaseUri Uri false 与图像源属性中的相对 URL 结合的默认基本 URL。
AddImageQuery bool? false 设置为“true”将使 Windows 能够将查询字符串附加到在 toast 通知中提供的图像 URL。 如果你的服务器托管图像并且可以处理查询字符串，则可通过基于查询字符串搜索图像变量，或通过忽略查询字符串并且不带查询字符串按指定方式返回图像，来使用此特性。 此查询字符串指定缩放倍数、对比度设置和语言；例如，通知中提供的“www.website.com/images/hello.png”值将变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”
语言 字符串 false 使用本地化资源时视觉负载的目标区域设置，用 BCP-47 语言标签指定，如“en-US”或“fr-FR”。 此区域设置将用绑定或文本中指定的任何区域设置覆盖。 如果未提供，则将使用系统区域设置。

ToastBindingGeneric

泛型绑定是 Toast 的默认绑定，用于指定文本、图像、自适应内容等。

properties 类型 必需 说明
Children IList<IToastBindingGenericChild> false Toast 正文的内容，可以包括文本、图像和组（在周年更新中添加）。 文本元素必须位于任何其他元素之前，并且仅支持 3 个文本元素。 如果文本元素放置在任何其他元素之后，则会将其拉到顶部或删除。 最后，根子文本元素上不支持某些文本属性（如 HintStyle），这些属性仅在 AdaptiveSubgroup 中有效。 如果在没有周年更新的设备上使用 AdaptiveGroup，则只会删除组内容。
AppLogoOverride ToastGenericAppLogo false 用于替代应用徽标的可选徽标。
HeroImage ToastGenericHeroImage false 在 Toast 和操作中心内显示的可选特色“hero”图像。
Attribution ToastGenericAttributionText false 可选属性文本，该文本将显示在 Toast 通知的底部。
BaseUri Uri false 与图像源属性中的相对 URL 结合的默认基本 URL。
AddImageQuery bool? false 设置为“true”将使 Windows 能够将查询字符串附加到在 toast 通知中提供的图像 URL。 如果你的服务器托管图像并且可以处理查询字符串，则可通过基于查询字符串搜索图像变量，或通过忽略查询字符串并且不带查询字符串按指定方式返回图像，来使用此特性。 此查询字符串指定缩放倍数、对比度设置和语言；例如，通知中提供的“www.website.com/images/hello.png”值将变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”
语言 字符串 false 使用本地化资源时视觉负载的目标区域设置，用 BCP-47 语言标签指定，如“en-US”或“fr-FR”。 此区域设置将用绑定或文本中指定的任何区域设置覆盖。 如果未提供，则将使用系统区域设置。

IToastBindingGenericChild

Toast 子元素的标记接口，其中包括文本、图像、组等。

实现形式
AdaptiveText
AdaptiveImage
AdaptiveGroup
AdaptiveProgressBar

AdaptiveText

自适应文本元素。 如果将其放置在顶级 ToastBindingGeneric.Children 中，将仅应用 HintMaxLines。 但是，如果将其作为组/子组的子组放置，则支持全文本样式。

properties 类型 必需 说明
文本 字符串或 BindableString false 要显示的文本。 在创意者更新中添加的数据绑定支持，但仅适用于顶级文本元素。
HintStyle AdaptiveTextStyle false 样式控制文本的字体大小、粗细和不透明度。 仅适用于组/子组中的文本元素。
HintWrap bool? false 将其设置为 true 可启用文本换行。 顶级文本元素忽略此属性并始终换行（可以使用 HintMaxLines = 1 禁用顶级文本元素的换行）。 组/子组中的文本元素默认情况下不进行换行。
HintMaxLines int? false 对文本元素允许显示的最大行数。
HintMinLines int? false 文本元素必须显示的最小行数。 仅适用于组/子组中的文本元素。
HintAlign AdaptiveTextAlign false 文本的水平对齐方式。 仅适用于组/子组中的文本元素。
语言 字符串 false XML 负载的目标区域设置，以 BCP-47 语言标记指定，如“en-US”或“fr-FR”。 此处指定的区域设置会覆盖其他指定的任何区域设置，如绑定或视觉中指定的设置。 如果此值为文字字符串，则此属性默认为用户的用户界面语言。 如果此值为字符串参考，则此属性默认为解析字符串时由 Windows 运行时选择的区域设置。

BindableString

字符串的绑定值。

properties 类型 必需 说明
BindingName string true 获取或设置映射到绑定数据值的名称。

AdaptiveTextStyle

文本样式控制字体大小、粗细和不透明度。 精细不透明度是 60% 不透明。

Value 含义
默认 默认值。 样式由呈现器确定。
Caption 小于段落字体大小。
CaptionSubtle 与 Caption 相同，但具有精细不透明度。
正文 段落字体大小。
BodySubtle 与 Body 相同，但具有精细不透明度。
Base 段落字体大小、粗体。 本质上是正文的粗体版本。
BaseSubtle 与 Base 相同，但具有精细不透明度。
Subtitle H4 字体大小。
SubtitleSubtle 与 Subtitle 相同，但具有精细的不透明度。
标题 H3 字体大小。
TitleSubtle 与 Title 相同，但具有精细不透明度。
TitleNumeral 与 Title 相同，但去掉了上/下边距。
Subheader H2 字体大小。
SubheaderSubtle 与 Subheader 相同，但具有精细不透明度。
SubheaderNumeral 与 Subheader 相同，但去掉了上/下边距。
标头 H1 字体大小。
HeaderSubtle 与 Header 相同，但具有精细不透明度。
HeaderNumeral 与 Header 相同，但去掉了上/下边距。

AdaptiveTextAlign

控制文本的水平对齐。

Value 含义
默认 默认值。 对齐方式由呈现器自动确定。
Auto 对齐方式由当前的语言和文化确定。
Left 在水平方向将文本向左对齐。
Center 在水平方向将文本中心对齐。
Right 在水平方向将文本向右对齐。

AdaptiveImage

内联图像。

属性 类型 必需 说明
Source 字符串 true 图像的 URL。 支持 ms-appx、ms-appdata 和 http。 自 Fall Creators Update 起，正常连接上的 Web 图像的大小限制提升至 3 MB，按流量计费的连接上的限制提升至 1 MB。 在尚未运行 Fall Creators Update 的设备上，Web 图像的大小不得超过 200 KB。
HintCrop AdaptiveImageCrop false 周年更新中的新增功能：控制图像的所需裁剪。
HintRemoveMargin bool? false 默认情况下，组/子组内的图像周围有 8 像素的边距。 你可以将此属性设置为 true 去掉此边距。
HintAlign AdaptiveImageAlign false 水平方向上图像的对齐方式。 仅适用于组/子组中的图像。
AlternateText 字符串 false 描述图像的替换文本，用于辅助功能。
AddImageQuery bool? false 设置为“true”将使 Windows 能够将查询字符串附加到在 toast 通知中提供的图像 URL。 如果你的服务器托管图像并且可以处理查询字符串，则可通过基于查询字符串搜索图像变量，或通过忽略查询字符串并且不带查询字符串按指定方式返回图像，来使用此特性。 此查询字符串指定缩放倍数、对比度设置和语言；例如，通知中提供的“www.website.com/images/hello.png”值将变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”

AdaptiveImageCrop

指定所需的图像裁剪。

Value 含义
默认 默认值。 由呈现器确定的裁剪行为。
无 不裁剪图像。
圆形 将图像裁剪为圆形。

AdaptiveImageAlign

指定图像在水平方向上的对齐方式。

Value 含义
默认 默认值。 由渲染器确定的对齐行为。
拉伸 图像拉伸以填充可用宽度（根据图像的位置，可能还要填充可用高度）。
Left 向左对齐图像，并用其原始分辨率显示图像。
Center 在水平方向上中心对齐图像，并用其原始分辨率显示图像。
Right 向右对齐图像，并用其原始分辨率显示图像。

AdaptiveGroup

周年更新中的新增功能：组从语义上确定组中内容是必须作为整体显示，还是无法容纳就不显示。 组还允许创建多个列。

属性 类型 必需 说明
Children IList<AdaptiveSubgroup> false 子组显示为垂直列。 你必须使用子组来提供 AdaptiveGroup 内的任何内容。

AdaptiveSubgroup

周年更新中的新增功能：子组是可能包含文本和图像的垂直列。

properties 类型 必需 说明
Children IList<IAdaptiveSubgroupChild> false AdaptiveText 和 AdaptiveImage 是子组的有效子级。
HintWeight int? false 通过指定粗细控制此子组列相对于其他子组的宽度。
HintTextStacking AdaptiveSubgroupTextStacking false 控制此子组内容在垂直方向上的对齐方式。

IAdaptiveSubgroupChild

子组子级的标记界面。

实现形式
AdaptiveText
AdaptiveImage

AdaptiveSubgroupTextStacking

TextStacking 指定内容在垂直方向上的对齐方式。

Value 含义
默认 默认值。 渲染器将自动选择默认的垂直对齐方式。
顶部 垂直方向上向顶部对齐。
Center 垂直方向上向中心对齐。
下 垂直方向上向底部对齐。

AdaptiveProgressBar

创意者更新中的新增功能：进度栏。 仅在桌面版、15063 版或更高版本系统上的 Toast 上受支持。

properties 类型 必需 Description
标题 字符串或 BindableString false 获取或设置可选的标题字符串。 支持数据绑定。
值 double 或 AdaptiveProgressBarValue 或 BindableProgressBarValue false 获取或设置进度栏的值。 支持数据绑定。 默认值为 0。
ValueStringOverride 字符串或 BindableString false 获取或设置要显示的可选字符串，而不是默认的百分比字符串。 如果未提供此项，将显示类似于“70%”的内容。
Status 字符串或 BindableString true 获取或设置状态字符串（必需），该字符串显示在左侧进度栏下方。 此字符串应反映操作的状态，例如“正在下载...”或“正在安装...”

AdaptiveProgressBarValue

表示进度栏值的类。

properties 类型 必需 Description
值 double false 获取或设置表示完成百分比的值 (0.0 - 1.0)。
IsIndeterminate bool false 获取或设置一个值，该值指示进度栏是否不确定。 如果为 true，则该值将被忽略。

BindableProgressBarValue

可绑定进度栏值。

properties 类型 必需 说明
BindingName string true 获取或设置映射到绑定数据值的名称。

要显示的徽标，而不是应用徽标。

properties 类型 必需 说明
Source 字符串 true 图像的 URL。 支持 ms-appx、ms-appdata 和 http。 Http 图像大小必须为 200 KB 或更小。
HintCrop ToastGenericAppLogoCrop false 指定要如何裁剪图像。
AlternateText 字符串 false 描述图像的替换文本，用于辅助功能。
AddImageQuery bool? false 设置为“true”将使 Windows 能够将查询字符串附加到在 toast 通知中提供的图像 URL。 如果你的服务器托管图像并且可以处理查询字符串，则可通过基于查询字符串搜索图像变量，或通过忽略查询字符串并且不带查询字符串按指定方式返回图像，来使用此特性。 此查询字符串指定缩放倍数、对比度设置和语言；例如，通知中提供的“www.website.com/images/hello.png”值将变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”

ToastGenericAppLogoCrop

控制应用徽标图像的裁剪。

值 含义
默认 裁剪使用渲染器的默认行为。
无 图像不裁剪，显示为方形。
圆形 将图像裁剪为圆形。

ToastGenericHeroImage

在 Toast 和操作中心内显示的特色“hero”图像。

properties 类型 必需 说明
Source 字符串 true 图像的 URL。 支持 ms-appx、ms-appdata 和 http。 Http 图像大小必须为 200 KB 或更小。
AlternateText 字符串 false 描述图像的替换文本，用于辅助功能。
AddImageQuery bool? false 设置为“true”将使 Windows 能够将查询字符串附加到在 toast 通知中提供的图像 URL。 如果你的服务器托管图像并且可以处理查询字符串，则可通过基于查询字符串搜索图像变量，或通过忽略查询字符串并且不带查询字符串按指定方式返回图像，来使用此特性。 此查询字符串指定缩放倍数、对比度设置和语言；例如，通知中提供的“www.website.com/images/hello.png”值将变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”

ToastGenericAttributionText

Toast 通知底部显示的属性文本。

properties 类型 必需 说明
文本 string true 要显示的文本。
语言 字符串 false 使用本地化资源时视觉负载的目标区域设置，用 BCP-47 语言标签指定，如“en-US”或“fr-FR”。 如果未提供，则将使用系统区域设置。

IToastActions

Toast 操作/输入的标记接口。

实现形式
ToastActionsCustom
ToastActionsSnoozeAndDismiss

ToastActionsCustom

实现 IToastActions

使用按钮、文本框和选择输入等控件创建自己的自定义操作和输入。

properties 类型 必需 说明
输入 IList<IToastInput> false 文本框和选择输入等输入。 最多允许 5 个输入。
Buttons IList<IToastButton> false 按钮在所有输入之后显示（如果按钮用作快速回复按钮，则与输入相邻）。 最多允许 5 个按钮（如果还具有上下文菜单项，允许的按钮将更少）。
ContextMenuItems IList<ToastContextMenuItem> false 周年更新中的新增功能：自定义上下文菜单项，在用户右键单击通知时提供其他操作。 最多只能有 5 个按钮和上下文菜单项 组合在一起。

IToastInput

Toast 输入的标记接口。

实现形式
ToastTextBox
ToastSelectionBox

ToastTextBox

实现 IToastInput

TextBox 控件，用户可在其中键入文本。

properties 类型 必需 描述
Id string true ID 是必需的，用于将用户输入的文本映射到应用稍后使用的 ID/值的键值对。
标题 string false 要显示在文本框上方的标题文本。
PlaceholderContent string false 当用户尚未键入任何文本时，要显示在文本框中的占位符文本。
DefaultInput string false 要放置在文本框中的初始文本。 对于空白文本框，该字段值为 null。

ToastSelectionBox

实现 IToastInput

选择框控件，使用户能够从选项下拉列表中进行选择。

properties 类型 必需 描述
Id string true ID 是必需的。 如果用户选择了此项，则此 ID 将传回应用的代码，表示他们作出的选择。
内容 string true 内容是必需的，它是显示在选择项上的字符串。

ToastSelectionBoxItem

选择框项（用户可以从下拉列表中选择的项）。

properties 类型 必需 描述
Id string true ID 是必需的，用于将用户输入的文本映射到应用稍后使用的 ID/值的键值对。
标题 string false 要显示在选择框上方的标题文本。
DefaultSelectionBoxItemId string false 这会控制默认情况下选择哪个项，并引用 ToastSelectionBoxItem 的 Id 属性。 如果未提供此项，则默认选择将为空（用户看不到任何内容）。
物品 IList<ToastSelectionBoxItem> false 用户可以在此 SelectionBox 中选择的选择项。 只能添加 5 项。

IToastButton

Toast 按钮的标记接口。

实现形式
ToastButton
ToastButtonSnooze
ToastButtonDismiss

ToastButton

实现 IToastButton

用户可单击的按钮。

properties 类型 必需 说明
内容 string true 必需。 要在按钮上显示的文本。
参数 string true 必需。 当用户单击此按钮时，应用稍后将收到的应用定义的参数字符串。
ActivationType ToastActivationType false 控制单击时此按钮将使用的激活类型。 默认为前台。
ActivationOptions ToastActivationOptions false 创意者更新中的新增功能：获取或设置与 Toast 按钮激活相关的其他选项。

ToastActivationType

确定用户与特定操作交互时将使用的激活类型。

值 含义
前景 默认值。 前台应用已启动。
Background 将触发对应的后台任务（假设已设置所有内容），并且可以在后台中执行代码（例如发送用户的快速回复消息），而不会中断用户。
协议 使用协议激活启动其他应用。

ToastActivationOptions

创意者更新中的新增功能：与激活相关的其他选项。

properties 类型 必需 说明
AfterActivationBehavior ToastAfterActivationBehavior false 创意者更新秋季版中的新增功能：获取或设置在用户调用此操作时 Toast 应使用的行为。 这仅适用于桌面版上的 ToastButton 和 ToastContextMenuItem。
ProtocolActivationTargetApplicationPfn string false 如果使用 ToastActivationType.Protocol，可以选择指定目标 PFN，以便无论是否注册多个应用以处理同一协议 URI，都将始终启动所需的应用。

ToastAfterActivationBehavior

指定在用户对 Toast 执行操作时 Toast 应使用的行为。

值 含义
默认值 默认行为。 当用户对 Toast 执行操作时，将关闭 Toast。
PendingUpdate 用户单击 Toast 上的按钮后，通知将持续显示，但处于“挂起更新”视觉状态。 应立即从后台任务更新 Toast，这样用户就不会看到此“挂起更新”视觉状态太长时间。

ToastButtonSnooze

实现 IToastButton

系统处理的暂停按钮，用于自动处理通知的暂停。

properties 类型 必需 说明
CustomContent string false 按钮上显示的可选自定义文本，用于替代默认本地化的“暂停”文本。

ToastButtonDismiss

实现 IToastButton

系统处理的关闭按钮，在单击后将关闭通知。

properties 类型 必需 说明
CustomContent string false 按钮上显示的可选自定义文本，用于替代默认本地化的“关闭”文本。

ToastActionsSnoozeAndDismiss

*实现 IToastActions

自动为暂停间隔构造选择框，并自动构造暂停/消除按钮，选择框与按钮已全部自动本地化，并且系统会自动处理暂停逻辑。

properties 类型 必需 说明
ContextMenuItems IList<ToastContextMenuItem> false 周年更新中的新增功能：自定义上下文菜单项，在用户右键单击通知时提供其他操作。 最多只能有 5 项。

ToastContextMenuItem

上下文菜单项条目。

properties 类型 必需 说明
内容 string true 必需。 要显示的文本。
参数 string true 必需。 应用定义的参数字符串，当用户单击菜单项时，如果该参数被激活，应用稍后可以获取该参数。
ActivationType ToastActivationType false 控制单击时此菜单项将使用的激活类型。 默认为前台。
ActivationOptions ToastActivationOptions false 创意者更新中的新增功能：与激活 Toast 上下文菜单项相关的其他选项。

ToastAudio

指定要在收到 Toast 通知时播放的音频。

properties 类型 必需 说明
Src uri false 要播放的媒体文件，用于代替默认声音。 仅支持 ms-appx 和 ms-resource。 其他所有内容（ms-appdata、http、C: 等）都不受支持。
Loop boolean false 如果在只要显示 Toast 时就重复播放声音，则设置为 true，如果只播放一次声音，则设置为 false（默认值）。
静音 boolean false 如果要将声音设为静音，则设置为 true；如果允许播放 Toast 通知声音，则设置为 false（默认值）。

ToastHeader

创意者更新中的新增功能：在操作中心内将多个通知组合在一起的自定义标头。

properties 类型 必需 描述
Id string true 开发人员创建的标识符，用于唯一标识此标头。 如果两个通知具有相同的标头 ID，它们将显示在操作中心中的同一标头下。
标题 string true 标头的标题。
参数 string true 获取或设置开发人员定义的参数字符串，该参数在用户单击此标头时返回到应用。 不可为 null。
ActivationType ToastActivationType false 获取或设置单击时此标头将使用的激活类型。 默认为前台。 请注意，仅支持前台和协议。
ActivationOptions ToastActivationOptions false 获取或设置与 Toast 标头激活相关的其他选项。