快顯通知內容結構描述Toast content schema

以下說明快顯通知內容中的所有屬性和元素。The following describes all of the properties and elements within toast content.

如果您想要使用原始 XML,而不使用 Notifications 程式庫,請參閱 XML 結構描述If you would rather use raw XML instead of the Notifications library, please see the XML schema.

ToastContentToastContent

ToastContentToastContent

ToastContent 是描述通知內容 (包括視覺效果、動作和音效) 的最上層物件。ToastContent is the top level object that describes a notification's content, including visuals, actions, and audio.

屬性Property 類型Type 必要Required 說明Description
發射Launch 字串string falsefalse 快顯通知啟動應用程式時,傳遞給應用程式的字串。A string that is passed to the application when it is activated by the Toast. 此字串的格式和內容是由應用程式定義以供應用程式自己使用。The format and contents of this string are defined by the app for its own use. 當使用者點選或按一下快顯通知來啟動其相關聯應用程式時,啟動字串會提供相關內容給應用程式,以允許應用程式向使用者顯示與快顯通知內容有關的檢視,而非以其預設方式啟動。When the user taps or clicks the Toast to launch its associated app, the launch string provides the context to the app that allows it to show the user a view relevant to the Toast content, rather than launching in its default way.
VisualVisual ToastVisualToastVisual truetrue 描述快顯通知的視覺效果部分。Describes the visual portion of the toast notification.
動作Actions IToastActionsIToastActions falsefalse 選擇性使用按鈕和輸入建立自訂動作。Optionally create custom actions with buttons and inputs.
音訊Audio ToastAudioToastAudio falsefalse 描述快顯通知的音效部分。Describes the audio portion of the toast notification.
ActivationTypeActivationType ToastActivationTypeToastActivationType falsefalse 指定使用者此快顯通知內文時,將會使用什麼啟用類型。Specifies what activation type will be used when the user clicks the body of this Toast.
ActivationOptionsActivationOptions ToastActivationOptionsToastActivationOptions falsefalse Creators Update 的新功能:與快顯通知啟用相關的其他選項。New in Creators Update: Additional options relating to activation of the toast notification.
案例Scenario ToastScenarioToastScenario falsefalse 宣告使用快顯通知的案例,例如鬧鐘或提醒。Declares the scenario your toast is used for, like an alarm or reminder.
DisplayTimestampDisplayTimestamp DateTimeOffset?DateTimeOffset? falsefalse Creators Update 的新功能:以自訂時間戳記覆寫預設時間戳記,表示實際傳遞通知內容的時間,而不是 Windows 平台收到通知的時間。New in Creators Update: Override the default timestamp with a custom timestamp representing when your notification content was actually delivered, rather than the time the notification was received by the Windows platform.
標頭Header ToastHeaderToastHeader falsefalse Creators Update 的新功能:新增自訂標頭以在控制中心中將多個通知群組在一起。New in Creators Update: Add a custom header to your notification to group multiple notifications together within Action Center.

ToastScenarioToastScenario

指定快顯通知表示哪些案例。Specifies what scenario the toast represents.

Value 意義Meaning
預設值Default 一般快顯通知行為。The normal toast behavior.
提醒Reminder 提醒通知。A reminder notification. 這會以預先展開的方式顯示,並停留在使用者的螢幕上,直到關閉為止。This will be displayed pre-expanded and stay on the user's screen till dismissed.
警示Alarm 鬧鐘通知。An alarm notification. 這會以預先展開的方式顯示,並停留在使用者的螢幕上,直到關閉為止。This will be displayed pre-expanded and stay on the user's screen till dismissed. 音效預設會重複播放,並使用鬧鐘音效。Audio will loop by default and will use alarm audio.
IncomingCallIncomingCall 來電通知。An incoming call notification. 這會使用特殊通話格式以預先展開的方式顯示,並停留在使用者的螢幕上,直到關閉為止。This will be displayed pre-expanded in a special call format and stay on the user's screen till dismissed. 音效預設會重複播放,並使用鈴聲音效。Audio will loop by default and will use ringtone audio.

ToastVisualToastVisual

快顯通知的視覺效果部分含有繫結,其中包含文字、影像、調適性內容等。The visual portion of toasts contains the bindings, which contains text, images, adaptive content, and more.

屬性Property 類型Type 必要Required 說明Description
BindingGenericBindingGeneric ToastBindingGenericToastBindingGeneric truetrue 一般快顯通知繫結,可呈現在所有裝置上。The generic toast binding, which can be rendered on all devices. 此繫結為必要項,但不可為 null。This binding is required and cannot be null.
BaseUriBaseUri UriUri falsefalse 與影像來源屬性中的相對 URL 結合的預設基底 URL。A default base URL that is combined with relative URLs in image source attributes.
AddImageQueryAddImageQuery bool?bool? falsefalse 設定為 "true" 可讓 Windows 將查詢字串附加至快顯通知中提供的影像 URL。Set to "true" to allow Windows to append a query string to the image URL supplied in the toast notification. 如果您的伺服器裝載影像,並且可以處理查詢字串 (方式為根據查詢字串擷取影像變體,或忽略查詢字串並傳回未使用查詢字串所指定的影像),請使用此屬性。Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. 此查詢字串指定比例、對比設定和語言。例如,通知中指定的 "www.website.com/images/hello.png" 值會變成 "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
語言Language 字串string falsefalse 使用當地語系化資源時的視覺效果承載目標地區設定,指定為 BCP-47 語言標記,例如 "en-US" 或 "fr-FR"。The target locale of the visual payload when using localized resources, specified as BCP-47 language tags such as "en-US" or "fr-FR". 繫結或文字中指定的任何地區設定都會覆寫此地區設定。This locale is overridden by any locale specified in binding or text. 如果未提供,則改用系統地區設定。If not provided, the system locale will be used instead.

