通过


应用通知内容架构

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

如果宁愿使用原始 XML 而不是Windows 应用 SDK生成器 API,请参阅 XML 架构

ToastContent

ToastContent

ToastContent 是描述通知内容(包括视觉元素、动作和音频)的顶层对象。

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

ToastScenario

指定 Toast 表示的场景。

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

ToastVisual

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

财产 类型 必需 说明
BindingGeneric ToastBindingGeneric 可以在所有设备上渲染的通用 Toast 绑定。 此绑定是必需的,不能为 null。
BaseUri Uri 用于与图像源属性中的相对 URL 配合使用的默认基本 URL。
AddImageQuery bool? 设置为“true”以允许Windows将查询字符串追加到应用通知中提供的图像 URL。 如果您的服务器托管图像,并可以通过查询字符串检索图像变体,或者可以忽略查询字符串直接返回指定的图像,请使用此属性。 此查询字符串指定缩放、对比度设置和语言;例如,通知中给定的“www.website.com/images/hello.png”值变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”
语言 字符串 使用本地化资源时视觉有效负载的目标区域设置,指定为 BCP-47 语言标记,例如“en-US”或“fr-FR”。 此语言环境被绑定或文本中指定的任何语言环境覆盖。 如果未提供,将改用系统区域设置。

ToastBindingGeneric

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

财产 类型 必需 说明
儿童 IList<IToastBindingGenericChild> Toast 正文的内容,可以包括文本、图像和组。 文本元素必须位于任何其他元素之前,并且仅支持 3 个文本元素。 如果文本元素放置在任何其他元素之后,它要么被移到顶部,要么被放置到一边。 最后,根子文本元素不支持某些文本属性(如 HintStyle)并且仅在 AdaptiveSubgroup 中工作。
AppLogoOverride ToastGenericAppLogo 用于替代应用徽标的可选徽标。
HeroImage ToastGenericHeroImage 在 Toast 通知和通知中心中可以显示的可选特色“hero”图像。
Attribution ToastGenericAttributionText 可选的署名文本,将显示在应用通知底部。
BaseUri Uri 用于与图像源属性中的相对 URL 配合使用的默认基本 URL。
AddImageQuery bool? 设置为“true”以允许Windows将查询字符串追加到应用通知中提供的图像 URL。 如果您的服务器托管图像,并可以通过查询字符串检索图像变体,或者可以忽略查询字符串直接返回指定的图像,请使用此属性。 此查询字符串指定缩放、对比度设置和语言;例如,通知中给定的“www.website.com/images/hello.png”值变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”
语言 字符串 使用本地化资源时视觉有效负载的目标区域设置,指定为 BCP-47 语言标记,例如“en-US”或“fr-FR”。 此语言环境被绑定或文本中指定的任何语言环境覆盖。 如果未提供,将改用系统区域设置。

IToastBindingGenericChild

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

Implementations
AdaptiveText
AdaptiveImage
AdaptiveGroup
AdaptiveProgressBar

AdaptiveText

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

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

BindableString

字符串的绑定值。

财产 类型 必需 说明
BindingName 字符串 获取或设置映射到绑定数据值的名称。

AdaptiveTextStyle

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

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

AdaptiveTextAlign

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

价值 含义
默认 默认值。 对齐由呈现器自动确定。
自动 对齐方式由当前语言和文化决定。
Left 将文本水平左对齐。
Center 将文本水平居中对齐。
右侧 将文本水平对齐到右侧。

AdaptiveImage

嵌入图像

财产 类型 必需 说明
来源 字符串 图像的网址。 支持 ms-appx、ms-appdata 和 http。 在正常连接上,Web 图像最多可以为 3 MB,按流量计费的连接最多可以为 1 MB。
HintCrop AdaptiveImageCrop 控制图像的预期裁剪。
HintRemoveMargin bool? 默认情况下,组/子组中的图像周围有 8px 的边距。 可以通过将此属性设置为 true 来删除此边距。
HintAlign AdaptiveImageAlign 图像的水平对齐方式。 仅适用于组/子组中的图像。
AlternateText 字符串 为图像描述的替代文本,用于方便无障碍访问。
AddImageQuery bool? 设置为“true”以允许Windows将查询字符串追加到应用通知中提供的图像 URL。 如果您的服务器托管图像,并可以通过查询字符串检索图像变体,或者可以忽略查询字符串直接返回指定的图像,请使用此属性。 此查询字符串指定缩放、对比度设置和语言;例如,通知中给定的“www.website.com/images/hello.png”值变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”

AdaptiveImageCrop

指定希望的图像裁剪。

价值 含义
默认 默认值。 由呈现器确定的裁剪行为。
没有 图像未裁剪。
Circle 图像裁剪为圆形。

