應用程式通知內容

發行項
04/01/2024

應用程式通知是具有文字、影像和按鈕/輸入的靈活通知。本文說明可用於應用程式通知的 UI 元素，並提供用於產生應用程式通知的 XML 格式的程式碼範例。

注意

「快顯通知」一詞正取代為「應用程式通知」。這些詞彙都是指 Windows 的相同功能，但隨著時間推移，我們將逐步淘汰文件中的「快顯通知」使用。

開始使用

應用程式通知是使用 XML 承載定義的，該承載由應用程式通知結構描述定義。目前，有三種方式可在應用程式通知中產生 XML 承載。本文中的程式碼範例會示範這三種方法：

Microsoft.Windows.AppNotifications.Builder API - 在 Windows App SDK 1.2 中引入，此命名空間提供的 API 可讓您以程式設計方式輕鬆建立通知的 XML 有效負載，而不必擔心 XML 格式的具體情況。使用這些 API 的程式代碼範例位於標示為「Windows 應用程式 SDK」的索引標籤中。
Microsoft.Toolkit.Uwp.Notifications 產生器語法 - 這些 API 是 UWP Community Toolkit 的一部分，並為 UWP 應用程式提供支援。儘管這些 API 也可用於 Windows App SDK 應用程序，並且繼續受支持，但我們建議新實作使用 Microsoft.Windows.AppNotifications.Builder API。若要使用 Community Toolkit API，請將 UWP Community Toolkit 通知 Nuget 套件新增至專案中。本文提供的 C# 範例是使用 NuGet 套件 7.0.0 版。使用這些 API 的程式代碼範例位於標示為「Windows 社群工具組」的索引標籤中。
原始 XML - 如果您想要，您可以建立自己的自訂程式代碼，以所需的格式產生 XML 字串。原始 XML 範例位於標示為「XML」的索引標籤中。

安裝通知視覺化工具。 這款免費的 Windows 應用程式可在您編輯快顯通知時提供即時視覺預覽，從而幫助您設計互動式應用程式通知，類似於 Visual Studio 的 XAML 編輯器/設計檢視。如需詳細資訊，請參閱通知視覺化工具，或從商店下載通知視覺化工具。

本文僅介紹建立應用程式通知內容。有關在產生 XML 負載後發送通知的資訊，請參閱傳送本機應用程式通知。

應用程式通知結構

應用程式通知 XML 承載的一些重要、高階元件包括：

快顯通知：此元素的 launch 屬性定義了當使用者點擊您的 toast 時將傳遞回應用程式的參數，讓您深入瞭解快顯通知所顯示的正確內容。若要深入了解，請參閱傳送本機應用程式通知。
視覺效果：此元素表示快顯通知的視覺部分，包括包含文字和影像的泛型系結。
動作：此元素代表快顯通知的互動式部分，包括輸入和動作。
音訊：此元素會指定向用戶顯示快顯通知時播放的音訊。

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", "9813")

    .AddText("Some text")

    .AddButton(new AppNotificationButton("Archive")
        .AddArgument("action", "archive"))

    .SetAudioUri(new Uri("ms-appx:///Sound.mp3"));

var builder = new ToastContentBuilder()
    .AddArgument("conversationId", 9813)

    .AddText("Some text")

    .AddButton(new ToastButton()
        .SetContent("Archive")
        .AddArgument("action", "archive"))

    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast launch='conversationId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Some text</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
    <actions>
        <action content='Archive' arguments='action=archive'/>
    </actions>
</toast>

以下是應用程式通知內容的視覺表示法：

應用程式通知的螢幕截圖，頂部帶有歸因區域的標籤，顯示應用程式圖示和應用程式名稱 Notifications Visualizer。畫面的中間部分被標記為可視區域，其中包括三行文字。畫面的底部被標記為操作區域，並包含兩個標記為「接受」和「拒絕」的按鈕。

屬性區域

屬性區域位於應用程式通知的頂端。從 Windows 11 開始，您的應用程式名稱和圖示會顯示在此區域中。歸因區域還包括一個關閉按鈕 (允許用戶快速關閉通知) 和一個省略符號功能表 (允許用戶快速停用應用程式的通知，或前往 Windows 設定頁面以取得應用程式的通知)。屬性區域是由殼層所設定，而且無法在快顯通知 XML 承載中覆寫，不過您的應用程式可以將項目新增至屬性區域內容功能表。如需詳細資訊，請參閱內容功能表動作。

視覺效果

每個應用程式通知都必須指定一個視覺效果元素，您必須在其中提供通用的 Toast 綁定，並且可以包含文字和圖像。這些元素將會在各種 Windows 裝置上轉譯，包括桌上型電腦、手機、平板電腦和 Xbox。

有關視覺效果區段及其子元素中支援的所有屬性，請參閱應用程式通知結構描述。

文字元素

