アプリ通知の内容

[アーティクル]
12/29/2023

アプリ通知は、テキスト、画像、ボタン/入力を含むフレキシブルな通知です。この記事では、アプリ通知で使用できる UI 要素について説明し、アプリ通知の XML 形式を生成するコード例を示します。

Note

"トースト通知" という用語は、"アプリ通知" に置き換えられます。これらの用語はどちらも Windows の同じ機能を指していますが、時間の経過と共に、ドキュメントでの "トースト通知" の使用を段階的に廃止します。

作業の開始

アプリ通知は、アプリ通知スキーマによって定義される XML ペイロードで定義されます。現在、アプリ通知用の XML ペイロードを生成する方法は 3 つあります。この記事のコード例では、次の 3 つのメソッドすべてを示します。

Microsoft.Windows.AppNotifications.Builder API - Windows アプリ SDK 1.2 で導入されたこの名前空間では、XML 形式の詳細を気にすることなく、プログラムで通知用の XML ペイロードを簡単に構築できる API を提供します。これらの API を使用するコード例は、"Windows アプリ SDK" というラベルのタブにあります。
ビルダー構文 Microsoft.Toolkit.Uwp.Notifications - これらの API は UWP Community Toolkit の一部であり、UWP アプリのサポートを提供します。これらの API は Windows アプリ SDK アプリにも使用でき、引き続きサポートされますが、新しい実装では Microsoft.Windows.AppNotifications.Builder API を使用することをお勧めします。 Community Toolkit API を使用するには、UWP Community Toolkit Notifications nuget パッケージをプロジェクトに追加します。この記事で示している C# のサンプルでは、NuGet パッケージのバージョン 7.0.0 を使っています。これらの API を使用するコード例は、"Windows Community Toolkit" というラベルのタブにあります。
未加工 XML - 必要に応じて、必要な形式で XML 文字列を生成する独自のカスタムコードを作成できます。生の XML の例は、"XML" というラベルのタブにあります。

Notifications Visualizer をインストールします。 この無料の Windows アプリは、Visual Studio の XAML エディターまたはデザインビューと同様、トーストの編集時に視覚的なプレビューが即座に表示されるため、対話型アプリ通知のデザインに便利です。詳細については、「通知ビジュアライザー」を参照するか、ストアから Notifications Visualizer をダウンロードしてください。

この記事では、アプリ通知コンテンツの作成について説明します。 XML ペイロードを生成した後に通知を送信する方法については、「ローカルアプリ通知を送信する」を参照してください。

アプリ通知の構造

アプリ通知 XML ペイロードの重要な高度なコンポーネントには、次のようなものがあります。

toast: この要素の launch 属性は、ユーザーがトーストをクリックしたときにアプリに渡される引数を定義します。これにより、トーストが表示されていた正しいコンテンツへのディープリンクが可能になります。詳細については、「ローカルアプリ通知を送信する」を参照してください。
visual: この要素は、テキストと画像を含む汎用バインディングを含んだトーストの視覚的な部分を表します。
actions: この要素は、入力やアクションを含む、トーストの対話型部分を表します。
audio: この要素は、トーストがユーザーに表示されるときに再生されるオーディオを指定します。

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>

アプリ通知の内容を視覚的に示します。

An screenshot of an app notification with labels for the attribution area at the top showing the app icon and and app name Notifications Visualizer. The middle part of the toast is labeled as the visual area, which includes three lines of text. The bottom section of the toast is labeled as the action area and contains two buttons labeled Accept and Decline.

帰属領域

属性領域は、アプリ通知の上部にあります。 Windows 11 以降では、アプリの名前とアイコンがこの領域に表示されます。属性領域には、ユーザーが通知をすぐに閉じることができる閉じるボタンと、ユーザーがアプリの通知をすぐに無効にしたり、アプリの通知の Windows 設定ページに移動したりできる省略記号メニューも含まれています。属性領域はシェルによって構成され、トースト XML ペイロードではオーバーライドできませんが、アプリは属性領域のコンテキストメニューに項目を追加できます。詳しくは、「コンテキストメニューのアクション」に関する記事をご覧ください。

ビジュアル

各アプリ通知では、ビジュアル要素を指定する必要があります。ここでは、汎用トーストバインドを指定する必要があり、テキストと画像を含めることができます。これらの要素は、デスクトップ、携帯電話、タブレット、Xbox など、さまざまな Windows デバイスでレンダリングされます。

