ダイアログ コントロールDialog controls

ダイアログ コントロールは、状況依存のアプリ情報を表示するモーダル UI オーバーレイです。Dialog controls are modal UI overlays that provide contextual app information. それらでは、明示的に閉じられるまで、アプリ ウィンドウの対話式操作がブロックされます。They block interactions with the app window until being explicitly dismissed. 多くの場合、ユーザーに何らかの操作を要求します。They often request some kind of action from the user.

ダイアログの例

重要な API:ContentDialog クラスImportant APIs: ContentDialog class

適切なコントロールの選択Is this the right control?

重要な情報をユーザーに通知したり、アクションが完了する前に確認や追加情報を要求したりするには、ダイアログを使用します。Use dialogs to notify users of important information or to request confirmation or additional info before an action can be completed.

どのようなときにダイアログを使い、どのようなときにポップアップ (似たコントロール) を使うかに関する推奨事項については、「ダイアログとポップアップ」をご覧ください。For recommendations on when to use a dialog vs. when to use a flyout (a similar control), see Dialogs and flyouts.

Examples

XAML コントロール ギャラリーXAML Controls Gallery
XAML controls gallery

XAML コントロール ギャラリー アプリがインストールされている場合、こちらをクリックしてアプリを開き、ContentDialog または Flyout の動作を確認してください。If you have the XAML Controls Gallery app installed, click here to open the app and see the ContentDialog or Flyout in action.

一般的なガイドラインGeneral guidelines

  • ダイアログ内のテキストの 1 行目で、問題やユーザーの目的 (実行する内容) を明確に示す必要があります。Clearly identify the issue or the user's objective in the first line of the dialog's text.
  • ダイアログのタイトルは主な説明で、省略可能です。The dialog title is the main instruction and is optional.
    • 簡潔なタイトルを使って、ユーザーがそのダイアログで行う必要がある操作を説明します。Use a short title to explain what people need to do with the dialog.
    • ダイアログを使って、簡単なメッセージ、エラー、または質問を表示する場合は、タイトルを省略することもできます。If you're using the dialog to deliver a simple message, error or question, you can optionally omit the title. 主な情報はコンテンツのテキストを使って伝えます。Rely on the content text to deliver that core information.
    • タイトルは、ボタンの選択に直接関連するものにします。Make sure that the title relates directly to the button choices.
  • ダイアログ コンテンツには説明のテキストを含め、これは必須です。The dialog content contains the descriptive text and is required.
    • メッセージ、エラー、または操作をブロック質問をできる限り簡潔に示します。Present the message, error, or blocking question as simply as possible.
    • ダイアログ タイトルを使う場合は、コンテンツ領域を詳しい情報の提示や用語の定義に使います。If a dialog title is used, use the content area to provide more detail or define terminology. タイトルの言葉づかいを変えただけの文を繰り返さないようにします。Don't repeat the title with slightly different wording.
  • 少なくとも 1 つのダイアログ ボタンを表示する必要があります。At least one dialog button must appear.
    • ダイアログに、安全で非破壊的なアクションに対応する "OK"、"閉じる"、"キャンセル" などのボタンが少なくとも 1 つのあるようにします。Ensure that your dialog has at least one button corresponding to a safe, nondestructive action like "Got it!", "Close", or "Cancel". このボタンを追加するには、CloseButton API を使用します。Use the CloseButton API to add this button.
    • ボタンのテキストには、主な説明またはコンテンツに対する具体的な応答を使用します。Use specific responses to the main instruction or content as button text. たとえば、主な説明が "使っているコンピューターへの AppName からのアクセスを許可しますか?" の場合、"許可" ボタンと "ブロック" ボタンを使います。An example is, "Do you want to allow AppName to access your location?", followed by "Allow" and "Block" buttons. 具体的な応答の言葉はすばやく理解できるので、効率的に判断できます。Specific responses can be understood more quickly, resulting in efficient decision making.
    • アクション ボタンのテキストは簡潔にします。Ensure that the text of the action buttons is concise. 短い文字列にすると、ユーザーがすばやく確実に選択できるようになります。Short strings enable the user to make a choice quickly and confidently.
    • 安全で非破壊的なアクションに加え、必要に応じて、主な説明に関連する 1 つまたは 2 つのアクション ボタンをユーザーに対して表示できます。In addition to the safe, nondestructive action, you may optionally present the user with one or two action buttons related to the main instruction. このような "処理実行" アクション ボタンでは、ダイアログの重要な点を確認します。These "do it" action buttons confirm the main point of the dialog. このような "処理実行" アクションを追加するには、PrimaryButton API と SecondaryButton API を使用します。Use the PrimaryButton and SecondaryButton APIs to add these "do it" actions.
    • "処理実行" アクション ボタンは一番左のボタンとして表示されます。The "do it" action button(s) should appears as the leftmost buttons. 安全で非破壊的なアクションは一番右のボタンとして表示されます。The safe, nondestructive action should appear as the rightmost button.
    • 必要に応じて、ダイアログの 3 つのボタンのうちの 1 つを既定のボタンとして区別できます。You may optionally choose to differentiate one of the three buttons as the dialog's default button. ボタンの 1 つを区別するには DefaultButton API を使用します。Use the DefaultButton API to differentiate one of the buttons.
  • パスワード フィールドの検証エラーなど、ページの特定の場所に関連するエラーでは、ダイアログを使わずに、アプリのキャンバス自体を使ってインライン エラーを表示します。Don't use dialogs for errors that are contextual to a specific place on the page, such as validation errors (in password fields, for example), use the app's canvas itself to show inline errors.
  • ダイアログ エクスペリエンスを構築するには、ContentDialog クラスを使います。Use the ContentDialog class to build your dialog experience. 非推奨の MessageDialog API は使わないでください。Don't use the deprecated MessageDialog API.

