快顯通知內容結構描述

  • 發行項

以下說明快顯內容中的所有屬性和元素。

如果您想要使用原始 XML 而非通知程式庫，請參閱 XML 結構描述。

ToastContent

ToastContent

ToastContent 是描述通知內容的最上層物件，包括視覺效果、動作和音訊。

屬性 型別 必要 描述
啟動 string false 快顯啟動應用程式時傳遞至應用程式的字串。 此字串的格式和內容是由應用程式自行定義。 當使用者點選或按一下快顯來啟動其相關聯的應用程式時，啟動字串會提供內容給應用程式，使其能夠對使用者顯示與快顯內容相關的檢視，而不是以預設方式啟動。
視覺效果 ToastVisual true 描述快顯通知的視覺效果部分。
動作 IToastActions false 選擇性地使用按鈕和輸入來建立自訂動作。
音訊 ToastAudio false 描述快顯通知的音訊部分。
ActivationType ToastActivationType false 指定當使用者按一下此快顯的本文時，將使用的啟用類型。
ActivationOptions ToastActivationOptions false Creators Update 的新功能：與啟用快顯通知相關的其他選項。
案例 ToastScenario false 宣告快顯所使用的情境，例如警示或提醒。
DisplayTimestamp DateTimeOffset？ false Creators Update 的新功能：將預設時間戳記覆寫為自訂時間戳記，以代表實際傳遞通知內容的時間，而非 Windows 平台收到通知的時間。
頁首 ToastHeader false Creators Update 的新功能：新增自訂標頭至通知，以便在重要訊息中心內將多則通知設為群組。

ToastScenario

指定快顯所代表的情境。

值 意義
Default 一般快顯行為。
Reminder 提醒通知。 這會以預先展開的方式顯示，並停留在使用者的畫面上，直到關閉為止。
鬧鐘 警示通知。 這會以預先展開的方式顯示，並停留在使用者的畫面上，直到關閉為止。 音訊預設為循環播放，並且會使用警示音訊。
IncomingCall 來電通知。 這會以特殊通話形式預先展開顯示，並停留在使用者的畫面上，直到關閉為止。 音訊預設為循環播放，並且會使用鈴聲音訊。

ToastVisual

快顯的視覺效果部分包含繫結，其中包含文字、影像、彈性內容等。

屬性 型別 必要 描述
BindingGeneric ToastBindingGeneric true 可在所有裝置上轉譯的一般快顯繫結。 此繫結為必要項，而且不可為 null。
BaseUri URI false 預設基底 URL，會結合影像來源屬性中的相對 URL。
AddImageQuery bool？ false 設定為「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」
語言 string false 使用當地語系化資源時，視覺效果承載的目標地區設定，會指定為 BCP-47 語言標記，例如 “en-US” 或 “fr-FR”。 此地區設定會被繫結或文字中指定的任何地區設定覆寫。 如果未提供，則會改用系統地區設定。

ToastBindingGeneric

一般繫結是快顯的預設繫結，也是您指定文字、影像、彈性內容等地地方。

屬性 型別 必要 描述
子系 IList<IToastBindingGenericChild> false 快顯本文的內容，可以包含文字、影像和群組 (於年度更新版中新增)。 文字元素必須位於任何其他元素之前，而且只支援 3 個文字元素。 如果將文字元素放在任何其他元素之後，則會將它提升到頂端或捨棄。 最後，根子系文字元素不支援 HintStyle 這類特定文字屬性，而且只能在 AdaptiveSubgroup 內運作。 如果您在沒有年度更新版的裝置上使用 AdaptiveGroup，則群組內容將一律遭到捨棄。
AppLogoOverride ToastGenericAppLogo false 可覆寫應用程式標誌的選用標誌。
HeroImage ToastGenericHeroImage false 選用的精選「主圖」影像，會在快顯上和重要訊息中心內顯示。
Attribution ToastGenericAttributionText false 選用的條件文字，會在快顯通知的底部顯示。
BaseUri URI false 預設基底 URL，會結合影像來源屬性中的相對 URL。
AddImageQuery bool？ false 設定為「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」
語言 string false 使用當地語系化資源時，視覺效果承載的目標地區設定，會指定為 BCP-47 語言標記，例如 “en-US” 或 “fr-FR”。 此地區設定會被繫結或文字中指定的任何地區設定覆寫。 如果未提供，則會改用系統地區設定。