visual セクションとその子要素でサポートされているすべての属性については、「アプリ通知スキーマ」を参照してください。

テキスト要素

各アプリ通知には少なくとも 1 つのテキスト要素が必要であり、AdaptiveText 型の 2 つの追加テキスト要素を含めることができます。

A screenshot of an app notification with three lines of text. The top line of text is bold.

Windows 10 Anniversary Update 以降では、テキストの HintMaxLines プロパティを使用して、表示されるテキストの行数を制御できます。既定 (および最大) は、タイトルに対して最大 2 行のテキスト、2 つの追加の説明要素 (2 番目と 3 番目の 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>

インラインイメージ

既定では、画像はテキスト要素の後にインラインで表示され、ビジュアル領域の全幅が埋め込まれます。

A screenshot of an app notification showing the default image placement, inline, filling the full width of the visual area.

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% のスケーリングで 48 x 48 ピクセルです。一般的には、バージョンに各倍率 (100%、125%、150%、200%、400%) に対応したアイコンアセットを提供することをお勧めします。

A screenshot of an app notification showing the app logo override image placement in a square on the left side of the visual area of the notification.

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 に設定して、円形のトリミングでイメージをレンダリングします。

A screenshot of an app notification showing the app logo override image placement cropped into a circle on the left side of the visual area of the toast.

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 の新機能: アプリの通知では、トーストバナー内と Notification Center 内で目立つように表示される注目の ToastGenericHeroImage であるヒーロー画像を表示できます。画像のサイズは、100% のスケーリングで 364 x 180 ピクセルです。

A screenshot of an app notification showing the hero image placement, above the attribution area.

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 では、テキストは単に別のテキスト要素として表示されます (最大 3 つのテキスト要素がまだ存在しないことと仮定)。

A screenshot of a toast notification showing the attribution text

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 の新機能: システム提供のタイムスタンプを、メッセージ/情報/コンテンツが生成された日時を正確に表す独自のタイムスタンプでオーバーライドできるようになりました。このタイムスタンプは、通知センター内に表示されます。

Screenshot of a notification in the Notifications Center with a custom timestamp

カスタムタイムスタンプの使用の詳細については、「トーストのカスタムタイムスタンプ」を参照してください。

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 の新機能: アプリ通知に進行状況バーを表示して、ダウンロードなどの操作の進行状況をユーザーに示すことができます。

A screenshot of a toast notification showing a progress bar.

進行状況バーの使用の詳細については、「トースト進行状況バー」を参照してください。

ヘッダー

Creators Update の新機能: 通知センター内のヘッダーの下に通知をグループ化できます。たとえば、グループチャットからのメッセージをヘッダーの下にグループ化したり、ヘッダーの下にある共通テーマの通知をグループ化したりできます。

A screenshot of a action center showing multiple notifications for the application Notifications Viewer organized under a header labeled

ヘッダーの使用の詳細については、「トーストヘッダー」を参照してください。

アダプティブコンテンツ

Anniversary Update の新機能: 上記で指定したコンテンツに加えて、トーストの展開時に表示される追加のアダプティブコンテンツを表示することもできます。

この追加コンテンツはアダプティブを使用して指定します。アダプティブタイルのドキュメントを参照して詳細を確認できます。

アダプティブコンテンツは AdaptiveGroup 内に含まれている必要があることに注意してください。それ以外の場合は、アダプティブを使用してレンダリングされません。

列とテキスト要素

以下は、列といくつかの高度なアダプティブテキスト要素が使用される例です。テキスト要素は AdaptiveGroup 内に存在するため、豊富なアダプティブスタイル設定プロパティがすべてサポートされます。

A screenshot of a toast notification showing groups of text elements aligned to the left and right of the visual area of the toast.

// 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 アプリ SDK アプリの場合、アプリは常にフォアグラウンドで起動されます。アプリは AppInstance.GetActivatedEventArgs を呼び出して、アクティブ化が通知によって起動されたかどうかを検出し、渡された引数からフォアグラウンドアプリを完全に起動するか、通知を処理して終了するかを判断できます。
通知のスヌーズや無視などのシステムアクションは、UWP アプリと Windows アプリ SDK の両方でサポートされます。 AppNotificationBuilder API はこのシナリオをサポートしていませんが、Windows アプリ SDK アプリは、Microsoft.Windows.AppNotifications.Builder API または未加工 XML を使用してこのシナリオを実装できます。

Note

ボタンは最大 5 つまでです (後で説明するコンテキストメニュー項目を含みます)。

A screenshot of a toast notification showing a line of text followed a row with two buttons defined by action elements

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% のスケーリングで白い透明な 16 x 16 ピクセルの画像であり、画像自体にパディングを含めてはなりません。トースト通知でアイコンを指定する場合は、ボタンのスタイルがアイコンボタンに変換されるため、通知内のすべてのボタンのアイコンを指定する必要があります。

Note

アクセシビリティを高めるには、アイコンのコントラスト白バージョン (白い背景の黒いアイコン) を必ず含めて、ユーザーがハイコントラストホワイトモードをオンにするとアイコンが表示されるようにしてください。詳細については、「言語、スケール、ハイコントラストに合わせたタイルとトースト通知のサポート」も参照してください。

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 の HintToolTip プロパティを使用して、アイコンにヒントを追加できます。これは、ボタンにアイコンはあるがコンテンツがない場合に、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 の新機能: 次に示すように、トースト XML 要素に useButtonStyle 属性を追加し、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 の新機能: ユーザーがトースト通知を右クリックするか、コンテキストメニューアイコンを選択したときに表示される既存のコンテキストメニューに、追加のコンテキストメニューアクションを追加できます。

Note

古いデバイスでは、これらの追加のコンテキストメニューアクションは、通知に通常のボタンとして表示されます。

追加した別のコンテキストメニューアクション ("グループチャットを 1 時間ミュートする" など) は、2 つの規定のシステムエントリの上に表示されます。

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 コミュニティツールキットビルダーの構文では、現在コンテキストメニューアクションがサポートされているため、初期化子の構文を使用することをお勧めします。

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>

Note

その他のコンテキストメニュー項目は、トーストでの 5 つのボタンの合計制限に影響します。

追加のコンテキストメニュー項目のアクティブ化は、トーストボタンと同じように処理されます。

入力

入力はアプリ通知の [アクション] 領域内で指定されます。つまり、通知が展開されたときにのみ表示されます。

クイック返信テキストボックス

クイック返信テキストボックス (メッセージングアプリなど) を有効にするには、テキスト入力とボタンを追加し、テキスト入力フィールドの ID を参照して、入力フィールドの横にボタンが表示されます。ボタンのオプションアイコンは (提供されている場合)、パディングなし、白いピクセルが透明に設定され、スケールが 100% の 32x32 ピクセルの画像である必要があります。

A screenshot of a toast notification with a profile picture and some lines of text. A text box for typing directly into the toast is included as well as a button to send the reply.

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>

ボタンバーを含む入力

また、入力の下に通常のボタンが表示された 1 つ (または複数) の入力を含めることもできます。

A screenshot of an app notification showing a line of text, a text box, and a row with two buttons labeled

// 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>

入力を選択する

テキストボックスに加えて、選択メニューを使用することもできます。

A screenshot of an app notification showing a line of text, a selection input with

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>

再通知/解除

選択メニューと 2 つのボタンを使用して、システムの再通知と無視アクションを利用するアラーム通知を作成できます。通知がアラームのように動作するように、必ずシナリオを "アラーム" に設定してください。

A screenshot of an app notification with lines of text describing the time and location of a meeting. A selection box has

トーストボタンの SelectionBoxId プロパティを使用して、再通知ボタンを選択メニュー入力にリンクします。

Microsoft.Windows.AppNotifications.Builder 構文は現在、システムのアクティブ化をサポートしていません。ただし、このシナリオは Windows アプリ 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 を指定する
必要に応じて、カスタムコンテンツ文字列を指定します。
文字列を指定しない場合は、"再通知" と "Dismiss" にローカライズされた文字列が自動的に使用されます。
必要に応じて、SelectionBoxId を指定します。
ユーザーにスヌーズ間隔を選択させず、システム定義の時間間隔 (OS 全体で一貫している) で通知を 1 回だけスヌーズしたい場合は、<入力> を一切作成しないでください。
再通知間隔の選択を指定する場合: - 再通知アクションで SelectionBoxId を指定します - 入力の ID を再通知アクションの SelectionBoxId と一致させます - ToastSelectionBoxItem の値を、再通知間隔を分単位で表す NonNegativeInteger に指定します。

オーディオ

カスタムオーディオは常にモバイルでサポートされており、デスクトップバージョン 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-winsoundevent の一覧から選択することもできます。

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>

アプリ通知のオーディオについては、「オーディオスキーマページ」を参照してください。カスタムオーディオを使用するアプリ通知を送信する方法については、「トーストでのカスタムオーディオ」に関するページを参照してください。

シナリオ

重要な通知、アラーム、アラーム、着信通知を作成するには、シナリオ値が割り当てられた通常のアプリ通知を使用するだけです。このシナリオでは、一貫性のある統一されたユーザーエクスペリエンスを作成するために、いくつかの動作を調整します。使用可能なシナリオの値は 4 つあります。

リマインダー
アラーム
IncomingCall
緊急

リマインダー

アラームシナリオでは、ユーザーが通知を閉じるか、アクションを実行するまで、通知は画面に残ります。 Windows Mobile では、アプリの通知にも事前に展開が表示されます。リマインダーのサウンドが再生されます。アプリ通知で少なくとも 1 つのボタンを指定する必要があります。それ以外の場合、通知は通常の通知として扱われます。

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>

アラーム

アラームはアラームと同じように動作しますが、アラームは既定のアラームサウンドでオーディオをループします。アプリ通知で少なくとも 1 つのボタンを指定する必要があります。それ以外の場合、通知は通常の通知として扱われます。

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 デバイスでは、全画面表示が表示されます。

Incoming call toast notification

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 以降を実行している必要があります。

重要な通知を使用すると、ユーザーは、優先アプリ通知 (緊急/重要) を送信できるファーストパーティおよびサードパーティのアプリを、フォーカスアシスト (応答不可) を中断できる内容をより詳細に制御できます。これは通知設定で変更できます。

A screenshot of an urgent app notification that has an exclamation point in the attribution area next to the app name. The image also shows the system-initiated app notification that provides buttons for the user to allow or disallow urgent notifications from the app.

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>

ローカライズとアクセシビリティ

タイルとアプリ通知では、表示言語、表示スケールファクター、ハイコントラスト、その他のランタイムコンテキストに合わせて調整された文字列と画像を読み込むことができます。詳細は、「言語、スケール、ハイコントラストに合わせたタイルとトースト通知のサポート」は参照してください。

アクティブ化の処理

アプリのアクティブ化 (トーストまたはトーストのボタンをクリックしているユーザー) を処理する方法については、「ローカルトーストの送信」を参照してください。

アプリ通知の内容

作業の開始

アプリ通知の構造

帰属領域

ビジュアル

テキスト要素

インラインイメージ

アプリロゴのオーバーライド

ヒントのクロップ

ヒーローイメージ

画像サイズの制限

属性のテキスト

カスタムタイムスタンプ

進捗バー

ヘッダー

アダプティブコンテンツ

列とテキスト要素

ボタン

アイコン付きのボタン

色付きのボタン

コンテキストメニューのアクション

入力

クイック返信テキストボックス

ボタンバーを含む入力

入力を選択する

再通知/解除

オーディオ

シナリオ

リマインダー

アラーム

着信通話

重要な通知

ローカライズとアクセシビリティ

アクティブ化の処理

フィードバック

その他のリソース

アプリ通知の内容

作業の開始

アプリ通知の構造

帰属領域

ビジュアル

テキスト要素

インライン イメージ

アプリ ロゴのオーバーライド

ヒントのクロップ

ヒーロー イメージ

画像サイズの制限

属性のテキスト

カスタム タイムスタンプ

進捗バー

ヘッダー

アダプティブ コンテンツ

列とテキスト要素

ボタン

アイコン付きのボタン

色付きのボタン

コンテキスト メニューのアクション

入力

クイック返信テキスト ボックス

ボタン バーを含む入力

入力を選択する

再通知/解除

オーディオ

シナリオ

リマインダー

アラーム

着信通話

重要な通知

ローカライズとアクセシビリティ

アクティブ化の処理

関連トピック

フィードバック

その他のリソース

インラインイメージ

アプリロゴのオーバーライド

ヒーローイメージ

カスタムタイムスタンプ

アダプティブコンテンツ

コンテキストメニューのアクション

クイック返信テキストボックス

ボタンバーを含む入力