ダイアログの作成方法How to create a dialog

ダイアログ ボックスを作成するには、ContentDialog クラスを使用します。To create a dialog, you use the ContentDialog class. ダイアログはコードまたはマークアップで作成できます。You can create a dialog in code or markup. 通常は UI 要素を XAML で定義する方が容易ですが、単純なダイアログの場合には、コードを記述する方が実際には容易です。Although its usually easier to define UI elements in XAML, in the case of a simple dialog, it's actually easier to just use code. この例では、ダイアログを作成して、ユーザーに WiFi 接続がないことの通知を行い、ShowAsyncメソッドを使ってそれを表示しています。This example creates a dialog to notify the user that there's no WiFi connection, and then uses the ShowAsync method to display it.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "Ok"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

ユーザーがダイアログのボタンをクリックすると、ShowAsync メソッドは ContentDialogResult を返して、ユーザーがクリックしたボタンを伝えます。When the user clicks a dialog button, the ShowAsync method returns a ContentDialogResult to let you know which button the user clicks.

この例でのダイアログは、質問を行い、ContentDialogResult の戻り値を使用してユーザーの応答を確認します。The dialog in this example asks a question and uses the returned ContentDialogResult to determine the user's response.

private async void DisplayDeleteFileDialog()
{
    ContentDialog deleteFileDialog = new ContentDialog
    {
        Title = "Delete file permanently?",
        Content = "If you delete this file, you won't be able to recover it. Do you want to delete it?",
        PrimaryButtonText = "Delete",
        CloseButtonText = "Cancel"
    };

    ContentDialogResult result = await deleteFileDialog.ShowAsync();

    // Delete the file if the user clicked the primary button.
    /// Otherwise, do nothing.
    if (result == ContentDialogResult.Primary)
    {
        // Delete the file.
    }
    else
    {
        // The user clicked the CLoseButton, pressed ESC, Gamepad B, or the system back button.
        // Do nothing.
    }
}

安全な操作を提供するProvide a safe action

ダイアログでユーザー操作がブロックされたとき、ユーザーがダイアログを閉じる主な方法はボタンであるため、ダイアログに "閉じる" や "OK" などの安全で非破壊的なボタンが少なくとも 1 つは含まれるようにします。Because dialogs block user interaction, and because buttons are the primary mechanism for users to dismiss the dialog, ensure that your dialog contains at least one "safe" and nondestructive button such as "Close" or "Got it!". すべてのダイアログには、ダイアログを閉じるための少なくとも 1 つの安全なアクション ボタンを含める必要があります。All dialogs should contain at least one safe action button to close the dialog. これにより、ユーザーはアクションを実行することなく安心してダイアログを閉じることができます。This ensures that the user can confidently close the dialog without performing an action.
ボタンを 1 つ備えたダイアログAn one button dialog

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "Ok"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

