共用方式為

快顯通知內容架構

下列描述快顯通知內容中的所有屬性和元素。

如果您想要使用原始 XML 而非 Notifications 連結庫，請參閱 XML 架構。

ToastContent

ToastContent

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

Property 類型 Required Description
Launch 字串 false 快顯通知啟動應用程式時傳遞給應用程式的字串。 此字串的格式和內容是由應用程式自行定義。 當使用者點選或按一下快顯通知來啟動其相關聯的應用程式時，啟動字串會提供內容給應用程式，以允許它向使用者顯示與快顯通知內容相關的檢視，而不是以預設方式啟動。
Visual ToastVisual true 描述快顯通知的視覺部分。
Actions IToastActions false 選擇性地使用按鈕和輸入來建立自定義動作。
Audio ToastAudio false 描述快顯通知的音訊部分。
ActivationType ToastActivationType false 指定當使用者按下這則快顯通知的主體時，將會使用的啟用類型。
ActivationOptions ToastActivationOptions false Creators Update 的新功能：與快顯通知啟用相關的其他選項。
Scenario ToastScenario false 宣告您的快顯通知所應用的情境，例如鬧鐘或提醒。
DisplayTimestamp DateTimeOffset? false Creators Update 的新功能：使用自定義時間戳覆寫預設時間戳，代表您通知內容實際傳遞的時間，而不是 Windows 平臺收到通知的時間。
Header ToastHeader false Creators Update 的新功能：將自定義標頭功能新增至您的通知，以便在操作中心內將多個通知群組在一起。

ToastScenario

指定通知提示所代表的情境。

Value Meaning
Default 一般的視窗通知行為。
Reminder 提醒通知。 這會在預先展開後顯示，並停留在用戶的畫面上，直到關閉為止。
Alarm 警示通知。 這會在預先展開後顯示，並停留在用戶的畫面上，直到關閉為止。 音訊預設會循環，並且會使用警示音訊。
IncomingCall 來電通知。 這會以特殊通話格式預先顯示，並停留在用戶的畫面上，直到關閉為止。 音效預設會循環播放，並且會使用鈴聲音效。

ToastVisual

快顯通知的視覺部分包含系結，其中包含文字、影像、調適型內容等等。

Property 類型 Required Description
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”
Language 字串 false 使用本地化資源時，視覺承載的目標地區設定，指定為 BCP-47 語言標記，例如 “en-US” 或 “fr-FR”。 綁定或文字中指定的任何區域設定會覆蓋此區域設定。 如果未提供，將使用系統預設的地區設定。

ToastBindingGeneric

泛用綁定是通知提示的預設綁定，您可以在此設定文字、圖片、調適式內容等。

Property 類型 Required Description
Children IList<IToastBindingGenericChild> false Toast 的內容可以包含文字、圖片和群組（在年度更新中新增）。 文字元素必須位於任何其他元素之前，而且只支援 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”
Language 字串 false 使用本地化資源時，視覺承載的目標地區設定，指定為 BCP-47 語言標記，例如 “en-US” 或 “fr-FR”。 綁定或文字中指定的任何區域設定會覆蓋此區域設定。 如果未提供，將使用系統預設的地區設定。

IToastBindingGenericChild

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

Implementations
AdaptiveText
AdaptiveImage
AdaptiveGroup
AdaptiveProgressBar

AdaptiveText

調適型文字元素。 如果放在最上層 ToastBindingGeneric.Children 中，則只會套用 HintMaxLines。 但如果這被放置在群組或子群組中時，則支援全文樣式。

Property 類型 Required Description
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 文字的水平對齊方式。 僅適用於群組/子群組內的文字元素。
Language 字串 false XML 承載的目標地區設定，指定為 BCP-47 語言標記，例如 「en-US」 或 「fr-FR」。 此處指定的地區設定會覆蓋任何其他指定的地區設定，例如資料綁定或視覺效果中的地區設定。 如果此值是常值字串，則此屬性預設為使用者的UI語言。 如果這個值是字串參考，則此屬性預設為 Windows 執行時間在解析字串時所選擇的地區設定。

BindableString

字串的系結值。

Property 類型 Required Description
BindingName 字串 true 取得或設定對應至系結數據值的名稱。

AdaptiveTextStyle

文字樣式會控制字型大小、粗細和不透明度。 微弱的透明度是 60% 透明。