IToastBindingGenericChild

快顯子元素的標記介面，其中包含文字、影像、群組等。

實作
AdaptiveText
AdaptiveImage
AdaptiveGroup
AdaptiveProgressBar

AdaptiveText

彈性文字元素。 若放在最上層 ToastBindingGeneric.Children 中，則只會套用 HintMaxLines。 但是以群組/子群組的子系放置，則支援全文檢索樣式。

屬性 型別 必要 描述
Text string 或 BindableString false 要顯示的文字。 Creators Update 中新增的資料繫結支援，但僅適用於最上層文字元素。
HintStyle AdaptiveTextStyle false 樣式可控制文字的字型大小、粗細和不透明度。 僅適用於群組/子群組內的文字元素。
HintWrap bool？ false 將此設定為 true，以啟用文字換行。 最上層文字元素會忽略此屬性並一律換行 (您可以使用 HintMaxLines = 1 來停用最上層文字元素的換行)。 群組/子群組內的文字元素的換行預設為 false。
HintMaxLines int？ false 文字元素可顯示的行數上限。
HintMinLines int？ false 文字元素必須顯示的行數下限。 僅適用於群組/子群組內的文字元素。
HintAlign AdaptiveTextAlign false 文字的水平對齊方式。 僅適用於群組/子群組內的文字元素。
語言 string false XML 承載的目標地區設定，會指定為 BCP-47 語言標記，例如 “en-US” 或 “fr-FR”。 此處指定的地區設定會覆寫任何其他指定的地區設定，例如繫結或視覺效果中的地區設定。 如果此值是常值字串，則此屬性會預設為使用者的 UI 語言。 如果此值是字串參考，則此屬性會預設為 Windows 執行階段解析字串時選擇的地區設定。

BindableString

字串的繫結值。

屬性 型別 必要 描述
BindingName string true 取得或設定對應至繫結資料值的名稱。

AdaptiveTextStyle

文字樣式會控制字型大小、粗細和不透明度。 淡色不透明度為 60% 不透明。

值 意義
Default 預設值。 樣式是由轉譯器決定。
標題 小於段落字型大小。
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

控制文字的水平對齊方式。

值 意義
Default 預設值。 對齊方式會由轉譯器自動決定。
Auto 由目前語言和文化特性決定的對齊方式。
Left 水平靠左對齊文字。
Center 水平置中對齊文字。
Right 水平靠右對齊文字。

AdaptiveImage

內嵌影像。

屬性 型別 必要 描述
來源 string 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 根據預設，群組/子群組內的影像周圍會有 8px 的邊界。 您可以藉由將此屬性設定為 true 來移除此邊界。
HintAlign AdaptiveImageAlign false 影像的水平對齊方式。 僅適用於群組/子群組內的影像。
AlternateText string false 描述影像的替代文字，用於輔助功能。
AddImageQuery bool？ false 設定為「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

指定所需的影像裁剪。

值 意義
Default 預設值。 轉譯器決定的裁剪行為。
None 影像未裁剪。
圓圈 影像會裁剪成圓形。

AdaptiveImageAlign

指定影像的水準對齊方式。

值 意義
Default 預設值。 由轉譯器決定的對齊行為。
延展 影像會延伸以填滿可用寬度 (可能也會填滿可用高度，視影像放置的位置而定)。
Left 將影像靠左對齊，以原生解析度顯示影像。
Center 水平置中對齊影像，以原生解析度顯示影像。
Right 將影像靠右對齊，以原生解析度顯示影像。