ToastBindingGenericToastBindingGeneric

泛型繫結是快顯通知的預設繫結,並且是您指定文字、影像、調適性內容等項目的位置。The generic binding is the default binding for toasts, and is where you specify the text, images, adaptive content, and more.

屬性Property 類型Type 必要Required 說明Description
子系Children IList<IToastBindingGenericChild>IList<IToastBindingGenericChild> falsefalse 快顯通知的內文內容,其中可能包含文字、影像和群組 (年度更新版新增功能)。The contents of the body of the Toast, which can include text, images, and groups (added in Anniversary Update). 文字元素必須放在任何其他元素前面,但僅支援 3 個文字元素。Text elements must come before any other elements, and only 3 text elements are supported. 如果將文字元素放在任何其他元素後面,不是將其提拉到頂端,就是捨棄。If a text element is placed after any other element, it will either be pulled to the top or dropped. 總之,根子系文字元素不支援某些像是 HintStyle 的文字屬性,只能在 AdaptiveSubgroup 中使用。And finally, certain text properties like HintStyle aren't supported on the root children text elements, and only work inside an AdaptiveSubgroup. 如果您在沒有年度更新版的裝置上使用 AdaptiveGroup,就會直接捨棄群組內容。If you use AdaptiveGroup on devices without the Anniversary Update, the group content will simply be dropped.
AppLogoOverrideAppLogoOverride ToastGenericAppLogoToastGenericAppLogo falsefalse 要覆寫 App 標誌的選用標誌。An optional logo to override the app logo.
HeroImageHeroImage ToastGenericHeroImageToastGenericHeroImage falsefalse 選擇性精選「主角」影像,這會顯示在快顯通知和控制中心。An optional featured "hero" image that is displayed on the toast and within Action Center.
AttributionAttribution ToastGenericAttributionTextToastGenericAttributionText falsefalse 選擇性屬性文字,這會顯示在快顯通知的底部。Optional attribution text which will be displayed at the bottom of the toast notification.
BaseUriBaseUri UriUri falsefalse 與影像來源屬性中的相對 URL 結合的預設基底 URL。A default base URL that is combined with relative URLs in image source attributes.
AddImageQueryAddImageQuery bool?bool? falsefalse 設定為 "true" 可讓 Windows 將查詢字串附加至快顯通知中提供的影像 URL。Set to "true" to allow Windows to append a query string to the image URL supplied in the toast notification. 如果您的伺服器裝載影像,並且可以處理查詢字串 (方式為根據查詢字串擷取影像變體,或忽略查詢字串並傳回未使用查詢字串所指定的影像),請使用此屬性。Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. 此查詢字串指定比例、對比設定和語言。例如,通知中指定的 "www.website.com/images/hello.png" 值會變成 "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
語言Language 字串string falsefalse 使用當地語系化資源時的視覺效果承載目標地區設定,指定為 BCP-47 語言標記,例如 "en-US" 或 "fr-FR"。The target locale of the visual payload when using localized resources, specified as BCP-47 language tags such as "en-US" or "fr-FR". 繫結或文字中指定的任何地區設定都會覆寫此地區設定。This locale is overridden by any locale specified in binding or text. 如果未提供,則改用系統地區設定。If not provided, the system locale will be used instead.

IToastBindingGenericChildIToastBindingGenericChild

快顯通知子元素的標記介面,包含文字、影像、群組等。Marker interface for toast child elements that include text, images, groups, and more.

實作Implementations
AdaptiveTextAdaptiveText
AdaptiveImageAdaptiveImage
AdaptiveGroupAdaptiveGroup
AdaptiveProgressBarAdaptiveProgressBar

AdaptiveTextAdaptiveText

調適性文字元素。An adaptive text element. 如果放置在最上層 ToastBindingGeneric.Children,則只會套用 HintMaxLines。If placed in the top level ToastBindingGeneric.Children, only HintMaxLines will be applied. 但要是放置做為群組/子群組的子系,則支援全文檢索樣式。But if this is placed as a child of a group/subgroup, full text styling is supported.