ダイアログにブロック質問を表示する場合、ダイアログには質問に関連するアクション ボタンを表示する必要があります。When dialogs are used to display a blocking question, your dialog should present the user with action buttons related to the question. 安全で非破壊的なボタンは、1 つまたは 2 つの "処理実行" アクション ボタンを伴っている場合があります。The "safe" and nondestructive button may be accompanied by one or two "do it" action buttons. 複数のオプションを表示するときは、提示されている質問に関して "処理実行" アクションと安全な "処理非実行" アクションをボタンが明確に示すようにします。When presenting the user with multiple options, ensure that the buttons clearly explain the "do it" and safe/"don’t do it" actions related to the question proposed.

ボタンを 2 つ備えたダイアログ

private async void DisplayLocationPromptDialog()
{
    ContentDialog locationPromptDialog = new ContentDialog
    {
        Title = "Allow AppName to access your location?",
        Content = "AppName uses this information to help you find places, connect with friends, and more.",
        CloseButtonText = "Block",
        PrimaryButtonText = "Allow"
    };

    ContentDialogResult result = await locationPromptDialog.ShowAsync();
}

ボタンを 3 つ備えたダイアログは、2 つの "処理実行" アクションと 1 つの "処理非実行" アクションを表示するときに使用します。Three button dialogs are used when you present the user with two "do it" actions and a "don’t do it" action. ボタンを 3 つ備えたダイアログは、セカンダリ アクションと安全な "閉じる" アクションを明確に区別して慎重に使用する必要があります。Three button dialogs should be used sparingly with clear distinctions between the secondary action and the safe/close action.

ボタンを 3 つ備えたダイアログ

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it"
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

ダイアログの 3 つのボタンThe three dialog buttons

ContentDialog には、ダイアログ エクスペリエンスを構築するために使用できる、3 種類のボタンがあります。ContentDialog has three different types of buttons that you can use to build a dialog experience.

  • CloseButton - 必須 - ユーザーがダイアログを終了できる安全で非破壊的なアクションを表します。CloseButton - Required - Represents the safe, nondestructive action that enables the user to exit the dialog. 一番右のボタンとして表示されます。Appears as the rightmost button.
  • PrimaryButton - 省略可能 - 1 つ目の "処理実行" アクションを表します。PrimaryButton - Optional - Represents the first "do it" action. 一番左のボタンとして表示されます。Appears as the leftmost button.
  • SecondaryButton - 省略可能 - 2 つ目の "処理実行" アクションを表します。SecondaryButton - Optional - Represents the second "do it" action. 中央のボタンとして表示されます。Appears as the middle button.

組み込みのボタンを使用すると、ボタンが適切な位置に表示され、キーボード イベントに正しく反応し、コマンド領域がスクリーン キーボード使用時にも表示されたままになり、ダイアログの外観が他のダイアログと一貫性のあるものになります。Using the built-in buttons will position the buttons appropriately, ensure that they correctly respond to keyboard events, ensure that the command area remains visible even when the on-screen keyboard is up, and will make the dialog look consistent with other dialogs.

CloseButtonCloseButton

すべてのダイアログには、ユーザーが安心してダイアログを終了できる、安全で非破壊的なアクション ボタンが含まれる必要があります。Every dialog should contain a safe, nondestructive action button that enables the user to confidently exit the dialog.

このボタンを作成するには、ContentDialog.CloseButton API を使用します。Use the ContentDialog.CloseButton API to create this button. これにより、マウス、キーボード、タッチ、およびゲームパッドを含むすべての入力に対して、適切なユーザー エクスペリエンスを作成することができます。This allows you to create the right user experience for all inputs including mouse, keyboard, touch, and gamepad. このエクスペリエンスは以下の場合に発生します。This experience will happen when:

  1. ユーザーが CloseButton をクリックまたはタップするThe user clicks or taps on the CloseButton
  2. ユーザーがシステムの戻るボタンを押すThe user presses the system back button
  3. ユーザーがキーボードの Esc キーを押すThe user presses the ESC button on the keyboard
  4. ユーザーがゲームパッドの B を押すThe user presses Gamepad B