每個應用程式通知必須至少有一個文字元素，並且可以包含兩個附加文字元素，均為 AdaptiveText 類型。

包含三行文字的應用程式通知的螢幕截圖。文字的首行是粗體。

自 Windows 10 Anniversary Update 以來，您可以透過使用文字上的 HintMaxLines 屬性來控制顯示的文字行數。預設 (也是最大) 標題文字最多為 2 行，兩個附加描述元素 (第二個和第三個) AdaptiveText 最多為 4 行 (組合)。

var builder = new AppNotificationBuilder()
    .AddArgument("conversationId", 9813)
    .AddText("Adaptive Tiles Meeting", new AppNotificationTextProperties().SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

var builder = new ToastContentBuilder()
    .AddArgument("meetingId", 9813)
    .AddText("Adaptive Tiles Meeting", hintMaxLines: 1)
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

<toast launch='meetingId=9813'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

內嵌影像

根據預設，影像會在任何文字元素之後內嵌顯示，以填滿視覺區域的完整寬度。

應用程式通知的螢幕截圖，顯示預設影像位置，內文，填滿可視區域的整個寬度。

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

AppNotificationManager.Default.Show(builder.BuildNotification());

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddInlineImage(new Uri("ms-appx:///Images/InlineImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image src='ms-appx:///Images/InlineImage.png'/>
        </binding>
    </visual>
</toast>

應用程式標誌覆寫

指定「appLogoOverride」的放置值將導致影像顯示在視覺區域左側的方塊中。此屬性的名稱反映了先前版本的 Windows 中的行為，其中圖像將取代預設的應用程式標誌影像。在 Windows 11 中，應用程式標誌顯示在歸因區域中，因此它不會被 appLogoOverride 影像放置覆寫。

100% 縮放時影像維度為 48x48 像素。我們通常建議為每個縮放比例提供各圖示資產的版本：100%、125%、150%、200% 和 400%。

應用程式通知的螢幕截圖，顯示應用程式標誌覆蓋通知可視區域左側正方形中的圖像位置。

var builder = new AppNotificationBuilder()
    .AddText("Featured image of the day.")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

var builder = new ToastContentBuilder()
    .AddText("Featured image of the day.")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/AppLogo.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Featured image of the day.</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/AppLogo.png'/>
        </binding>
    </visual>
</toast>

提示裁剪

Microsoft 樣式指南建議使用圓形影像來代表個人檔案圖片，以在應用程式和殼層之間提供一致的人員表示法。將 HintCrop 屬性設為 Circle 以使用圓形裁剪渲染影像。

應用程式通知的螢幕截圖，顯示應用程式標誌覆蓋圖像位置，裁剪成畫面可視區域左側的圓圈。

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), AppNotificationImageCrop.Circle);

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddAppLogoOverride(new Uri("ms-appx:///Images/Profile.png"), ToastGenericAppLogoCrop.Circle);

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
            <image placement='appLogoOverride' src='ms-appx:///Images/Profile.png' hint-crop='circle'/>
        </binding>
    </visual>
</toast>

主角圖像

Anniversary Update 中的新增功能：應用程式通知可以顯示主角圖像，這是一個精選 ToastGenericHeroImage，在 toast 橫幅和通知中心內醒目顯示。 100% 縮放時影像維度為 364x180 像素。

應用程式通知的螢幕截圖，顯示歸因區域上方的英雄圖像位置。

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Mary Anne</text>
            <text>Check out where we camped last night!</text>
            <image placement='hero' src='ms-appx:///Images/HeroImage.png'/>
        </binding>
    </visual>
</toast>

影像大小限制

您在快顯通知中使用的影像可以來自...

http://
ms-appx:///
ms-appdata:///

對於 http 和 https 遠端 Web 影像，每個影像的檔案大小都有限制。在 Fall Creators Update (16299) 中，我們將正常連線的限制增加到 3 MB，以計量連接的限制增加到 1 MB。在此之前，影像一律限制為 200 KB。

一般連線	計量連線	Fall Creators Update 之前
3 MB	1 MB	200 KB

如果圖像超出檔案大小、下載失敗或逾時，則該圖像將會刪除，並顯示通知的其餘部分。

屬性文字

Anniversary Update 中的新增功能：如果您需要引用內容來源，可以使用歸屬文字。該文字始終顯示在所有文字元素下方、內嵌圖像上方。文字會使用比標準文字元素稍微小一點的大小，以與一般文字元素區分開來。

在不支援屬性文字的舊版 Windows 上，文字只會簡單地顯示為另一個文字元素 (假設您還沒有最多三個文字元素)。

一張顯示畫面通知的截圖，顯示在畫面的視覺區域的其他文字下方的屬性文字「via SMS」。

var builder = new AppNotificationBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .SetAttributionText("via SMS");
    .SetHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

new ToastContentBuilder()
    .AddText("Marry Anne")
    .AddText("Check out where we camped last night!")
    .AddAttributionText("Via SMS");
    .AddHeroImage(new Uri("ms-appx:///Images/HeroImage.png"));

<toast>  
  <visual>
    <binding template="ToastGeneric">
      <image src="ms-appx:///Images/HeroImage.png"/>
      <text>Mary Anne</text>
      <text>Check out where we camped last night!</text>
      <text placement="attribution">Via SMS</text>
    </binding>
  </visual>
</toast>

自訂時間戳記

Creators Update 中的新增功能：您現在可以使用自己的時間戳覆蓋系統提供的時間戳，該時間戳準確表示訊息/資訊/內容的產生時間。此時間戳會顯示在通知中心內。

Notifications Center 中一個通知的截圖，顯示自訂的時間戳記。

若要深入瞭解如何使用自定義時間戳，請參閱快顯通知上的自定義時間戳。

var builder = new AppNotificationBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .SetTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

var builder = new ToastContentBuilder()
    .AddText("Matt sent you a friend request")
    .AddText("Hey, wanna dress up as wizards and ride around on hoverboards?")
    .AddCustomTimeStamp(new DateTime(2017, 04, 15, 19, 45, 00, DateTimeKind.Utc));

<toast displayTimestamp='2017-04-15T12:45:00-07:00'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Matt sent you a friend request</text>
            <text>Hey, wanna dress up as wizards and ride around on hoverboards?</text>
        </binding>
    </visual>
</toast>

進度列

Creators Update 中的新增功能：您可以在應用程式通知上提供進度列，以便讓使用者了解下載等作業的進度。

顯示進度條列的畫面通知的螢幕截圖。

若要深入瞭解如何使用進度列，請參閱快顯通知進度列。

標題

Creators Update 中的新增功能：您可以在通知中心內的標頭下將通知分組。例如，您可以將群組聊天中的訊息分組到標頭下，或將常見主題的通知分組到標頭下。

操作中心的螢幕截圖，顯示應用程式 Notifications Viewer 的多個通知，這些通知被彙整在標有「露營！」的標題下。

若要深入瞭解如何使用標頭，請參閱快顯通知標頭。

調適型內容

Anniversary Update 中的新增內容：除了上面指定的內容之外，您還可以顯示當快顯通知展開時可見的其他自適應內容。

此附加內容是使用 Adaptive 指定的，您可以閱讀調適型磚文件進一步瞭解。

請注意，任何自適應內容都必須包含在 AdaptiveGroup 中。否則將不會使用自適應進行渲染。

欄和文字元素

以下是使用欄和一些進階自適應文字元素的範例。由於文字元素位於 AdaptiveGroup 內，因此它們支援所有豐富的自適應樣式屬性。

畫面通知的螢幕截圖，顯示與畫面視覺區域左側和右側對齊的文字元素群組。

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support adaptive text elements.

new ToastContentBuilder()
    ...
    
    .AddVisualChild(new AdaptiveGroup()
    {
        Children =
        {
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "52 attendees",
                        HintStyle = AdaptiveTextStyle.Base
                    },
                    new AdaptiveText()
                    {
                        Text = "23 minute drive",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            },
            new AdaptiveSubgroup()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "1 Microsoft Way",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    },
                    new AdaptiveText()
                    {
                        Text = "Bellevue, WA 98008",
                        HintStyle = AdaptiveTextStyle.CaptionSubtle,
                        HintAlign = AdaptiveTextAlign.Right
                    }
                }
            }
        }
    });

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <text>Reminder: Windows Launch Party</text>
      <text>4:00 PM, 10/21/2021</text>
      <group>
        <subgroup>
          <text hint-style="base">52 attendees</text>
          <text hint-style="captionSubtle">23 minute drive</text>
        </subgroup>
        <subgroup>
          <text hint-style="captionSubtle" hint-align="right">1 Microsoft Way</text>
          <text hint-style="captionSubtle" hint-align="right">Bellevue, WA 98008</text>
        </subgroup>
      </group>
    </binding>
  </visual>