屬性Property 類型Type 必要Required 說明Description
TextText 字串或 BindableStringstring or BindableString falsefalse 要顯示的文字。The text to display. Creators Update 新增的資料繫結支援,但僅適用於最上層文字元素。Data binding support added in Creators Update, but only works for top-level text elements.
HintStyleHintStyle AdaptiveTextStyleAdaptiveTextStyle falsefalse 此樣式會控制文字的字型大小、粗細和不透明度。The style controls the text's font size, weight, and opacity. 僅適用於群組/子群組內的文字元素。Only works for text elements inside a group/subgroup.
HintWrapHintWrap bool?bool? falsefalse 將此設定為 true 可啟用文字換行。Set this to true to enable text wrapping. 最上層文字元素會忽略此屬性,並且一律會換行 (您可以使用 HintMaxLines = 1 來停用最上層文字元素換行)。Top-level text elements ignore this property and always wrap (you can use HintMaxLines = 1 to disable wrapping for top-level text elements). 群組/子群組內的文字元素將換行預設為 false。Text elements inside groups/subgroups default to false for wrapping.
HintMaxLinesHintMaxLines int?int? falsefalse 允許文字元素顯示的最大行數。The maximum number of lines the text element is allowed to display.
HintMinLinesHintMinLines int?int? falsefalse 文字元素必須顯示的最小行數。The minimum number of lines the text element must display. 僅適用於群組/子群組內的文字元素。Only works for text elements inside a group/subgroup.
HintAlignHintAlign AdaptiveTextAlignAdaptiveTextAlign falsefalse 文字的水平對齊。The horizontal alignment of the text. 僅適用於群組/子群組內的文字元素。Only works for text elements inside a group/subgroup.
語言Language 字串string falsefalse 指定為 BCP-47 語言標記的 XML 承載目標地區設定,例如 "en-US" or "fr-FR"。The target locale of the XML payload, specified as a BCP-47 language tags such as "en-US" or "fr-FR". 此處指定的地區設定會覆寫任何其他位置 (例如繫結或視覺效果) 指定的地區設定。The locale specified here overrides any other specified locale, such as that in binding or visual. 如果此值為常值字串,則此屬性預設為使用者的 UI 語言。If this value is a literal string, this attribute defaults to the user's UI language. 如果此值為字串參考,則此屬性預設為 Windows 執行階段在解析字串時所選擇的地區設定。If this value is a string reference, this attribute defaults to the locale chosen by Windows Runtime in resolving the string.

BindableStringBindableString

字串的繫結值。A binding value for strings.

屬性Property 類型Type 必要Required 說明Description
BindingNameBindingName 字串string truetrue 取得或設定對應至您資料繫結值的名稱。Gets or sets the name that maps to your binding data value.

AdaptiveTextStyleAdaptiveTextStyle

文字樣式會控制字型大小、粗細和不透明度。Text style controls font size, weight, and opacity. 輕微不透明度是 60% 不透明。Subtle opacity is 60% opaque.

Value 意義Meaning
預設值Default 預設值。Default value. 樣式取決於轉譯器。Style is determined by the renderer.
標題Caption 小於段落字型大小。Smaller than paragraph font size.
CaptionSubtleCaptionSubtle 和 Caption 一樣,只是有輕微不透明度。Same as Caption but with subtle opacity.
本文Body 段落字型大小。Paragraph font size.
BodySubtleBodySubtle 和 Body 一樣,只是有輕微不透明度。Same as Body but with subtle opacity.
基地Base 段落字型大小、粗體粗細。Paragraph font size, bold weight. 基本上是 Body 的粗體版本。Essentially the bold version of Body.
BaseSubtleBaseSubtle 和 Base 一樣,只是有輕微不透明度。Same as Base but with subtle opacity.
副標題Subtitle H4 字型大小。H4 font size.
SubtitleSubtleSubtitleSubtle 和 Subtitle 一樣,只是有輕微不透明度。Same as Subtitle but with subtle opacity.
Title (標題)Title H3 字型大小。H3 font size.
TitleSubtleTitleSubtle 和 Title 一樣,只是有輕微不透明度。Same as Title but with subtle opacity.
TitleNumeralTitleNumeral 和 Title 一樣,只是上/下邊框間距已移除。Same as Title but with top/bottom padding removed.
Subheader.aboutdocsSubheader H2 字型大小。H2 font size.
SubheaderSubtleSubheaderSubtle 和 Subheader 一樣,只是有輕微不透明度。Same as Subheader but with subtle opacity.
SubheaderNumeralSubheaderNumeral 和 Subheader 一樣,只是上/下邊框間距已移除。Same as Subheader but with top/bottom padding removed.
標頭Header H1 字型大小。H1 font size.
HeaderSubtleHeaderSubtle 和 Header 一樣,只是有輕微不透明度。Same as Header but with subtle opacity.
HeaderNumeralHeaderNumeral 和 Header 一樣,只是上/下邊框間距已移除。Same as Header but with top/bottom padding removed.

AdaptiveTextAlignAdaptiveTextAlign

控制文字的水平對齊。Controls the horizontal alignmen of text.

Value 意義Meaning
預設值Default 預設值。Default value. 對齊方式自動由轉譯器決定。Alignment is automatically determined by the renderer.
AutoAuto 對齊方式取決於目前的語言及文化特性。Alignment determined by the current language and culture.
離開Left 將文字水平對齊左側。Horizontally align the text to the left.
中心Center 將文字水平對齊中央。Horizontally align the text in the center.
Right 將文字水平對齊右側。Horizontally align the text to the right.

AdaptiveImageAdaptiveImage

內嵌影像。An inline image.