AdaptiveGroup

年度更新版的新功能：群組會以語意方式識別群組中的內容必須整體顯示，或是無法容納的話，則不顯示。 群組也允許建立多個欄。

屬性 型別 必要 描述
子系 IList<AdaptiveSubgroup> false 子群組會顯示為垂直欄。 您必須使用子群組來提供 AdaptiveGroup 內的任何內容。

AdaptiveSubgroup

年度更新版的新功能：子群組是可以包含文字和影像的垂直欄。

屬性 型別 必要 描述
子系 IList<IAdaptiveSubgroupChild> false AdaptiveText 和 AdaptiveImage 是子群組的有效子系。
HintWeight int？ false 藉由指定相對於其他子群組的權數，控制這個子群組欄的寬度。
HintTextStacking AdaptiveSubgroupTextStacking false 控制這個子群組內容的垂直對齊方式。

IAdaptiveSubgroupChild

子群組子系的標記介面。

實作
AdaptiveText
AdaptiveImage

AdaptiveSubgroupTextStacking

TextStacking 會指定內容的垂直對齊方式。

值 意義
Default 預設值。 轉譯器會自動選取預設的垂直對齊方式。
前幾個 垂直靠上對齊。
Center 垂直置中對齊。
下方 垂直靠下對齊。

AdaptiveProgressBar

Creators Update 的新功能：進度列。 僅在電腦版組建 15063 或更新版本的快顯上支援。

屬性 型別 必要 Description
職稱 string 或 BindableString false 取得或設定選用的標題字串。 支援資料繫結。
值 double 或 AdaptiveProgressBarValue 或 BindableProgressBarValue false 取得或設定進度列的值。 支援資料繫結。 預設為 0。
ValueStringOverride string 或 BindableString false 取得或設定要取代預設百分比字串顯示的選用字串。 若未提供此字串，將會顯示如「70%」這樣的內容。
狀態 string 或 BindableString true 取得或設定狀態字串 (必要)，它會顯示在左側進度列下方。 此字串應傳達作業的狀態，例如「正在下載...」或「正在安裝...」

AdaptiveProgressBarValue

代示進度列值的類別。

屬性 型別 必要 Description
值 double false 取得或設定代表完成百分比的值 (0.0 - 1.0)。
IsIndeterminate bool false 取得或設定值，指出進度列是否不確定。 如果此值為 true，則會忽略 Value。

BindableProgressBarValue

可繫結的進度列值。

屬性 型別 必要 描述
BindingName string true 取得或設定對應至繫結資料值的名稱。

要顯示的標誌，而不是應用程式標誌。

屬性 型別 必要 描述
來源 string true 影像的 URL。 可支援 ms-appx、ms-appdata 和 http。 Http 影像的大小不得超過 200 KB。
HintCrop ToastGenericAppLogoCrop false 指定要裁剪影像的方式。
AlternateText string false 描述影像的替代文字，用於輔助功能。
AddImageQuery bool？ false 設定為「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

控制應用程式標誌影像的裁剪。

值 意義
Default 裁剪會使用轉譯器的預設行為。
None 影像未裁剪，以正方形顯示。
圓圈 影像會裁剪成圓形。

ToastGenericHeroImage

精選「主圖」影像，會在快顯上和重要訊息中心內顯示。

屬性 型別 必要 描述
來源 string true 影像的 URL。 可支援 ms-appx、ms-appdata 和 http。 Http 影像的大小不得超過 200 KB。
AlternateText string false 描述影像的替代文字，用於輔助功能。
AddImageQuery bool？ false 設定為「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

快顯通知底部顯示的 Attribution 文字。