</toast>

按鈕

按鈕可讓您的快顯通知具有互動性，讓使用者可以對您的應用程式通知快速執行操作，而無需中斷目前的工作流程。例如，使用者可以直接從快顯通知中回覆訊息，或者甚至無需打開電子郵件應用程式即可刪除電子郵件。按鈕會出現在通知的展開部分。

要了解有關端對端實作按鈕的更多資訊，請參閱傳送本機快顯通知。

按鈕可以透過下列方式啟動應用程式：

該應用程式在前台激活，並帶有可用於瀏覽到特定頁面/內容的引數。
另一個應用程式會透過通訊協定啟動來啟動。
UWP 應用程式明確支援背景啟動。對於 Windows App SDK 應用程序，該應用程式一律會在前景啟動。應用程式可以呼叫 AppInstance.GetActivatedEventArgs 來偵測啟動是否由通知啟動，並根據傳遞的引數決定是完全啟動前景應用程式還是僅處理通知並退出。
UWP 應用程式和 Windows 應用程式 SDK 都支援系統動作，例如延遲或關閉通知。 AppNotificationBuilder API 不支援此場景，但 Windows App SDK 應用程式可以使用 Microsoft.Windows.AppNotifications.Builder API 或原始 XML 實作此場景。

注意

您最多只能有 5 個按鈕 (包括我們稍後將討論的內容功能表項目)。