屬性Property 類型Type 必要Required 說明Description
SourceSource 字串string truetrue 影像的 URL。The URL to the image. 支援 ms-appx、ms-appdata 和 http。ms-appx, ms-appdata, and http are supported. 從 Fall Creators Update 開始,一般連線的網頁影像可以高達 3 MB,而計量付費連線可以高達 1 MB。As of the Fall Creators Update, web images can be up to 3 MB on normal connections and 1 MB on metered connections. 在尚未執行 Fall Creators Update 的裝置上,網頁影像不得超過 200 KB。On devices not yet running the Fall Creators Update, web images must be no larger than 200 KB.
HintCropHintCrop AdaptiveImageCropAdaptiveImageCrop falsefalse 年度更新版的新功能:控制影像所需的裁剪。New in Anniversary Update: Control the desired cropping of the image.
HintRemoveMarginHintRemoveMargin bool?bool? falsefalse 群組/子群組內的影像周圍預設會有 8px 邊界。By default, images inside groups/subgroups have an 8px margin around them. 您可將此屬性設定為 true 以移除此邊界。You can remove this margin by setting this property to true.
HintAlignHintAlign AdaptiveImageAlignAdaptiveImageAlign falsefalse 影像的水平對齊。The horizontal alignment of the image. 僅適用於群組/子群組內的影像。Only works for images inside a group/subgroup.
AlternateTextAlternateText 字串string falsefalse 描述影像的替代文字,用於協助工具用途。Alternate text describing the image, used for accessibility purposes.
AddImageQueryAddImageQuery bool?bool? falsefalse 設定為 "true" 可讓 Windows 將查詢字串附加至快顯通知中提供的影像 URL。Set to "true" to allow Windows to append a query string to the image URL supplied in the toast notification. 如果您的伺服器裝載影像,並且可以處理查詢字串 (方式為根據查詢字串擷取影像變體,或忽略查詢字串並傳回未使用查詢字串所指定的影像),請使用此屬性。Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. 此查詢字串指定比例、對比設定和語言。例如,通知中指定的 "www.website.com/images/hello.png" 值會變成 "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"

AdaptiveImageCropAdaptiveImageCrop

指定影像所需的裁剪。Specifies the desired cropping of the image.

Value 意義Meaning
預設值Default 預設值。Default value. 裁剪行為取決於轉譯器。Cropping behavior determined by renderer.
None 不裁剪影像。Image is not cropped.
CircleCircle 將影像裁剪成圓形形狀。Image is cropped to a circle shape.

AdaptiveImageAlignAdaptiveImageAlign

指定影像的水平對齊方式。Specifies the horizontal alignment for an image.

Value 意義Meaning
預設值Default 預設值。Default value. 對齊行為取決於轉譯器。Alignment behavior determined by renderer.
延展Stretch 影像自動縮放到填滿可用寬度 (和可能會有的可用高度,視放置影像的位置而定)。Image stretches to fill available width (and potentially available height too, depending on where the image is placed).
離開Left 將影像對齊左側,並以其原生解析度來顯示影像。Align the image to the left, displaying the image at its native resolution.
中心Center 將影像對齊中央,並以其原生解析度來顯示影像。Align the image in the center horizontally, displayign the image at its native resolution.
Right 將影像對齊右側,並以其原生解析度來顯示影像。Align the image to the right, displaying the image at its native resolution.

AdaptiveGroupAdaptiveGroup

年度更新版的新功能:群組會在語意上識別,群組中的內容必須完整顯示,如果無法容納其中,則不顯示。New in Anniversary Update: Groups semantically identify that the content in the group must either be displayed as a whole, or not displayed if it cannot fit. 群組也允許建立多欄。Groups also allow creating multiple columns.

屬性Property 類型Type 必要Required 說明Description
子系Children IList<AdaptiveSubgroup>IList<AdaptiveSubgroup> falsefalse 子群組會顯示為垂直欄。Subgroups are displayed as vertical columns. 要在 AdaptiveGroup 中提供任何內容,您必須使用子群組。You must use subgroups to provide any content inside an AdaptiveGroup.

AdaptiveSubgroupAdaptiveSubgroup

年度更新版的新功能:子群組是可容納文字和影像的垂直欄。New in Anniversary Update: Subgroups are vertical columns that can contain text and images.

屬性Property 類型Type 必要Required 說明Description
子系Children IList<IAdaptiveSubgroupChild>IList<IAdaptiveSubgroupChild> falsefalse AdaptiveTextAdaptiveImage 是子群組的有效子系。AdaptiveText and AdaptiveImage are valid children of subgroups.
HintWeightHintWeight int?int? falsefalse 藉由指定相對於其他子群組的粗細,控制這個子群組欄的寬度。Control the width of this subgroup column by specifying the weight, relative to the other subgroups.
HintTextStackingHintTextStacking AdaptiveSubgroupTextStackingAdaptiveSubgroupTextStacking falsefalse 控制這個子群組內容的垂直對齊方式。Control the vertical alignment of this subgroup's content.

IAdaptiveSubgroupChildIAdaptiveSubgroupChild

子群組子系的標記介面。Marker interface for subgroup children.

實作Implementations
AdaptiveTextAdaptiveText
AdaptiveImageAdaptiveImage