ユーザーがダイアログのボタンをクリックすると、ShowAsync メソッドは ContentDialogResult を返して、ユーザーがクリックしたボタンを伝えます。When the user clicks a dialog button, the ShowAsync method returns a ContentDialogResult to let you know which button the user clicks. CloseButton を押すと ContentDialogResult.None が返されます。Pressing on the CloseButton returns ContentDialogResult.None.

PrimaryButton と SecondaryButtonPrimaryButton and SecondaryButton

CloseButton に加え、必要に応じて、主な説明に関連する 1 つまたは 2 つのアクション ボタンをユーザーに対して表示できます。In addition to the CloseButton, you may optionally present the user with one or two action buttons related to the main instruction. 1 つ目の "処理実行" アクションには PrimaryButton、2 つ目の "処理実行" アクションには SecondaryButton を使います。Leverage PrimaryButton for the first "do it" action, and SecondaryButton for the second "do it" action. ボタンを 3 つ備えたダイアログでは、通常、PrimaryButton は肯定的な "処理実行" アクションを示し、SecondaryButton は中立的または二次的な "処理実行" アクションを示します。In three-button dialogs, the PrimaryButton generally represents the affirmative "do it" action, while the SecondaryButton generally represents a neutral or secondary "do it" action. たとえば、ユーザーがアプリからサービスに登録するように求められる場合があります。For example, an app may prompt the user to subscribe to a service. 肯定的な "処理実行" アクションとして PrimaryButton は "サブスクライブする" というテキストを表示し、中立的な "処理実行" アクションとして SecondaryButton は "試してみる" というテキストを表示します。The PrimaryButton as the affirmative "do it" action would host the Subscribe text, while the SecondaryButton as the neutral "do it" action would host the Try it text. CloseButton は、ユーザーがいずれのアクションも実行せずにキャンセルできるようにします。The CloseButton would allow the user to cancel without performing either action.

ユーザーが PrimaryButton をクリックすると、ShowAsync メソッドは ContentDialogResult.Primary を返します。When the user clicks on the PrimaryButton, the ShowAsync method returns ContentDialogResult.Primary. ユーザーが SecondaryButton をクリックすると、ShowAsync メソッドは ContentDialogResult.Secondary を返します。When the user clicks on the SecondaryButton, the ShowAsync method returns ContentDialogResult.Secondary.

ボタンを 3 つ備えたダイアログ

DefaultButtonDefaultButton

必要に応じて、3 つのボタンのうちの 1 つを既定のボタンとして区別できます。You may optionally choose to differentiate one of the three buttons as the default button. 既定のボタンを指定すると、次のようになります。Specifying the default button causes the following to happen:

  • ボタンにアクセント ボタンとして視覚的な効果が適用されるThe button receives the Accent Button visual treatment
  • ボタンが Enter キーに自動的に応答するThe button will respond to the ENTER key automatically
    • ユーザーがキーボードの Enter キーを押すと、既定のボタンに関連付けられているクリック ハンドラーが起動し、ContentDialogResult は既定のボタンに関連付けられている値を返すWhen the user presses the ENTER key on the keyboard, the click handler associated with the Default Button will fire and the ContentDialogResult will return the value associated with the Default Button
    • ユーザーが Enter を処理するコントロールにキーボード フォーカスを置いている場合、既定のボタンは Enter が押されても反応しないIf the user has placed Keyboard Focus on a control that handles ENTER, the Default Button will not respond to ENTER presses
  • ダイアログのコンテンツにフォーカス可能な UI が含まれていない限り、ダイアログが開くとボタンが自動的にフォーカスされるThe button will receive focus automatically when the Dialog is opened unless the dialog’s content contains focusable UI

既定のボタンを指定するには、ContentDialog.DefaultButton プロパティを使います。Use the ContentDialog.DefaultButton property to indicate the default button. 既定では、既定のボタンは設定されていません。By default, no default button is set.