畫面通知的螢幕截圖顯示一行文字，後面是一行由操作元素設定的兩個按鈕」。

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("New product in stock!")
        .AddButton(new AppNotificationButton("See more details")
            .AddArgument("action", "viewDetails"))
            .AddArgument("contentId", "351")
        .AddButton(new AppNotificationButton("Remind me later")
            .AddArgument("action", "remindLater"))
            .AddArgument("contentId", "351");

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("See more details")
        .AddArgument("action", "viewDetails"))

    .AddButton(new ToastButton()
        .SetContent("Remind me later")
        .AddArgument("action", "remindLater"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>New product in stock!</text>
        </binding>
    </visual>
      <actions>
          <action content='See more details' arguments='action=viewDetails;contentId=351'/>
          <action content='Remind me later' arguments='action=remindLater;contentId=351'/>
      </actions>
</toast>

具有圖示的按鈕

您可以將圖示新增至按鈕。這些圖標是 100% 縮放的白色透明 16x16 像素圖像，圖像本身不應包含任何邊框間距。如果您選擇在快顯通知通知上提供圖標，則必須為通知中的所有按鈕提供圖標，因為它將按鈕的樣式轉換為圖標按鈕。

注意

為了便於訪問，請確保包含圖示的對比白色版本 (白色背景的黑色圖示)，以便當使用者開啟高對比度白色模式時，您的圖示可見。如需其他資訊，請參閱對語言、縮放比例及高對比的磚與快顯通知支援。

new ToastContentBuilder()
    var builder = new AppNotificationBuilder()
        .AddText("Return books to the library.")
        .AddButton(new AppNotificationButton("Accept")
            .AddArgument("action", "accept")
            .SetIcon(new Uri("ms-appx:///Images/Accept.png")))
        .AddButton(new AppNotificationButton("Snooze")
            .AddArgument("action", "snooze")
            .SetIcon(new Uri("ms-appx:///Images/Snooze.png")))
        .AddButton(new AppNotificationButton("Dismiss")
            .AddArgument("action", "dismiss")
            .SetIcon(new Uri("ms-appx:///Images/Dismiss.png")));

var builder = new ToastContentBuilder()
    .AddText("New product in stock!")
    .AddButton(new ToastButton()
        .SetContent("Accept")
        .AddArgument("action", "accept")
        .SetImageUri(new Uri("ms-appx:///Images/Accept.png")))
    .AddButton(new ToastButton()
        .SetContent("Snooze")
        .AddArgument("action", "snooze")
        .SetImageUri(new Uri("ms-appx:///Images/Snooze.png")))
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss")
        .SetImageUri(new Uri("ms-appx:///Images/Dismiss.png")));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Return books to the library.</text>
        </binding>
    </visual>
    <actions>
        <action content='Accept' arguments='action=accept' imageUri='ms-appx:///Assets/Accept.png'/>
        <action content='Snooze' arguments='action=snooze' imageUri='ms-appx:///Assets/Snooze.png'/>
        <action content='Dismiss' arguments='action=dismiss' imageUri='ms-appx:///Assets/Dismiss.png'/>
    </actions>
</toast>

Windows 11 Update 中的新增功能：您可以使用 XML 中的 Hint ToolTip 屬性為圖示新增工具提示。如果您的按鈕有圖示但沒有內容，這是理想的選擇，因為這將確保您可以傳遞 Windows 朗讀程式可以閱讀的文字。但是，如果存在內容，則朗讀程式將讀取該內容，無論工具提示中傳遞的內容是什麼。

var button = new AppNotificationButton("Reply")
    .AddArgument("action", "reply");

if (AppNotificationButton.IsToolTipSupported())
{
    button.ToolTip = "Click to reply.";
}

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .AddButton(button);

// The Community Toolkit builder syntax does not currently support icon tooltips.

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Reply' arguments='action=reply' hint-toolTip='Click to reply'/>
    </actions>
</toast>

具有色彩的按鈕

Windows 11 Update 中的新增功能：您可以透過將 useButtonStyle 屬性新增至快顯通知 XML 元素，並將hint-buttonStyle 屬性新增至操作 XML 元素來為按鈕新增紅色或綠色，如下所示。

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .AddText("Incoming Call - Mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///Images/Profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Video Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Video.png"))
        .AddArgument("videoId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Answer Phone Call")
        .SetButtonStyle(AppNotificationButtonStyle.Success)
        .SetIcon(new Uri("ms-appx:///Images/Call.png"))
        .AddArgument("callId", "123"))
    .AddButton(new AppNotificationButton()
        .SetToolTip("Hang Up")
        .SetButtonStyle(AppNotificationButtonStyle.Critical)
        .SetIcon(new Uri("ms-appx:///Images/HangUp.png"))
        .AddArgument("hangUpId", "123"));