AdaptiveSubgroupTextStackingAdaptiveSubgroupTextStacking

TextStacking 指定內容的垂直對齊方式。TextStacking specifies the vertical alignment of content.

Value 意義Meaning
預設值Default 預設值。Default value. 轉譯器自動選取預設垂直對齊方式。Renderer automatically selects the default vertical alignment.
前幾個Top 垂直對齊最上方。Vertical align to the top.
中心Center 垂直對齊中央。Vertical align to the center.
底端Bottom 垂直對齊底部。Vertical align to the bottom.

AdaptiveProgressBarAdaptiveProgressBar

Creators Update 中的新功能:進度列。New in Creators Update: A progress bar. 僅支援桌上型電腦組建 15063 或更新版本的快顯通知。Only supported on toasts on Desktop, build 15063 or newer.

屬性Property 類型Type 必要Required 說明Description
Title (標題)Title 字串或 BindableStringstring or BindableString falsefalse 取得或設定選用標題字串。Gets or sets an optional title string. 支援資料繫結。Supports data binding.
ReplTest1Value double 或 AdaptiveProgressBarValueBindableProgressBarValuedouble or AdaptiveProgressBarValue or BindableProgressBarValue falsefalse 取得或設定進度列的值。Gets or sets the value of the progress bar. 支援資料繫結。Supports data binding. 預設為 0。Defaults to 0.
ValueStringOverrideValueStringOverride 字串或 BindableStringstring or BindableString falsefalse 取得或設定要顯示的選用字串,用於取代預設百分比字串。Gets or sets an optional string to be displayed instead of the default percentage string. 如果未提供此項,將會顯示「70%」之類的內容。If this isn't provided, something like "70%" will be displayed.
狀態Status 字串或 BindableStringstring or BindableString truetrue 取得或設定狀態字串 (必要),它會顯示在左側進度列的下方。Gets or sets a status string (required), which is displayed underneath the progress bar on the left. 這個字串應該反映作業的狀態,例如「正在下載...」或「正在安裝...」This string should reflect the status of the operation, like "Downloading..." or "Installing..."

AdaptiveProgressBarValueAdaptiveProgressBarValue

類別,表示進度列的值。A class that represents the progress bar's value.

屬性Property 類型Type 必要Required 說明Description
ReplTest1Value doubledouble falsefalse 取得或設定值 (0.0 - 1.0),代表完成百分比。Gets or sets the value (0.0 - 1.0) representing the percent complete.
IsIndeterminateIsIndeterminate boolbool falsefalse 取得或設定值,指出進度列不確定。Gets or sets a value indicating whether the progress bar is indeterminate. 如果這為 true,會略過 ValueIf this is true, Value will be ignored.

BindableProgressBarValueBindableProgressBarValue

可繫結的進度列值。A bindable progress bar value.

屬性Property 類型Type 必要Required 說明Description
BindingNameBindingName 字串string truetrue 取得或設定對應至您資料繫結值的名稱。Gets or sets the name that maps to your binding data value.

要替代 App 標誌顯示的標誌。A logo to be displayed instead of the app logo.

屬性Property 類型Type 必要Required 說明Description
SourceSource 字串string truetrue 影像的 URL。The URL to the image. 支援 ms-appx、ms-appdata 和 http。ms-appx, ms-appdata, and http are supported. Http 影像的大小必須是 200 KB 或更少。Http images must be 200 KB or less in size.
HintCropHintCrop ToastGenericAppLogoCropToastGenericAppLogoCrop falsefalse 指定想要裁剪影像的方式。Specify how you would like the image to be cropped.
AlternateTextAlternateText 字串string falsefalse 描述影像的替代文字,用於協助工具用途。Alternate text describing the image, used for accessibility purposes.
AddImageQueryAddImageQuery bool?bool? falsefalse 設定為 "true" 可讓 Windows 將查詢字串附加至快顯通知中提供的影像 URL。Set to "true" to allow Windows to append a query string to the image URL supplied in the toast notification. 如果您的伺服器裝載影像,並且可以處理查詢字串 (方式為根據查詢字串擷取影像變體,或忽略查詢字串並傳回未使用查詢字串所指定的影像),請使用此屬性。Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. 此查詢字串指定比例、對比設定和語言。例如,通知中指定的 "www.website.com/images/hello.png" 值會變成 "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"

ToastGenericAppLogoCropToastGenericAppLogoCrop

控制 App 標誌影像的裁剪。Controls the cropping of the app logo image.

Value 意義Meaning
預設值Default 裁剪時會使用轉譯器的預設行為。Cropping uses the default behavior of the renderer.
None 不裁剪影像,顯示為正方形。Image is not cropped, displayed square.
CircleCircle 將影像裁剪成圓形。Image is cropped to a circle.

ToastGenericHeroImageToastGenericHeroImage

精選「主角」影像,這會顯示在快顯通知和控制中心。A featured "hero" image that is displayed on the toast and within Action Center.

