通过

Toast 内容架构

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

如果宁愿使用原始 XML 而不是 通知库，请参阅 XML 架构。

ToastContent

ToastContent

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

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

ToastScenario

指定 Toast 表示的场景。

Value Meaning
Default 正常的 Toast 行为。
Reminder 提醒通知。 这将显示预先展开，并保留在用户的屏幕上，直到关闭。
Alarm 警报通知。 这将显示预先展开，并保留在用户的屏幕上，直到关闭。 默认情况下，音频将循环，并使用警报音频。
IncomingCall 来电通知。 这将以特殊弹窗格式预先展开显示，并保持在用户的屏幕上，直到关闭。 默认情况下，音频将自动循环，并使用铃声作为音频。

ToastVisual

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

Property 类型 Required Description
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”
Language 字符串 false 使用本地化资源时视觉有效负载的目标区域设置，指定为 BCP-47 语言标记，例如“en-US”或“fr-FR”。 此语言环境被绑定或文本中指定的任何语言环境覆盖。 如果未提供，将改用系统区域设置。

ToastBindingGeneric

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

Property 类型 Required Description
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”
Language 字符串 false 使用本地化资源时视觉有效负载的目标区域设置，指定为 BCP-47 语言标记，例如“en-US”或“fr-FR”。 此语言环境被绑定或文本中指定的任何语言环境覆盖。 如果未提供，将改用系统区域设置。

IToastBindingGenericChild

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

Implementations
AdaptiveText
AdaptiveImage
AdaptiveGroup
AdaptiveProgressBar

AdaptiveText

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

Property 类型 Required Description
Text 字符串 或 BindableString false 要显示的文本。 在 Creators Update 中添加的数据绑定支持，但仅适用于顶级文本元素。
HintStyle AdaptiveTextStyle false 样式控制文本的字号、粗细和不透明度。 仅适用于组/子组中的文本元素。
HintWrap bool? false 将此设置为 true 以启用文本换行。 顶级文本元素忽略此属性并始终换行（可以使用 HintMaxLines = 1 禁用顶级文本元素的换行）。 组/子组中的文本元素默认为 false 进行换行。
HintMaxLines int? false 允许文本元素显示的最大行数。
HintMinLines int? false 文本元素必须显示的最小行数。 仅适用于组/子组中的文本元素。
HintAlign AdaptiveTextAlign false 文本的水平对齐方式。 仅适用于组/子组中的文本元素。
Language 字符串 false XML 负载的目标区域设置，指定为 BCP-47 语言标记，例如“en-US”或“fr-FR”。 此处指定的区域设置将替代任何其他指定区域设置，例如绑定或视觉对象中的区域设置。 如果此值是文本字符串，则此属性默认为用户的 UI 语言。 如果此值是字符串引用，则此属性默认为 Windows 运行时在解析字符串时选择的区域设置。

BindableString

字符串的绑定值。

Property 类型 Required Description
BindingName 字符串 true 获取或设置映射到绑定数据值的名称。

AdaptiveTextStyle

文本样式控制字号、粗细和不透明度。 细微的不透明度为 60% 不透明。

Value Meaning
Default Default value. 样式由呈现器确定。
Caption 小于段落字体大小。
CaptionSubtle 与 Caption 相同，但具有微妙的不透明度。
Body 段落字号。
BodySubtle 与身体相同，但具有微妙的不透明度。
Base 段落字体大小，加粗。 实质上是正文的粗体版本。
BaseSubtle 与 Base 相同，但具有微妙的不透明度。
Subtitle H4 字号。
SubtitleSubtle 与副标题相同，但具有微妙的不透明度。
Title H3 标题字号。
TitleSubtle 与标题相同，但具有微妙的不透明度。
TitleNumeral 与标题相同，但删除了顶部/底部填充。
Subheader H2 字号。
SubheaderSubtle 与子标题相同，但具有微妙的不透明度。
SubheaderNumeral 与子标题相同，但删除了顶部/底部填充。
Header H1 字号。
HeaderSubtle 与标题相同，但具有轻微的不透明度。
HeaderNumeral 与标题相同，但去除了上下的边距。