// The WIndows Community Toolkit builder syntax does not currently support red and green button colors.

<toast scenario='incomingCall' useButtonStyle='true'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>Incoming Call - Mobile</text>
            <image src='ms-appx:///Images/InlineImage.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='' 
            arguments='videoId=123' 
            imageUri='ms-appx:///Images/Video.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Video Call'/>
        <action 
            content='' 
            arguments='callId=123' 
            imageUri='ms-appx:///Images/Call.png' 
            hint-buttonStyle='Success' 
            hint-toolTip='Answer Phone Call'/>
        <action 
            content='' 
            arguments='hangUpId=123' 
            imageUri='ms-appx:///Images/HangUp.png' 
            hint-buttonStyle='Critical' 
            hint-toolTip='Hang Up'/>
    </actions>
</toast>

Anniversary Update 中的新增功能：您可以在使用者右鍵點擊快顯通知或選擇上下文功能表圖示時出現的現有上下文功能表，新增其他上下文功能表動作。

注意

在較舊的裝置上，這些附加的上下文功能表動作將僅只會顯示為通知上的一般按鈕。

您新增的其他上下文功能表動作 (例如「將群組聊天靜音 1 小時」) 將顯示在兩個預設系統項目上方。

var builder = new AppNotificationBuilder()
    .AddText("Camping this weekend?")
    .SetAppLogoOverride(new Uri("ms-appx:///images/Reply.png"), AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Mute group chat for 1 hour")
        .AddArgument("action", "mute")
        .SetContextMenuPlacement());

Windows Community Toolkit 生產器語法目前不支援上下文功能表操作，因此建議使用初始設定語法。

ToastContent content = new ToastContent()
{
    ...
 
    Actions = new ToastActionsCustom()
    {
        ContextMenuItems =
        {
            new ToastContextMenuItem("Mute group chat for 1 hour", "action=muteId")
        }
    }
};

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Camping this weekend?</text>
            <image placement='appLogoOverride' src='ms-appx:///images/Reply.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action content='Mute group chat for 1 hour' arguments='action=mute' placement='contextMenu'/>
    </actions>
</toast>

注意

附加上下文功能表項目在快顯通知上有 5 個按鈕的總數限制。

附加上下文選單項目的啟動處理方式與快顯通知按鈕相同。

輸入

輸入在應用程式通知的動作區域中指定，這表示只有在展開通知時才會顯示這些輸入。

快速回覆文字方塊

若要啟用快速回覆文字方塊 (例如，在訊息傳遞應用程式中)，請新增文字輸入和按鈕，並引用文字輸入欄位的識別碼，以便在輸入欄位旁邊顯示。按鈕的可選圖示 (如果提供) 應為 32x32 像素影像，沒有邊框間距、白色像素設定為透明且縮放比例為 100%。

一個帶有個人頭像和幾行文字的畫面通知的截圖。該截圖還包括一個用於直接輸入文字的對話框，以及一個發送回覆的按鈕。

var builder = new AppNotificationBuilder()
    .AddTextBox("textBox", "Type a reply", "Reply")
    .AddButton(AppNotificationButton("Send")
        .AddArguments("action", "Send")
        .SetInputId("textBox"))
    .BuildNotification();