屬性Property 類型Type 必要Required 說明Description
SourceSource 字串string truetrue 影像的 URL。The URL to the image. 支援 ms-appx、ms-appdata 和 http。ms-appx, ms-appdata, and http are supported. Http 影像的大小必須是 200 KB 或更少。Http images must be 200 KB or less in size.
AlternateTextAlternateText 字串string falsefalse 描述影像的替代文字,用於協助工具用途。Alternate text describing the image, used for accessibility purposes.
AddImageQueryAddImageQuery bool?bool? falsefalse 設定為 "true" 可讓 Windows 將查詢字串附加至快顯通知中提供的影像 URL。Set to "true" to allow Windows to append a query string to the image URL supplied in the toast notification. 如果您的伺服器裝載影像,並且可以處理查詢字串 (方式為根據查詢字串擷取影像變體,或忽略查詢字串並傳回未使用查詢字串所指定的影像),請使用此屬性。Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. 此查詢字串指定比例、對比設定和語言。例如,通知中指定的 "www.website.com/images/hello.png" 值會變成 "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"

ToastGenericAttributionTextToastGenericAttributionText

顯示在快顯通知底部的屬性文字。Attribution text displayed at the bottom of the toast notification.

屬性Property 類型Type 必要Required 說明Description
TextText 字串string truetrue 要顯示的文字。The text to display.
語言Language 字串string falsefalse 使用當地語系化資源時的視覺效果承載目標地區設定,指定為 BCP-47 語言標記,例如 "en-US" 或 "fr-FR"。The target locale of the visual payload when using localized resources, specified as BCP-47 language tags such as "en-US" or "fr-FR". 如果未提供,則改用系統地區設定。If not provided, the system locale will be used instead.

IToastActionsIToastActions

快顯通知動作/輸入的標記介面。Marker interface for toast actions/inputs.

實作Implementations
ToastActionsCustomToastActionsCustom
ToastActionsSnoozeAndDismissToastActionsSnoozeAndDismiss

ToastActionsCustomToastActionsCustom

Implements IToastActionsImplements IToastActions

使用按鈕、文字方塊和選擇輸入等控制項,自行建立自訂動作和輸入。Create your own custom actions and inputs, using controls like buttons, text boxes, and selection inputs.

屬性Property 類型Type 必要Required 說明Description
輸入Inputs IList<IToastInput>IList<IToastInput> falsefalse 像文字方塊和選擇輸入之類的輸入。Inputs like text boxes and selection inputs. 最多僅允許 5 項輸入。Only up to 5 inputs are allowed.
按鈕Buttons IList<IToastButton>IList<IToastButton> falsefalse 按鈕會顯示在所有輸入之後 (如果當做快速回覆按鈕,則與輸入相鄰)。Buttons are displayed after all the inputs (or adjacent to an input if the button is used as a quick reply button). 最多僅允許 5 個按鈕 (如果還有操作功能表項目則更少)。Only up to 5 buttons are allowed (or fewer if you also have context menu items).
ContextMenuItemsContextMenuItems IList<ToastCoNtextMenuItem>IList<ToastContextMenuItem> falsefalse 年度更新版的新功能:自訂操作功能表項目,如果使用者以滑鼠右鍵按一下通知,則會提供其他動作。New in Anniversary Update: Custom context menu items, providing additional actions if the user right clicks the notification. 最多只能有 5 個按鈕與操作功能表項目搭配 組合You can only have up to 5 buttons and context menu items combined.

IToastInputIToastInput

快顯通知輸入的標記介面。Marker interface for toast inputs.

實作Implementations
ToastTextBoxToastTextBox
ToastSelectionBoxToastSelectionBox

ToastTextBoxToastTextBox

Implements IToastInputImplements IToastInput

使用者可以輸入文字的文字方塊控制項。A text box control that the user can type text into.

屬性Property 類型Type 必要Required 說明Description
識別碼Id 字串string truetrue Id 是必要項,用來將使用者輸入的文字對應到 App 稍後取用之識別碼/值的索引鍵/值組。The Id is required, and is used to map the user-inputted text into a key-value pair of id/value which your app later consumes.
Title (標題)Title 字串string falsefalse 要顯示在文字方塊上方的標題文字。Title text to display above the text box.
PlaceholderContentPlaceholderContent 字串string falsefalse 使用者尚未輸入任何文字時,要顯示在文字方塊中的預留位置文字。Placeholder text to be displayed on the text box when the user hasn't typed any text yet.
DefaultInputDefaultInput 字串string falsefalse 要放在文字方塊中的初始文字。The initial text to place in the text box. 如需空白文字方塊,請保持為 null。Leave this null for a blank text box.

ToastSelectionBoxToastSelectionBox

Implements IToastInputImplements IToastInput

可讓使用者從選項下拉式清單挑選的選擇方塊控制項。A selection box control, which lets users pick from a dropdown list of options.

屬性Property 類型Type 必要Required 說明Description
識別碼Id 字串string truetrue Id 為必要項。The Id is required. 如果使用者選取此項目,這個 Id 將會傳回到 App 的程式碼,表示他們選擇了哪些選取項目。If the user selected this item, this Id will be passed back to your app's code, representing which selection they chose.
內容Content 字串string truetrue Content 為必要項,並且是顯示在選取項目上的字串。Content is required, and is a string that is displayed on the selection item.

ToastSelectionBoxItemToastSelectionBoxItem

選擇方塊項目 (使用者可從下拉式清單選取的項目)。A selection box item (an item that the user can select from the drop down list).