AdaptiveTextAlign

控制文本的水平对齐方式。

Value Meaning
Default Default value. 对齐由呈现器自动确定。
Auto 对齐方式由当前语言和文化决定。
Left 将文本水平左对齐。
Center 将文本水平居中对齐。
Right 将文本水平对齐到右侧。

AdaptiveImage

嵌入图像

Property 类型 Required Description
Source 字符串 true 图像的网址。 支持 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 默认情况下，组/子组中的图像周围有 8px 的边距。 可以通过将此属性设置为 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 Meaning
Default Default value. 由呈现器确定的裁剪行为。
None 图像未裁剪。
Circle 图像裁剪为圆形。

AdaptiveImageAlign

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

Value Meaning
Default Default value. 由呈现器确定的对齐行为。
Stretch 图像拉伸以填充可用的宽度（以及可能可用的高度，具体取决于图像的放置位置）。
Left 将图像左对齐，按原始分辨率显示图像。
Center 水平对齐中心中的图像，以本机分辨率显示图像。
Right 将图像右对齐，以原始分辨率显示图像。

AdaptiveGroup

周年更新中的新增功能：组在语义上标识组中的内容必须显示为整体，或者如果不能容纳，则不显示。 组还允许创建多个列。

Property 类型 Required Description
Children IList<自适应子组> false 子组显示为垂直列。 必须使用子组来提供 AdaptiveGroup 中的任何内容。

AdaptiveSubgroup

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

Property 类型 Required Description
Children IList<IAdaptiveSubgroupChild> false AdaptiveText 和 AdaptiveImage 是子组的有效子级。
HintWeight int? false 通过指定相对于其他子组的权重来控制此子组列的宽度。
HintTextStacking AdaptiveSubgroupTextStacking false 控制此子组内容的垂直对齐方式。

IAdaptiveSubgroupChild

子组子组的标记接口。

Implementations
AdaptiveText
AdaptiveImage

AdaptiveSubgroupTextStacking

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

Value Meaning
Default Default value. 呈现器会自动选择默认的垂直对齐方式。
Top 垂直对齐至顶部。
Center 垂直对齐到中心。
Bottom 垂直对齐到底部。

AdaptiveProgressBar

创作者更新中的新增功能：进度条。 仅在桌面版 15063 或更高版本的 Toast 上受支持。

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

AdaptiveProgressBarValue

一个表示进度栏值的类。

Property 类型 Required Description
Value double false 获取或设置表示完成百分比的值（0.0 - 1.0）。
IsIndeterminate bool false 获取或设置一个值，该值指示进度栏是否不确定。 如果这是真的，将忽略 值。

BindableProgressBarValue

可绑定进度条值。

Property 类型 Required Description
BindingName 字符串 true 获取或设置映射到绑定数据值的名称。

显示的徽标将替代应用程序的徽标。

Property 类型 Required Description
Source 字符串 true 图像的网址。 支持 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

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

Value Meaning
Default 裁剪使用呈现器的默认行为。
None 图像未裁剪，显示正方形。
Circle 图像裁剪为圆圈。

ToastGenericHeroImage

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

Property 类型 Required Description
Source 字符串 true 图像的网址。 支持 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 通知底部显示的属性文本。

Property 类型 Required Description
Text 字符串 true 要显示的文本。
Language 字符串 false 使用本地化资源时视觉有效负载的目标区域设置，指定为 BCP-47 语言标记，例如“en-US”或“fr-FR”。 如果未提供，将改用系统区域设置。

IToastActions

Toast 操作/输入标记接口。

Implementations
ToastActionsCustom
ToastActionsSnoozeAndDismiss

ToastActionsCustom

Implements IToastActions

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

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