var builder = new ToastContentBuilder()
    .AddInputTextBox("tbReply", "Type a reply")
        .AddButton(new ToastButton()
        .SetContent("Reply")
        .SetTextBoxId("tbReply") // To place button next to text box, reference text box's id
        .SetImageUri(new Uri("Assets/Reply.png", UriKind.Relative))
        .AddArgument("action", "reply"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Send"
      arguments="action=reply&amp;convId=9318"
      hint-inputId="textBox"
      imageUri="Assets/Reply.png"/>
  </actions>
</toast>

具有按鈕列的輸入

您也可以擁有一個 (或多個) 輸入，並在輸入下方顯示一般按鈕。

一個應用程式通知的截圖，顯示一行文字、一個對話框和一行上有兩個為「回覆」和「視訊通話」的按鍵。

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support quick reply text boxes.

new ToastContentBuilder()
    ...
    
    .AddInputTextBox("tbReply", "Type a reply")

    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply"))

    .AddButton(new ToastButton()
        .SetContent("Video call")
        .AddArgument("action", "videoCall"));

<toast launch="app-defined-string">
  <visual>
    <binding template="ToastGeneric">
      <image placement="appLogoOverride" hint-crop="circle" src="https://picsum.photos/48?image=883"/>
      <text>Andrew Bares</text>
      <text>Shall we meet up at 8?</text>
    </binding>
  </visual>
  <actions>
    <input id="textBox" type="text" placeHolderContent="Type a reply"/>
    <action
      content="Reply"
      arguments="action=reply&amp;threadId=9218"/>
    <action
      content="Video call"
      arguments="action=videocall&amp;threadId=9218"
      activationType="foreground"/>
  </actions>
</toast>

選取輸入

除了文字方塊之外，您還可以使用選取選單。

一個應用程式通知的截圖，顯示一行文字、一個選擇輸入，其中「午餐」被勾選，還有一行上有兩個按鍵為「預訂」和「聯繫餐廳」。

var builder = new AppNotificationBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddComboBox(new AppNotificationComboBox("time")
        .SetTitle("Select an item:")
        .AddItem("breakfast", "Breakfast")
        .AddItem("lunch", "Lunch")
        .AddItem("dinner", "Dinner")
        .SetSelectedItem("lunch"))
    .AddButton(new AppNotificationButton("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement())
    .AddButton(new AppNotificationButton("Call restaurant")
        .AddArgument("action", "videocall")
        .AddArgument("threadId", "9218")
        .SetContextMenuPlacement());

var builder = new ToastContentBuilder()
    .AddText("4th coffee?")
    .AddText("When do you plan to come in tomorrow?")
    .AddToastInput(new ToastSelectionBox("time")
    {
        DefaultSelectionBoxItemId = "lunch",
        Items =
            {
                new ToastSelectionBoxItem("breakfast", "Breakfast"),
                new ToastSelectionBoxItem("lunch", "Lunch"),
                new ToastSelectionBoxItem("dinner", "Dinner")
            }
    })
    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply")
        .AddArgument("threadId", "9218"))
    .AddButton(new ToastButton()
        .SetContent("Call restaurant")
        .AddArgument("action", "videoCall")
        .AddArgument("threadId", "9218"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>4th coffee?</text>
            <text>When do you plan to come in tomorrow?</text>
        </binding>
    </visual>
    <actions>
        <input id='time' type='selection' title='Select an item:' defaultInput='lunch'>
            <selection id='breakfast' content='Breakfast'/><selection id='dinner' content='Dinner'/>
            <selection id='lunch' content='Lunch'/>
        </input>
        <action content='Reply' arguments='action=reply;threadId=9218' placement='contextMenu'/>
        <action content='Call Restaurant' arguments='action=videocall;threadId=9218' placement='contextMenu'/>
    </actions>
</toast>

延遲/關閉

使用選取選單和兩個按鈕，我們可以建立一個利用系統延遲和關閉動作的提醒通知。確保將場景設為「提醒」，以使通知表現得像提醒一樣。

一個應用程式通知的截圖，顯示幾行文字描述了一個會議的時間和地點。一個對話框中勾選了「15 分鐘」，還有標籤為「稍後提醒」和「忽略」的按鍵。

使用快顯通知按鈕上的 SelectionBoxId 屬性將「延遲」按鈕連結到選取選單輸入。

Microsoft.Windows.AppNotifications.Builder 語法目前不支援系統啟動。但 Windows App SDK 應用程式支援此場景，您可以使用 Microsoft.Toolkit.Uwp.Notifications API 或原始 XML 為此場景建立通知。

// The Microsoft.Windows.AppNotifications.Builder syntax does not currently support system activation. 
// But this scenario is supported for Windows App SDK apps, and you can build notifications for this 
// scenario using the `Microsoft.Toolkit.Uwp.Notifications` APIs or raw XML.

new ToastContentBuilder()
    .SetToastScenario(ToastScenario.Reminder)
    
    ...
    
    .AddToastInput(new ToastSelectionBox("snoozeTime")
    {
        DefaultSelectionBoxItemId = "15",
        Items =
        {
            new ToastSelectionBoxItem("5", "5 minutes"),
            new ToastSelectionBoxItem("15", "15 minutes"),
            new ToastSelectionBoxItem("60", "1 hour"),
            new ToastSelectionBoxItem("240", "4 hours"),
            new ToastSelectionBoxItem("1440", "1 day")
        }
    })

    .AddButton(new ToastButtonSnooze() { SelectionBoxId = "snoozeTime" })
    .AddButton(new ToastButtonDismiss());

<toast>
  <visual>
    <binding template="ToastGeneric">
      <text hint-maxLines="1">Adaptive Tiles Meeting</text>
      <text>Conf Room 2001 / Building 135</text>
      <text>10:00 AM - 10:30 AM</text>
    </binding>
  </visual>
  <actions>
    <input id="snoozeTime" type="selection" defaultInput="15">
      <selection id="1" content="1 minute"/>
      <selection id="15" content="15 minutes"/>
      <selection id="60" content="1 hour"/>
      <selection id="240" content="4 hours"/>
      <selection id="1440" content="1 day"/>
    </input>
    <action activationType="system" arguments="snooze" hint-inputId="snoozeTime" content="" />
    <action activationType="system" arguments="dismiss" content=""/>
  </actions>
</toast>

若要使用系統延遲與關閉動作：

指定 ToastButtonSnooze 或 ToastButtonDismiss
選擇指定自訂內容字串：
如果您未提供字串，我們將自動使用當地語系化字串來表示「Snooze」和「Dismiss」。
選擇性指定 SelectionBoxId：
如果您不希望使用者選擇延遲間隔，而只是希望通知在系統定義的時間間隔內僅暫停一次 (在整個作業系統中保持一致)，則完全不要建構任何<輸入>。
若要提供延遲間隔選擇： - 在延遲作業中指定 SelectionBoxId - 比對輸入的識別碼與延遲動作的 SelectionBoxId - 將 ToastSelectionBoxItem 的值指定為非負整數，以表示延遲間隔 (以分鐘為單位)。

音訊

行動裝置始終支援自訂音訊，桌面版本 1511 (版本 10586) 或更高版本也支援自訂音訊。您可以透過下列路徑參考自訂音訊：

ms-appx:///
ms-appdata:///

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioUri(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-appx:///Audio/NotificationSound.mp3"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-appx:///Audio/NotificationSound.mp3'/>
</toast>

或者，您可以從 ms-winsoundevents 清單中進行選擇，這兩個平台始終支援該清單。

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetAudioEvent(AppNotificationSoundEvent.Alarm, AppNotificationAudioLooping.Loop);

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .AddAudio(new Uri("ms-winsoundevent:Notification.Looping.Alarm"));

<toast>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <audio src='ms-winsoundevent:Notification.Looping.Alarm' loop='true'/>
</toast>

有關應用程式通知中音訊的資訊，請參閱音訊結構描述頁面。若要了解如何傳送使用自訂音訊的應用程式通知，請參閱快顯通知上的自訂音訊。

案例

若要建立重要的通知、鬧鐘、提醒和來電通知，您只需使用一般的應用程式通知，並為其指派場景值即可。該場景調整了一些行為，以建立一致且統一的使用者體驗。可能的場景值有四個：

Reminder
鬧鐘
IncomingCall
緊急

提醒

在提醒場景中，通知將保留在螢幕上，直到使用者將其關閉或採取動作。在 Windows Mobile 上，應用程式通知也會以預先展開的方式顯示。將會播放提醒音效。您必須在應用程式通知上提供至少一個按鈕。否則，系統會將該通知視為一般通知。

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Reminder);

var builder = new ToastContentBuilder()
    .AddText("Notification text.")
    .SetToastScenario(ToastScenario.Reminder)

<toast scenario='reminder'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
</toast>

警示

鬧鐘的行為與提醒相同，但鬧鐘還會循環播放預設鬧鐘音效。您必須在應用程式通知上提供至少一個按鈕。否則，系統會將該通知視為一般通知。

var builder = new AppNotificationBuilder()
    .AddText("Notification text.")
    .SetScenario(AppNotificationScenario.Alarm)
    .AddButton(new AppNotificationButton("Dismiss")
        .AddArgument("action", "dismiss"));

var builder = new ToastContentBuilder()
    .AddText("Notification text")
    .SetToastScenario(ToastScenario.Alarm)
    .AddButton(new ToastButton()
        .SetContent("Dismiss")
        .AddArgument("action", "dismiss"));

<toast scenario='alarm'>
    <visual>
        <binding template='ToastGeneric'>
            <text>Notification text.</text>
        </binding>
    </visual>
    <actions>
        <action content='Dismiss' arguments='action=dismiss'/>
    </actions>
</toast>

來電

來電通知會以特殊的通話格式預先展開顯示，並保留在使用者螢幕上直至消失。預設情況下，鈴聲音訊將循環播放。在 Windows Mobile 裝置上，它們會顯示全螢幕顯示。

來電畫面通知

var builder = new AppNotificationBuilder()
    .SetScenario(AppNotificationScenario.IncomingCall)
    .AddText("Andrew Bares", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
    .AddText("incoming call - mobile", new AppNotificationTextProperties()
        .SetIncomingCallAlignment())
      .SetInlineImage(new Uri("ms-appx:///images/profile.png"),
        AppNotificationImageCrop.Circle)
    .AddButton(new AppNotificationButton("Text reply")
        .SetToolTip("Text reply")
        .SetIcon(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new AppNotificationButton("Reminder")
        .SetToolTip("Reminder")
        .SetIcon(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new AppNotificationButton("Ignore")
        .SetToolTip("Ignore")
        .SetIcon(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new AppNotificationButton("Answer")
        .SetToolTip("Answer")
        .SetIcon(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

var builder = new ToastContentBuilder()
    .SetToastScenario(ToastScenario.IncomingCall)
    .AddText("Andrew Bares")
    .AddText("incoming call - mobile")
    .AddInlineImage(new Uri("ms-appx:///images/profile.png"), 
        "Andrew Bares",
        null,
        AdaptiveImageCrop.Circle)
    .AddButton(new ToastButton()
        .SetContent("Text reply")
        .SetImageUri(new Uri("ms-appx:///images/reply.png"))
        .AddArgument("textId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Reminder")
        .SetImageUri(new Uri("ms-appx:///images/reminder.png"))
        .AddArgument("reminderId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Ignore")
        .SetImageUri(new Uri("ms-appx:///images/ignore.png"))
        .AddArgument("ignoreId", "123"))
    .AddButton(new ToastButton()
        .SetContent("Answer")
        .SetImageUri(new Uri("ms-appx:///images/answer.png"))
        .AddArgument("answerId", "123"));

<toast scenario='incomingCall'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-callScenarioCenterAlign='true'>Andrew Bares</text>
            <text hint-callScenarioCenterAlign='true'>incoming call - mobile</text>
            <image src='ms-appx:///images/profile.png' hint-crop='circle'/>
        </binding>
    </visual>
    <actions>
        <action 
            content='Text reply' 
            arguments='textId=123' 
            imageUri='ms-appx:///images/reply.png' 
            hint-toolTip='Text reply'/>
        <action 
                content='Reminder' 
                arguments='reminderId=123' 
                imageUri='ms-appx:///images/reminder.png' 
                hint-toolTip='Reminder'/>
        <action 
                content='Ignore' 
                arguments='ignoreId=123' 
                imageUri='ms-appx:///images/ignore.png' 
                hint-toolTip='Ignore'/>
        <action 
            content='Answer' 
            arguments='answerId=123' 
            imageUri='ms-appx:///images/answer.png' 
            hint-toolTip='Answer'/>
    </actions>
</toast>

重要通知

重要

需求：您必須執行 Windows Insider Preview Build 22546 或更新版本才能使用重要通知。

重要通知允許使用者更好地控制哪些第一方和第三方應用程式可以發送高優先順序應用程式通知 (緊急/重要)，突破專注輔助 (請勿打擾)。這可以在通知設定中修改。

一個緊急的應用程式通知的截圖，顯示在應用程式名稱旁邊有一個感歎號。圖像還顯示了系統發起的應用程式通知，提供按鍵讓使用者允許或拒絕該應用程式的緊急通知。

var builder = new AppNotificationBuilder()
    .AddText("Adaptive Tiles Meeting", 
        new AppNotificationTextProperties()
            .SetMaxLines(1))
    .AddText("Conf Room 2001 / Building 135")
    .AddText("10:00 AM - 10:30 AM");

if (AppNotificationBuilder.IsUrgentScenarioSupported())
{
    builder.SetScenario(AppNotificationScenario.Urgent);
}

// The builder syntax does not support important notifications yet.

<toast scenario='urgent'>
    <visual>
        <binding template='ToastGeneric'>
            <text hint-maxLines='1'>Adaptive Tiles Meeting</text>
            <text>Conf Room 2001 / Building 135</text>
            <text>10:00 AM - 10:30 AM</text>
        </binding>
    </visual>
</toast>

當地語系化和協助工具

您的磚和應用程式通知可以載入針對顯示語言、顯示縮放比例、高對比度和其他運行階段內容量身打造的字串和影像。如需其他資訊，請參閱對語言、縮放比例及高對比的磚與快顯通知支援。

處理啟用

若要了解如何處理應用程式啟用 (使用者點擊快顯通知或快顯通知上的按鈕)，請參閱傳送本機快顯通知。

共用方式為

應用程式通知內容

開始使用

應用程式通知結構

屬性區域

視覺效果

文字元素

內嵌影像

應用程式標誌覆寫

提示裁剪

主角圖像

影像大小限制

屬性文字

自訂時間戳記

進度列

標題

調適型內容

欄和文字元素

按鈕

具有圖示的按鈕

具有色彩的按鈕

內容功能表動作

輸入

快速回覆文字方塊

具有按鈕列的輸入

選取輸入

延遲/關閉

音訊

案例

提醒

警示

來電

重要通知

當地語系化和協助工具

處理啟用

其他資源

共用方式為

應用程式通知內容

開始使用

應用程式通知結構

屬性區域

視覺效果

文字元素

內嵌影像

應用程式標誌覆寫

提示裁剪

主角圖像

影像大小限制

屬性文字

自訂時間戳記

進度列

標題

調適型內容

欄和文字元素

按鈕

具有圖示的按鈕

具有色彩的按鈕

內容功能表動作

輸入

快速回覆文字方塊

具有按鈕列的輸入

選取輸入

延遲/關閉

音訊

案例

提醒

警示

來電

重要通知

當地語系化和協助工具

處理啟用

相關主題

其他資源