屬性Property 類型Type 必要Required 說明Description
識別碼Id 字串string truetrue Id 是必要項,用來將使用者輸入的文字對應到 App 稍後取用之識別碼/值的索引鍵/值組。The Id is required, and is used to map the user-inputted text into a key-value pair of id/value which your app later consumes.
Title (標題)Title 字串string falsefalse 要顯示在選擇方塊上方的標題文字。Title text to display above the selection box.
DefaultSelectionBoxItemIdDefaultSelectionBoxItemId 字串string falsefalse 這會控制預設選取哪些項目,並且參考 ToastSelectionBoxItem 的的 Id 屬性。This controls which item is selected by default, and refers to the Id property of the ToastSelectionBoxItem. 如果沒有提供這個屬性,預設選取項目會是空白 (使用者看不到任何項目)。If you do not provide this, the default selection will be empty (user sees nothing).
項目Items IList<ToastSelectionBoxItem>IList<ToastSelectionBoxItem> falsefalse 使用者可以從這個 SelectionBox 中挑選的選取項目。The selection items that the user can pick from in this SelectionBox. 只能新增 5 個項目。Only 5 items can be added.

IToastButtonIToastButton

快顯通知按鈕的標記介面。Marker interface for toast buttons.

實作Implementations
ToastButtonToastButton
ToastButtonSnoozeToastButtonSnooze
ToastButtonDismissToastButtonDismiss

ToastButtonToastButton

Implements IToastButtonImplements IToastButton

使用者可以按一下的按鈕。A button that the user can click.

屬性Property 類型Type 必要Required 說明Description
內容Content 字串string truetrue 必要。Required. 要在按鈕上顯示的文字。The text to display on the button.
引數Arguments 字串string truetrue 必要。Required. App 定義的引數字串,如果使用者按一下此按鈕,App 稍後會收到該字串。App-defined string of arguments that the app will later receive if the user clicks this button.
ActivationTypeActivationType ToastActivationTypeToastActivationType falsefalse 控制此按鈕在使用者按一下時使用什麼類型的啟用。Controls what type of activation this button will use when clicked. 預設為 Foreground。Defaults to Foreground.
ActivationOptionsActivationOptions ToastActivationOptionsToastActivationOptions falsefalse Creators Update 的新功能:取得或設定與快顯通知按鈕啟用相關的其他選項。New in Creators Update: Gets or sets additional options relating to activation of the toast button.

ToastActivationTypeToastActivationType

決定使用者以特定動作進行互動時使用的啟用類型。Decides the type of activation that will be used when the user interacts with a specific action.