屬性 型別 必要 描述
文字 string true 要顯示的文字。
語言 string false 使用當地語系化資源時，視覺效果承載的目標地區設定，會指定為 BCP-47 語言標記，例如 “en-US” 或 “fr-FR”。 如果未提供，則會改用系統地區設定。

IToastActions

快顯動作/輸入的標記介面。

實作
ToastActionsCustom
ToastActionsSnoozeAndDismiss

ToastActionsCustom

實作 IToastActions

使用按鈕、文字方塊和選項輸入等控制項，建立您自己的自訂動作和輸入。

屬性 型別 必要 描述
輸入 IList<IToastInput> false 文字方塊和選項輸入等輸入。 最多允許 5 個輸入。
按鈕 IList<IToastButton> false 按鈕會顯示在所有輸入之後 (如果是做為快速回覆按鈕使用，則與輸入相鄰)。 最多只允許 5 個按鈕 (如果同時有內容功能表項目，則會更少)。
ContextMenuItems IList<ToastContextMenuItem> false 年度更新版的新功能：自訂內容功能表項目，在使用者以滑鼠右鍵按一下通知時提供其他動作。 按鈕和內容功能表項目加起來最多只能有 5 個。

IToastInput

快顯輸入的標記介面。

實作
ToastTextBox
ToastSelectionBox

ToastTextBox

實作 IToastInput

使用者可在其中輸入文字的文字方塊控制項。

屬性 型別 必要 描述
Id string true ID 是必要項，用來將使用者輸入的文字對應至應用程式稍後取用的 ID/值鍵值組。
標題 string false 文字方塊上方顯示的標題文字。
PlaceholderContent string false 使用者尚未輸入任何文字時，文字方塊上要顯示的預留位置文字。
DefaultInput string false 放在文字方塊中的初始文字。 若保留 null 則會是空白文字方塊。

ToastSelectionBox

實作 IToastInput

選取方塊控制項，可讓使用者從選項下拉式清單中挑選。

屬性 型別 必要 描述
Id string true ID 是必要項。 如果使用者選取此項目，則會將此 ID 傳回應用程式的程式碼，代表其選擇的選項。
內容 string true 內容為必要項，而且是顯示在選取項目上的字串。

ToastSelectionBoxItem

選取方塊項目 (使用者可從下拉式清單中選取的項目)。

屬性 型別 必要 描述
Id string true ID 是必要項，用來將使用者輸入的文字對應至應用程式稍後取用的 ID/值鍵值組。
標題 string false 選取方塊上方顯示的標題文字。
DefaultSelectionBoxItemId string false 此項會控制預設選取的項目，並參考 ToastSelectionBoxItem 的 Id 屬性。 如果您未提供此項，則預設選取會是空的 (使用者不會看見任何內容)。
項目 IList<ToastSelectionBoxItem> false 使用者可從此 SelectionBox 中挑選的選取項目。 只能新增 5 個項目。

IToastButton

快顯按鈕的標記介面。

實作
ToastButton
ToastButtonSnooze
ToastButtonDismiss

ToastButton

實作 IToastButton

使用者可以按下的按鈕。

屬性 型別 必要 描述
內容 string true 必要。 按鈕上顯示的文字。
引數 string true 必要。 當使用者按一下此按鈕時，應用程式稍後將會收到的應用程式定義引數字串。
ActivationType ToastActivationType false 控制按下此按鈕時，此按鈕將使用的啟用類型。 預設為前景。
ActivationOptions ToastActivationOptions false Creators Update 的新功能：取得或設定與快顯按鈕啟用相關的其他選項。

ToastActivationType

決定使用者與特定動作互動時將使用的啟用類型。

值 意義
前景 預設值。 您的前景應用程式已啟動。
背景 您的對應背景工作 (假設一切設定完成) 會觸發，而且您可以在背景執行程式碼 (例如，傳送使用者的快速回覆訊息)，而不會干擾使用者。
通訊協定 使用通訊協定啟用來啟動不同的應用程式。

ToastActivationOptions