IToastInput

用于 Toast 输入的标记接口。

Implementations
ToastTextBox
ToastSelectionBox

ToastTextBox

Implements IToastInput

用户可以键入文本的文本框控件。

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

ToastSelectionBox

Implements IToastInput

选择框控件，允许用户从选项下拉列表中进行选择。

Property 类型 Required Description
Id 字符串 true ID 是必需的。 如果用户选择了此项，则此 ID 将传回应用的代码，表示他们的选择。
Content 字符串 true 内容是必需的，它是显示在选择项上的一个字符串。

ToastSelectionBoxItem

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

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

IToastButton

Toast 按钮的标记接口。

Implementations
ToastButton
ToastButtonSnooze
ToastButtonDismiss

ToastButton

Implements IToastButton

用户可以单击的按钮。

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

ToastActivationType

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

Value Meaning
Foreground Default value. 前台应用已启动。
Background 假设已设置好所有内容，相应的后台任务会被触发，您可以在后台执行代码，例如发送用户的快速回复消息，而不会中断用户。
Protocol 使用协议激活启动其他应用。

ToastActivationOptions

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

Property 类型 Required Description
AfterActivationBehavior ToastAfterActivationBehavior false Fall Creators Update 中的新增功能：获取或设置 Toast 在用户调用此操作时应使用的行为。 这仅适用于台式机，ToastButton 和 ToastContextMenuItem。
ProtocolActivationTargetApplicationPfn 字符串 false 如果使用 ToastActivationType.Protocol，您可以选择指定目标 PFN，这样即使有多个应用程序注册处理同一协议的 URI，也始终会启动您所需的应用程序。

ToastAfterActivationBehavior

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

Value Meaning
Default Default behavior. 当用户对 Toast 执行操作时，将消除 Toast。
PendingUpdate 用户单击 Toast 上的按钮后，通知将保持“挂起更新”视觉状态。 如要避免用户长时间看到此“挂起的更新”视觉状态，您应该立刻从后台任务中更新Toast通知。

ToastButtonSnooze

Implements IToastButton

系统自动管理通知延迟的按钮。

Property 类型 Required Description
CustomContent 字符串 false 可选的自定义文本显示在按钮上，用于替代默认的本地化“暂停”文本。

ToastButtonDismiss

Implements IToastButton

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

Property 类型 Required Description
CustomContent 字符串 false 在按钮上显示的可选自定义文本，覆盖默认的本地化“关闭”文本。

ToastActionsSnoozeAndDismiss

*Implements IToastActions

自动为设定推迟间隔构建选择框，并提供推迟/取消按钮，所有这些组件均自动实现本地化，系统会自动处理推迟逻辑。

Property 类型 Required Description
ContextMenuItems IList<ToastContextMenuItem> false 周年更新中的新增功能：自定义上下文菜单项，如果用户右键单击通知，则提供其他操作。 最多只能有 5 个项目。

ToastContextMenuItem

上下文菜单项条目。

Property 类型 Required Description
Content 字符串 true Required. 要显示的文本。
Arguments 字符串 true Required. 应用定义的参数字符串，一旦用户单击菜单项并激活应用，应用可以稍后检索该字符串。
ActivationType ToastActivationType false 控制单击时此菜单项将使用的激活类型。 默认为前台。
ActivationOptions ToastActivationOptions false 创作者更新中的新功能：与激活 Toast 上下文菜单项相关的其他选项。

ToastAudio

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

Property 类型 Required Description
Src uri false 要播放的媒体文件代替默认声音。 仅支持 ms-appx 和 ms-resource。 其他所有（ms-appdata、http、C：等）都不受支持。
Loop boolean false 如果在显示 Toast 时声音应重复，则设置为 true。设置为 false 则仅播放一次（默认值）。
Silent boolean false 将 true 设为静音；将 false 设为允许播放 Toast 通知声音（默认）。

ToastHeader

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

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