Value Meaning
Default 預設值。 樣式是由轉譯器決定。
Caption 小於段落字型大小。
CaptionSubtle 與 Caption 相同，但帶有微妙的不透明度。
Body 段落字型大小。
BodySubtle 與本體相同，但具有微妙的透明效果。
Base 段落字型大小，字體粗細。 基本上是粗體版本的 Body。
BaseSubtle 與基底相同，但含微妙的不透明度。
Subtitle H4 字體大小。
SubtitleSubtle 與子標題相同，但呈現輕微的透明度。
Title H3 字型大小。
TitleSubtle 與標題相同，但透明度較輕微。
TitleNumeral 與 Title 相同，但已移除上/下邊框間距。
副標題 H2 字體大小。
SubheaderSubtle 與子標題相同，但具有略微不透明度。
SubheaderNumeral 與子標題相同，但已移除上/下邊框間距。
Header H1 字型大小。
HeaderSubtle 與標題相同，但具有輕微的不透明度。
HeaderNumeral 與 Header 相同，但已移除上/下邊框間距。

AdaptiveTextAlign

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

Value Meaning
Default 預設值。 對齊是由轉譯器自動決定。
Auto 對齊方式由目前的語言和文化決定。
Left 將文字水平對齊至左側。
Center 將文字水平置中對齊。
Right 請將文字水平對齊至右側。

AdaptiveImage

內嵌影像。

Property 類型 Required Description
Source 字串 true 圖片的網址。 支援 ms-appx、ms-appdata 和 HTTP。 從「Fall Creators Update」開始，網頁圖片在一般連線下最多可以為 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 將查詢字串附加至快顯通知中提供的影像 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 預設值。 渲染器決定的裁剪行為。
None 影像未裁剪。
Circle 影像會裁剪成圓形圖形。

AdaptiveImageAlign

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

Value Meaning
Default 預設值。 由渲染器決定的對齊行為。
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 預設值。 轉譯器會自動選取預設的垂直對齊方式。
Top 垂直對齊頂端。
Center 垂直對齊置中。
Bottom 垂直對齊底部。

AdaptiveProgressBar

Creators Update 的新功能：進度列。 僅支援桌面上的快顯通知，版本編號15063或更新版本。

Property 類型 Required Description
Title string 或 BindableString false 取得或設定可選的標題字串。 支援數據系結。
Value double 或 自適應進度條值 或 可綁定進度條值 false 取得或設定進度列的值。 支援數據系結。 預設值為 0。
ValueStringOverride string 或 BindableString false 取得或設定要顯示的選擇性字串，而不是預設百分比字串。 如果未提供此值，則會顯示類似「70%」的內容。
Status string 或 BindableString true 取得或設定狀態字串 （必要），其會顯示在左側進度列下方。 此字串應該反映作業的狀態，例如「正在下載...」或 「正在安裝...」

AdaptiveProgressBarValue

表示進度列值的類別。

Property 類型 Required Description
Value double false 取得或設定代表完成百分比的值 （0.0 - 1.0）。
IsIndeterminate bool false 取得或設定值，指出進度列是否不確定。 如果這是真的，則會忽略 Value。

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 將查詢字串附加至快顯通知中提供的影像 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

精選的「主角」影像，顯示在快顯通知和控制中心內。

Property 類型 Required Description
Source 字串 true 圖片的網址。 支援 ms-appx、ms-appdata 和 HTTP。 Http 映射的大小必須小於 200 KB。
AlternateText 字串 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

快顯通知底部顯示的屬性文字。

Property 類型 Required Description
Text 字串 true 要顯示的文字。
Language 字串 false 使用本地化資源時，視覺承載的目標地區設定，指定為 BCP-47 語言標記，例如 “en-US” 或 “fr-FR”。 如果未提供，將使用系統預設的地區設定。

IToastActions

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

Implementations
ToastActionsCustom
ToastActionsSnoozeAndDismiss

ToastActionsCustom

實作 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

實作 IToastInput

用戶可以輸入文字的文字框控制件。

Property 類型 Required Description
Id 字串 true 需要 Id，並用來將使用者輸入的文字對應成應用程式稍後取用的鍵值對。
Title 字串 false 顯示於文字框上方的標題文字。
PlaceholderContent 字串 false 當使用者尚未輸入任何文字時，要顯示在文字框中的佔位文字。
DefaultInput 字串 false 要放在文字框中的初始文字。 將此設為 null 以讓文字框保持空白。

ToastSelectionBox

實作 IToastInput

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

Property 類型 Required Description
Id 字串 true 需要標識碼。 如果使用者選取此項目，則會將此標識符傳回至應用程式的程序代碼，以代表他們選擇的內容。
Content 字串 true 內容是必需的，且是顯示於選擇項目的字串。

ToastSelectionBoxItem

可選項目（使用者可以從下拉式清單中選取的項目）。

Property 類型 Required Description
Id 字串 true 需要 Id，並用來將使用者輸入的文字對應成應用程式稍後取用的鍵值對。
Title 字串 false 顯示在選取方塊上方的文字標題。
DefaultSelectionBoxItemId 字串 false 這會控制預設選擇的項目，並且參考 ToastSelectionBoxItem的 Id 屬性。 如果您未提供此，預設選項將為空（使用者不會看到任何內容）。
Items IList<ToastSelectionBoxItem> false 用戶可以在此 SelectionBox 中挑選的選項。 只能新增5個項目。