AdaptiveImageAlign

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

价值 含义
默认 默认值。 由呈现器确定的对齐行为。
Stretch 图像拉伸以填充可用的宽度(以及可能可用的高度,具体取决于图像的放置位置)。
Left 将图像左对齐,按原始分辨率显示图像。
Center 将图像水平居中对齐,以原始分辨率显示图像。
右侧 将图像右对齐,以原始分辨率显示图像。

AdaptiveGroup

组以语义方式标识组中的内容必须显示为整体,或者如果不能容纳,则不显示。 组还允许创建多个列。

财产 类型 必需 说明
儿童 IList<自适应子组> 子组显示为垂直列。 必须使用子组来提供 AdaptiveGroup 中的任何内容。

AdaptiveSubgroup

子组是可以包含文本和图像的垂直列。

财产 类型 必需 说明
儿童 IList<IAdaptiveSubgroupChild> AdaptiveTextAdaptiveImage 是子组的有效子级。
HintWeight int? 通过指定相对于其他子组的权重来控制此子组列的宽度。
HintTextStacking AdaptiveSubgroupTextStacking 控制此子组内容的垂直对齐方式。

IAdaptiveSubgroupChild

子组子组的标记接口。

Implementations
AdaptiveText
AdaptiveImage

AdaptiveSubgroupTextStacking

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

价值 含义
默认 默认值。 呈现器会自动选择默认的垂直对齐方式。
顶部 垂直对齐至顶部。
Center 垂直对齐到中心。
底部 垂直对齐到底部。

AdaptiveProgressBar

进度栏。 仅在桌面上受支持。

财产 类型 必需 说明
标题 字符串 或 BindableString 获取或设置可选的标题字符串。 支持数据绑定。
价值 double 或 AdaptiveProgressBarValueBindableProgressBarValue 获取或设置进度栏的值。 支持数据绑定。 默认值为 0。
ValueStringOverride 字符串 或 BindableString 获取或设置要显示的可选字符串,而不是默认百分比字符串。 如果未提供此项,将显示“70%”之类的内容。
状态 字符串 或 BindableString 获取或设置状态字符串(必需),该字符串显示在左侧进度栏下方。 此字符串应反映操作的状态,例如“正在下载...”或“正在安装...”

AdaptiveProgressBarValue

一个表示进度栏值的类。

财产 类型 必需 说明
价值 翻倍 获取或设置表示完成百分比的值(0.0 - 1.0)。
IsIndeterminate 布尔 获取或设置一个值,该值指示进度栏是否不确定。 如果这是真的,将忽略

BindableProgressBarValue

可绑定进度条值。

财产 类型 必需 说明
BindingName 字符串 获取或设置映射到绑定数据值的名称。

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

财产 类型 必需 说明
来源 字符串 图像的网址。 支持 ms-appx、ms-appdata 和 http。 Http 映像的大小必须为 200 KB 或更小。
HintCrop ToastGenericAppLogoCrop 指定要裁剪图像的方式。
AlternateText 字符串 为图像描述的替代文本,用于方便无障碍访问。
AddImageQuery bool? 设置为“true”以允许Windows将查询字符串追加到应用通知中提供的图像 URL。 如果您的服务器托管图像,并可以通过查询字符串检索图像变体,或者可以忽略查询字符串直接返回指定的图像,请使用此属性。 此查询字符串指定缩放、对比度设置和语言;例如,通知中给定的“www.website.com/images/hello.png”值变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”

ToastGenericAppLogoCrop

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

价值 含义
默认 裁剪使用呈现器的默认行为。
没有 图像未裁剪,显示正方形。
Circle 图像裁剪为圆圈。

ToastGenericHeroImage

在 Toast(短暂通知)和通知中心内显示的特色“英雄”图像。

财产 类型 必需 说明
来源 字符串 图像的网址。 支持 ms-appx、ms-appdata 和 http。 Http 映像的大小必须为 200 KB 或更小。
AlternateText 字符串 为图像描述的替代文本,用于方便无障碍访问。
AddImageQuery bool? 设置为“true”以允许Windows将查询字符串追加到应用通知中提供的图像 URL。 如果您的服务器托管图像,并可以通过查询字符串检索图像变体,或者可以忽略查询字符串直接返回指定的图像,请使用此属性。 此查询字符串指定缩放、对比度设置和语言;例如,通知中给定的“www.website.com/images/hello.png”值变为“www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us”

ToastGenericAttributionText

应用通知底部显示的归属文本。

财产 类型 必需 说明
文字 字符串 要显示的文本。
语言 字符串 使用本地化资源时视觉有效负载的目标区域设置,指定为 BCP-47 语言标记,例如“en-US”或“fr-FR”。 如果未提供,将改用系统区域设置。