Creators Update 的新功能：與啟用相關的其他選項。

屬性 型別 必要 描述
AfterActivationBehavior ToastAfterActivationBehavior false Fall Creators Update 的新功能：取得或設定使用者叫用此動作時，快顯應使用的行為。 只能在電腦版上運作，適用於 ToastButton 和 ToastContextMenuItem。
ProtocolActivationTargetApplicationPfn string false 如果您使用 ToastActivationType.Protocol，您可以選擇性地指定目標 PFN，那麼即使註冊多個應用程式來處理相同的通訊協定 URI，仍會一律啟動您所需的應用程式。

ToastAfterActivationBehavior

指定使用者對快顯採取動作時，快顯應使用的行為。

值 意義
Default 預設行為。 使用者對快顯採取動作時，快顯將會關閉。
PendingUpdate 使用者按一下您快顯上的按鈕之後，通知仍會以「待更新」視覺狀態存在。 您應立即從背景工作更新快顯，使用者才不會一直看到這個「待更新」視覺狀態。

ToastButtonSnooze

實作 IToastButton

系統處理的延遲按鈕，它會自動處理通知的延遲。

屬性 型別 必要 描述
CustomContent string false 按鈕上顯示的選用自訂文字，會覆寫預設的當地語系化「延遲」文字。

ToastButtonDismiss

實作 IToastButton

系統處理的關閉按鈕，按下時會關閉通知。

屬性 型別 必要 描述
CustomContent string false 按鈕上顯示的選用自訂文字，會覆寫預設的當地語系化「關閉」文字。

ToastActionsSnoozeAndDismiss

*實作 IToastActions

自動建構延遲間隔的選取方塊，以及延遲/關閉按鈕，這些全都會自動當地語系化，且系統會自動處理延遲邏輯。

屬性 型別 必要 描述
ContextMenuItems IList<ToastContextMenuItem> false 年度更新版的新功能：自訂內容功能表項目，在使用者以滑鼠右鍵按一下通知時提供其他動作。 最多只能有 5 個項目。

ToastContextMenuItem

內容功能表項目。

屬性 型別 必要 描述
內容 string true 必要。 要顯示的文字。
引數 string true 必要。 當使用者按一下功能表項目時，應用程式稍後可在啟用時擷取的應用程式定義引數字串。
ActivationType ToastActivationType false 控制按下此功能表項目時，此功能表項目將使用的啟用類型。 預設為前景。
ActivationOptions ToastActivationOptions false Creators Update 的新功能：與快顯內容功能表項目的啟用相關的其他選項。

ToastAudio

指定收到快顯通知時要播放的音訊。

屬性 型別 必要 描述
Src uri false 要取代預設音效播放的媒體檔案。 僅支援 ms-appx 和 ms-resource。 其他都不支援 (ms-appdata、http、C: 等)。
Loop boolean false 若設定為 true，只要快顯仍顯示，音效就會重複播放；若設定為 false，則只播放一次 (預設)。
Silent boolean false True 表示將音效設為靜音；false 表示允許播放快顯通知音效 (預設)。

ToastHeader

Creators Update 的新功能：自訂標頭，可在重要訊息中心內將多則通知設為群組。

屬性 型別 必要 描述
Id string true 開發人員建立的識別碼，可做為此標頭的唯一識別。 若有兩則通知擁有相同的標頭 ID，則會在重要訊息中心內的相同標頭底下顯示。
標題 string true 標頭的標題。
引數 string true 取得或設定開發人員定義的引數字串，當使用者按一下此標頭時，該字串就會傳回至應用程式。 不可以是 null。
ActivationType ToastActivationType false 取得或設定按一下此標頭時，此標頭將會使用的啟用類型。 預設為前景。 請注意，僅支援前景和通訊協定。
ActivationOptions ToastActivationOptions false 取得或設定與快顯標頭的啟用相關的其他選項。