Value 意義Meaning
前景Foreground 預設值。Default value. 啟動您的前景 App。Your foreground app is launched.
背景Background 觸發對應的背景工作 (假設您已設定所有項目),而且您可以在不干擾使用者的情況下,於背景執行程式碼 (例如傳送使用者的快速回覆訊息)。Your corresponding background task (assuming you set everything up) is triggered, and you can execute code in the background (like sending the user's quick reply message) without interrupting the user.
通訊協定Protocol 使用通訊協定啟用來啟動不同的 App。Launch a different app using protocol activation.

ToastActivationOptionsToastActivationOptions

Creators Update 的新功能:與啟用相關的其他選項。New in Creators Update: Additional options relating to activation.

屬性Property 類型Type 必要Required 說明Description
AfterActivationBehaviorAfterActivationBehavior ToastAfterActivationBehaviorToastAfterActivationBehavior falsefalse Fall Creators Update 的新功能:取得或設定當使用者叫用此動作時,快顯通知應該使用的行為。New in Fall Creators Update: Gets or sets the behavior that the toast should use when the user invokes this action. 這只適用於桌上型電腦、ToastButtonToastContextMenuItemThis only works on Desktop, for ToastButton and ToastContextMenuItem.
ProtocolActivationTargetApplicationPfnProtocolActivationTargetApplicationPfn 字串string falsefalse 如果您要使用 ToastActivationType.Protocol ,則可以選擇性指定目標 PFN,因此無論是否已註冊多個 App 來處理相同的通訊協定 URI,都一律會啟動您想要的 App。If you are using ToastActivationType.Protocol , you can optionally specify the target PFN, so that regardless of whether multiple apps are registered to handle the same protocol uri, your desired app will always be launched.

ToastAfterActivationBehaviorToastAfterActivationBehavior

指定當使用者對快顯通知採取動作時,快顯通知應該使用的行為。Specifies the behavior that the toast should use when the user takes action on the toast.

Value 意義Meaning
預設值Default 預設行為。Default behavior. 當使用者對快顯通知採取動作時,將會關閉快顯通知。The toast will be dismissed when the user takes action on the toast.
PendingUpdatePendingUpdate 在使用者按一下快顯通知的按鈕後,通知仍保持存在於「擱置中的更新」可見狀態。After the user clicks a button on your toast, the notification will remain present, in a "pending update" visual state. 您應該立即更新背景工作的快顯通知,讓使用者不會看到太久的這個「擱置中的更新」可見狀態。You should immediately update your toast from a background task so that the user does not see this "pending update" visual state for too long.

ToastButtonSnoozeToastButtonSnooze

Implements IToastButtonImplements IToastButton

系統處理的延遲按鈕,此按鈕會自動處理通知延遲。A system-handled snooze button that automatically handles snoozing of the notification.

屬性Property 類型Type 必要Required 說明Description
CustomContentCustomContent 字串string falsefalse 顯示在按鈕上的選擇性自訂文字,這會覆寫預設當地語系化的 "Snooze" 文字 (延遲)。Optional custom text displayed on the button that overrides the default localized "Snooze" text.

ToastButtonDismissToastButtonDismiss

Implements IToastButtonImplements IToastButton

系統處理的關閉按鈕,按一下時會關閉通知。A system-handled dismiss button that dismisses the notification when clicked.

屬性Property 類型Type 必要Required 說明Description
CustomContentCustomContent 字串string falsefalse 顯示在按鈕上的選擇性自訂文字,這會覆寫預設當地語系化的 "Dismiss" 文字 (關閉)。Optional custom text displayed on the button that overrides the default localized "Dismiss" text.

ToastActionsSnoozeAndDismissToastActionsSnoozeAndDismiss

* 實行 IToastActions*Implements IToastActions

自動建構延遲間隔選取方塊並將按鈕延遲/關閉,全部自動進行當地語系化,並自動由系統處理延遲邏輯。Automatically constructs a selection box for snooze intervals, and snooze/dismiss buttons, all automatically localized, and snoozing logic is automatically handled by the system.

屬性Property 類型Type 必要Required 說明Description
ContextMenuItemsContextMenuItems IList<ToastCoNtextMenuItem>IList<ToastContextMenuItem> falsefalse 年度更新版的新功能:自訂操作功能表項目,如果使用者以滑鼠右鍵按一下通知,則會提供其他動作。New in Anniversary Update: Custom context menu items, providing additional actions if the user right clicks the notification. 您最多只能有 5 個項目。You can only have up to 5 items.

ToastContextMenuItemToastContextMenuItem

操作功能表項目輸入。A context menu item entry.

屬性Property 類型Type 必要Required 說明Description
內容Content 字串string truetrue 必要。Required. 要顯示的文字。The text to display.
引數Arguments 字串string truetrue 必要。Required. this button.App 定義的引數字串,當使用者按一下功能表項目時,只要 App 已啟用,稍後即可收到該字串。App-defined string of arguments that the app can later retrieve once it is activated when the user clicks the menu item.
ActivationTypeActivationType ToastActivationTypeToastActivationType falsefalse 控制此功能表項目在使用者按一下時使用什麼類型的啟用。Controls what type of activation this menu item will use when clicked. 預設為 Foreground。Defaults to Foreground.
ActivationOptionsActivationOptions ToastActivationOptionsToastActivationOptions falsefalse Creators Update 的新功能:與快顯通知操作功能表項目啟用作業相關的其他選項。New in Creators Update: Additional options relating to activation of the toast context menu item.

ToastAudioToastAudio

指定收到快顯通知時要播放的音效。Specify audio to be played when the Toast notification is received.

屬性Property 類型Type 必要Required 說明Description
SrcSrc uriuri falsefalse 要取代預設音效播放的媒體檔案。The media file to play in place of the default sound. 僅支援 ms-appx 和 ms-appdata。Only ms-appx and ms-appdata are supported.
Loop booleanboolean falsefalse 如果快顯通知顯示多久就要重複音效多久,則設定為 true。false 表示只播放一次 (預設)。Set to true if the sound should repeat as long as the Toast is shown; false to play only once (default).
無訊息Silent booleanboolean falsefalse true 表示將音效設定為靜音。false 表示允許播放快顯通知音訊 (預設)。True to mute the sound; false to allow the toast notification sound to play (default).

ToastHeaderToastHeader

Creators Update 的新功能:將控制中心內多個通知群組一起的自訂標頭。New in Creators Update: A custom header that groups multiple notifications together within Action Center.

屬性Property 類型Type 必要Required 說明Description
識別碼Id 字串string truetrue 開發人員所建立唯一辨識此標頭的識別碼。A developer-created identifier that uniquely identifies this header. 如果兩個通知標頭識別碼相同,這些通知將會在控制中心顯示於相同標頭下方。If two notifications have the same header id, they will be displayed underneath the same header in Action Center.
Title (標題)Title 字串string truetrue 標頭的標題。A title for the header.
引數Arguments 字串string truetrue 取得或設定開發人員定義的引數字串,當使用者按下此標頭時會傳回至應用程式。Gets or sets a developer-defined string of arguments that is returned to the app when the user clicks this header. 不可以是 null。Cannot be null.
ActivationTypeActivationType ToastActivationTypeToastActivationType falsefalse 取得或設定此標頭在使用者按一下時要使用的啟用類型。Gets or sets the type of activation this header will use when clicked. 預設為 Foreground。Defaults to Foreground. 請注意,只支援 Foreground 和 Protocol。Note that only Foreground and Protocol are supported.
ActivationOptionsActivationOptions ToastActivationOptionsToastActivationOptions falsefalse 取得或設定與快顯通知標頭啟用相關的其他選項。Gets or sets additional options relating to activation of the toast header.