IToastButton

快顯通知按鈕的標記介面。

Implementations
ToastButton
ToastButtonSnooze
ToastButtonDismiss

ToastButton

Implements IToastButton

用戶可以按下的按鈕。

Property 類型 Required Description
Content 字串 true Required. 要顯示在按鈕上的文字。
Arguments 字串 true Required. 使用者按下此按鈕時，應用程式將會收到由應用程式定義的參數字串。
ActivationType ToastActivationType false 控制按下時，此按鈕將使用的啟用類型。 預設為 Foreground。
ActivationOptions ToastActivationOptions false Creators Update 的新功能：取得或設定與快顯通知按鈕啟動操作相關的其他選項。

ToastActivationType

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

Value Meaning
Foreground 預設值。 前景應用程式已啟動。
Background 系統會觸發對應的背景工作（假設您已設定所有專案），而且您可以在背景執行程序代碼（例如傳送使用者的快速回復訊息），而不會中斷使用者。
Protocol 使用通訊協定啟用啟動不同的應用程式。

ToastActivationOptions

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

Property 類型 Required Description
AfterActivationBehavior ToastAfterActivationBehavior false Fall Creators Update 的新功能：取得或設定當使用者執行此操作時，通知訊息應該使用的行為。 這僅適用於桌面，對 ToastButton 和 ToastContextMenuItem有效。
ProtocolActivationTargetApplicationPfn 字串 false 如果您使用 ToastActivationType.Protocol，可以選擇性地指定目標 PFN，這樣，即使有多個應用程式註冊來處理相同的協定 URI，您想要的應用程式仍然會被啟動。

ToastAfterActivationBehavior

指定當使用者在快顯通知上採取動作時，快顯通知應該使用的行為。

Value Meaning
Default 預設行為。 當使用者在快顯通知上採取動作時，將會關閉快顯通知。
PendingUpdate 使用者按下你的彈出通知上的按鈕後，通知將會維持在「待更新」的視覺狀態。 立即從背景工作更新您的快顯通知，讓使用者不會看到這個「擱置中的更新」視覺狀態太久。

ToastButtonSnooze

Implements IToastButton

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

Property 類型 Required Description
CustomContent 字串 false 在按鈕上顯示的選用自定義文字，會覆蓋預設的本地化「Snooze」文字。

ToastButtonDismiss

Implements IToastButton

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

Property 類型 Required Description
CustomContent 字串 false 按鈕上顯示的選擇性自定義文字，將覆蓋預設本地化的「關閉」文字。

ToastActionsSnoozeAndDismiss

*實作 IToastActions

自動建立貪睡間隔的選取方塊及貪睡/取消按鈕，所有項目皆自動進行本地化，貪睡的邏輯由系統自動處理。

Property 類型 Required Description
ContextMenuItems IList<ToastContextMenuItem> false 年度更新的新功能：自訂內容功能表項目，使用者在滑鼠右鍵點擊通知時可執行額外動作。 您最多只能有 5 個項目。

ToastContextMenuItem

右鍵選單項目。

Property 類型 Required Description
Content 字串 true Required. 要顯示的文字。
Arguments 字串 true Required. 應用程式定義的參數字串，當使用者點擊選單項目後啟用時，應用程式可以稍後擷取。
ActivationType ToastActivationType false 控制點擊此功能表項時所使用的激活類型。 預設為 Foreground。
ActivationOptions ToastActivationOptions false Creators Update 的新功能：與通知快顯功能表項目啟用相關的其他選項。

ToastAudio

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

Property 類型 Required Description
Src uri false 要播放的媒體檔案，以取代預設音效。 僅支援 ms-appx 和 ms-resource。 不支援所有其他專案（ms-appdata、HTTP、C：等等）。
Loop boolean false 如果音效應該在快顯通知顯示期間重複播放，則設定為 true；若只播放一次，則設定為 false （預設值）。
Silent boolean false True 是表示 將音效設為靜音;false 表示允許快顯通知音效播放 （預設值）。

ToastHeader

Creators Update 的新功能：自定義標頭，可在控制中心內將多個通知群組在一起。

Property 類型 Required Description
Id 字串 true 開發人員建立的標識碼，可唯一識別此標頭。 如果兩個通知具有相同的標題 ID，它們會顯示在行動中心的相同標題下方。
Title 字串 true 標頭的標題。
Arguments 字串 true 取得或設定開發人員定義的參數字串，當使用者按一下此標頭時，會傳回給應用程式。 不可為空值。
ActivationType ToastActivationType false 取得或設定在點擊時，該標頭將使用的啟動類型。 預設為 Foreground。 請注意，只支援前景和通訊協定。
ActivationOptions ToastActivationOptions false 取得或設定有關啟用通知標題的其他選項。
  • Last updated on