既定のボタンを含むボタンを 3 つ備えたダイアログ

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it",
        DefaultButton = ContentDialogButton.Primary
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

確認ダイアログ ([OK]/[キャンセル])Confirmation dialogs (OK/Cancel)

確認ダイアログ ボックスにより、ユーザーはアクションを実行するかどうかを確認できます。A confirmation dialog gives users the chance to confirm that they want to perform an action. アクションを確認するか、キャンセルを選択することができます。They can affirm the action, or choose to cancel.
一般的な確認ダイアログ ボックスには、確認 ([OK]) ボタンと [キャンセル] ボタンの 2 つのボタンがあります。A typical confirmation dialog has two buttons: an affirmation ("OK") button and a cancel button.

  • 一般的に、確認ボタンは左側 (プライマリ ボタン) にあり、[キャンセル] ボタン (セカンダリ ボタン) は右側にあります。In general, the affirmation button should be on the left (the primary button) and the cancel button (the secondary button) should be on the right.

    An OK/cancel dialog
  • 一般的な推奨事項のセクションで説明したように、テキストを指定したボタンを使って、主な説明またはコンテンツに対する具体的な応答を示します。As noted in the general recommendations section, use buttons with text that identifies specific responses to the main instruction or content.

一部のプラットフォームでは、左側ではなく、右側に確認ボタンが配置されます。Some platforms put the affirmation button on the right instead of the left. それでは、左側に確認ボタンを配置するのはなぜでしょうか。So why do we recommend putting it on the left? ユーザーの大部分が右利きであり、右手でスマートフォンを保持すると想定した場合、実際に確認ボタンが左側にある方がボタンを押しやすくなります。これは、ボタンがユーザーの親指が描く円弧上にある可能性が高くなるためです。画面の右側にボタンがある場合、ユーザーは親指を内側に引いて操作しにくい位置に移動する必要があります。If you assume that the majority of users are right-handed and they hold their phone with that hand, it's actually more comfortable to press the affirmation button when it's on the left, because the button is more likely to be within the user's thumb-arc. Buttons on the right-side of the screen require the user to pull their thumb inward into a less-comfortable position.

AppWindow 内または XAML Islands 内の ContentDialogContentDialog in AppWindow or Xaml Islands

注: このセクションは、Windows 10 バージョン 1903 以降をターゲットとするアプリにのみ適用されます。NOTE: This section applies only to apps that target Windows 10, version 1903 or later. それより前のバージョンでは、AppWindow および XAML Islands は使用できません。AppWindow and XAML Islands are not available in earlier versions. バージョンについて詳しくは、バージョン アダプティブ アプリに関する記事をご覧ください。For more info about versioning, see Version adaptive apps.

既定では、コンテンツ ダイアログはルート ApplicationView を基準としてモーダルに表示されます。By default, content dialogs display modally relative to the root ApplicationView. ContentDialog を AppWindow または XAML Islandsの内部で使うときは、ダイアログの XamlRoot を XAML ホストのルートに手動で設定する必要があります。When you use ContentDialog inside of either an AppWindow or a XAML Island, you need to manually set the XamlRoot on the dialog to the root of the XAML host.

それを行うには、次に示すように、ContentDialog の XamlRoot プロパティを、AppWindow または XAML Islands に既に存在する要素と同じ XamlRoot に設定します。To do so, set the ContentDialog's XamlRoot property to the same XamlRoot as an element already in the AppWindow or XAML Island, as shown here.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "Ok"
    };

    // Use this code to associate the dialog to the appropriate AppWindow by setting
    // the dialog's XamlRoot to the same XamlRoot as an element that is already present in the AppWindow.
    if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
    {
        noWifiDialog.XamlRoot = elementAlreadyInMyAppWindow.XamlRoot;
    }

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

警告

1 つのスレッドで一度に開くことのできる ContentDialog は 1 つだけです。There can only be one ContentDialog open per thread at a time. 2 つの ContentDialog を開こうとすると、個別の AppWindow で開く場合でも、例外がスローされます。Attempting to open two ContentDialogs will throw an exception, even if they are attempting to open in separate AppWindows.

サンプル コードを入手するGet the sample code