IToastActions

Toast 操作/输入标记接口。

Implementations
ToastActionsCustom
ToastActionsSnoozeAndDismiss

ToastActionsCustom

实现 IToastActions

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

财产 类型 必需 说明
输入 IList<IToastInput> 文本框和选择输入等类型的输入。 最多允许 5 个输入。
按钮 IList<IToastButton> 按钮在所有输入之后显示(如果按钮用作快速答复按钮,则与输入相邻)。 仅允许最多 5 个按钮(或者更少,如果有上下文菜单项)。
ContextMenuItems IList<ToastContextMenuItem> 自定义上下文菜单项,如果用户右键单击通知,则提供其他操作。 最多只能组合 5 个按钮和上下文菜单项

IToastInput

用于 Toast 输入的标记接口。

Implementations
ToastTextBox
ToastSelectionBox

ToastTextBox

实现 IToastInput

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

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

ToastSelectionBox

实现 IToastInput

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

财产 类型 必需 说明
ID 字符串 ID 是必需的。 如果用户选择了此项,则此 ID 将传回应用的代码,表示他们的选择。
内容 字符串 内容是必需的,它是显示在选择项上的一个字符串。

ToastSelectionBoxItem

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

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

IToastButton

Toast 按钮的标记接口。

Implementations
ToastButton
ToastButtonSnooze
ToastButtonDismiss

ToastButton

实现 IToastButton

用户可以单击的按钮。

财产 类型 必需 说明
内容 字符串 必填。 要显示在按钮上的文本。
参数 字符串 必填。 应用定义的参数字符串,当用户单击此按钮时,应用程序将稍后收到。
ActivationType ToastActivationType 控制单击时此按钮将使用的激活类型。 默认为前台。
ActivationOptions ToastActivationOptions 获取或设置与 Toast 按钮激活相关的其他选项。

ToastActivationType

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

价值 含义
Foreground 默认值。 前台应用已启动。
背景 假设已设置好所有内容,相应的后台任务会被触发,您可以在后台执行代码,例如发送用户的快速回复消息,而不会中断用户。
协议 使用协议激活启动其他应用。

ToastActivationOptions

与激活相关的其他选项。

财产 类型 必需 说明
AfterActivationBehavior ToastAfterActivationBehavior 获取或设置当用户调用此操作时 Toast 应表现的行为。 这仅适用于台式机,ToastButtonToastContextMenuItem
ProtocolActivationTargetApplicationPfn 字符串 如果使用 ToastActivationType.Protocol,您可以选择指定目标 PFN,这样即使有多个应用程序注册处理同一协议的 URI,也始终会启动您所需的应用程序。

ToastAfterActivationBehavior

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

价值 含义
默认 默认行为。 当用户对 Toast 执行操作时,将消除 Toast。
PendingUpdate 用户单击 Toast 上的按钮后,通知将保持“挂起更新”视觉状态。 如要避免用户长时间看到此“挂起的更新”视觉状态,您应该立刻从后台任务中更新Toast通知。

ToastButtonSnooze

实现 IToastButton

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

财产 类型 必需 说明
CustomContent 字符串 可选的自定义文本显示在按钮上,用于替代默认的本地化“暂停”文本。

ToastButtonDismiss

实现 IToastButton

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

财产 类型 必需 说明
CustomContent 字符串 在按钮上显示的可选自定义文本,覆盖默认的本地化“关闭”文本。

ToastActionsSnoozeAndDismiss

*实现 IToastActions

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

财产 类型 必需 说明
ContextMenuItems IList<ToastContextMenuItem> 自定义上下文菜单项,如果用户右键单击通知,则提供其他操作。 最多只能有 5 个项目。

ToastContextMenuItem

上下文菜单项条目。

财产 类型 必需 说明
内容 字符串 必填。 要显示的文本。
参数 字符串 必填。 应用定义的参数字符串,一旦用户单击菜单项并激活应用,应用可以稍后检索该字符串。
ActivationType ToastActivationType 控制单击时此菜单项将使用的激活类型。 默认为前台。
ActivationOptions ToastActivationOptions 与激活 Toast 上下文菜单项相关的其他选项。

ToastAudio

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

财产 类型 必需 说明
Src uri 要播放的媒体文件代替默认声音。 仅支持 ms-appx 和 ms-resource。 其他所有(ms-appdata、http、C:等)都不受支持。
Loop 布尔 如果在显示 Toast 时声音应重复,则设置为 true。设置为 false 则仅播放一次(默认值)。
Silent 布尔 真 若要将声音设为静音,则为 true;false 允许应用通知声音播放(默认值)。

ToastHeader

在通知中心内将多个通知组合在一起的自定义标头。

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