ContentDialog 类

定义

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class ContentDialog : ContentControl

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class ContentDialog : ContentControl

Public Class ContentDialog
Inherits ContentControl

<ContentDialog .../>
-or-
<ContentDialog>
    singleObject
</ContentDialog>
-or-
<ContentDialog>stringContent</ContentDialog>

继承

Object IInspectable DependencyObject UIElement FrameworkElement Control ContentControl ContentDialog

属性

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

示例

WinUI 3 库应用包括大多数 WinUI 3 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。

此示例演示如何在代码中创建和显示简单的 ContentDialog。

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

    await noWifiDialog.ShowAsync();
}

此示例演示如何在应用页面的 XAML 中创建 ContentDialog。 尽管对话框是在应用页中定义的，但在代码中调用 ShowAsync 之前，该对话框也不会显示。

在这里， IsPrimaryButtonEnabled 属性设置为 false。 当用户检查 CheckBox 以确认其年龄时，主按钮在代码中启用。

TitleTemplate 属性用于创建同时包含徽标和文本的标题。

<ContentDialog x:Name="termsOfUseContentDialog"
           PrimaryButtonText="Accept" IsPrimaryButtonEnabled="False"
           CloseButtonText="Cancel"
           Opened="TermsOfUseContentDialog_Opened">
    <ContentDialog.TitleTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
                <Image Source="ms-appx:///Assets/SmallLogo.png" Width="40" Height="40" Margin="10,0"/>
                <TextBlock Text="Terms of use"/>
            </StackPanel>
        </DataTemplate>
    </ContentDialog.TitleTemplate>
    <StackPanel>
        <TextBlock TextWrapping="WrapWholeWords">
        <Run>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor
             congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus
             malesuada libero, sit amet commodo magna eros quis urna.</Run><LineBreak/>
        <Run>Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus.</Run><LineBreak/>
        <Run>Pellentesque habitant morbi tristique senectus et netus et malesuada fames
             ac turpis egestas. Proin pharetra nonummy pede. Mauris et orci.</Run><LineBreak/>
        <Run>Suspendisse dui purus, scelerisque at, vulputate vitae, pretium mattis, nunc.
             Mauris eget neque at sem venenatis eleifend. Ut nonummy.</Run>
        </TextBlock>
        <CheckBox x:Name="ConfirmAgeCheckBox" Content="I am over 13 years of age."
              Checked="ConfirmAgeCheckBox_Checked" Unchecked="ConfirmAgeCheckBox_Unchecked"/>
    </StackPanel>
</ContentDialog>

private async void ShowTermsOfUseContentDialogButton_Click(object sender, RoutedEventArgs e)
{
    termsOfUseContentDialog.XamlRoot = this.XamlRoot;
    ContentDialogResult result = await termsOfUseContentDialog.ShowAsync();
    if (result == ContentDialogResult.Primary)
    {
        // Terms of use were accepted.
    }
    else
    {
        // User pressed Cancel, ESC, or the back arrow.
        // Terms of use were not accepted.
    }
}

private void TermsOfUseContentDialog_Opened(ContentDialog sender, ContentDialogOpenedEventArgs args)
{
    // Ensure that the check box is unchecked each time the dialog opens.
    ConfirmAgeCheckBox.IsChecked = false;
}

private void ConfirmAgeCheckBox_Checked(object sender, RoutedEventArgs e)
{
    termsOfUseContentDialog.IsPrimaryButtonEnabled = true;
}

private void ConfirmAgeCheckBox_Unchecked(object sender, RoutedEventArgs e)
{
    termsOfUseContentDialog.IsPrimaryButtonEnabled = false;
}

此示例演示如何创建和使用更复杂的自定义对话框 (SignInContentDialog 派生自 ContentDialog 的) 。 另请参阅本文的 具有 WinUI 样式的派生控件 部分。

<ContentDialog
    x:Class="ContentDialog_WinUI3.SignInContentDialog"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:ContentDialog_WinUI3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Title="SIGN IN"
    PrimaryButtonText="Sign In"  
    CloseButtonText="Cancel"
    PrimaryButtonClick="ContentDialog_PrimaryButtonClick"
    CloseButtonClick="ContentDialog_CloseButtonClick">

    <ContentDialog.Resources>
        <Style TargetType="local:SignInContentDialog" BasedOn="{StaticResource DefaultContentDialogStyle}"/>
    </ContentDialog.Resources>

    <StackPanel VerticalAlignment="Stretch" HorizontalAlignment="Stretch">
        <TextBox Name="userNameTextBox" Header="User name"
                 TextChanged="UserNameTextBox_TextChanged"/>
        <PasswordBox Name="passwordTextBox" Header="Password" IsPasswordRevealButtonEnabled="True"
                     PasswordChanged="PasswordTextBox_PasswordChanged"/>
        <CheckBox Name="saveUserNameCheckBox" Content="Save user name"/>
        <InfoBar x:Name="errorInfoBar" Severity="Error" IsOpen="False" IsClosable="False"/>

        <!-- Content body -->
        <TextBlock Name="body" Style="{StaticResource BodyTextBlockStyle}" TextWrapping="Wrap">
            <TextBlock.Text>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit,
                    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
            </TextBlock.Text>
        </TextBlock>
    </StackPanel>
</ContentDialog>

using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;
using System.Threading.Tasks;

namespace ContentDialog_WinUI3
{
    public enum SignInResult
    {
        SignInOK,
        SignInFail,
        SignInCancel,
        Nothing
    }

    public sealed partial class SignInContentDialog : ContentDialog
    {
        public SignInResult Result { get; private set; }

        public SignInContentDialog()
        {
            this.InitializeComponent();
            this.Opened += SignInContentDialog_Opened;
            this.Closing += SignInContentDialog_Closing;
        }

        private async void ContentDialog_PrimaryButtonClick(ContentDialog sender, ContentDialogButtonClickEventArgs args)
        {
            // Ensure the user name and password fields aren't empty. If a required
            // field is empty, set args.Cancel = true to keep the dialog open.
              if (string.IsNullOrEmpty(userNameTextBox.Text))
            {
                errorInfoBar.Message = "User name is required.";
                errorInfoBar.IsOpen = true;
            }
            else if (string.IsNullOrEmpty(passwordTextBox.Password))
            {
                errorInfoBar.Message = "Password is required.";
                errorInfoBar.IsOpen = true;
            }
            args.Cancel = errorInfoBar.IsOpen;

            // If you're performing async operations in the button click handler,
            // get a deferral before you await the operation. Then, complete the
            // deferral when the async operation is complete.
            if (args.Cancel == false) 
            {
                ContentDialogButtonClickDeferral deferral = args.GetDeferral();
                if (await SimulateAsyncSignInOperation())
                {
                    this.Result = SignInResult.SignInOK;
                }
                else
                {
                    this.Result = SignInResult.SignInFail;
                }
                deferral.Complete();
            }
        }

        private async Task<bool> SimulateAsyncSignInOperation()
        {
            // return true to simulate sign-in success.
            return true;
            // return false to simulate sign-in failure.
            /// return false;
        }

        private void ContentDialog_CloseButtonClick(ContentDialog sender, ContentDialogButtonClickEventArgs args)
        {
            // User clicked Cancel, ESC, or the system back button.
            this.Result = SignInResult.SignInCancel;
        }

        void SignInContentDialog_Opened(ContentDialog sender, ContentDialogOpenedEventArgs args)
        {
            this.Result = SignInResult.Nothing;

            // If the user name is saved, get it and populate the user name field.
            Windows.Storage.ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
            if (localSettings.Values.ContainsKey("userName"))
            {
                userNameTextBox.Text = localSettings.Values["userName"].ToString();
                saveUserNameCheckBox.IsChecked = true;
            }
        }

        void SignInContentDialog_Closing(ContentDialog sender, ContentDialogClosingEventArgs args)
        {
            // If sign in was successful, save or clear the user name based on the user choice.
            if (this.Result == SignInResult.SignInOK)
            {
                if (saveUserNameCheckBox.IsChecked == true)
                {
                    SaveUserName();
                }
                else
                {
                    ClearUserName();
                }
            }
        }

        private void SaveUserName()
        {
            Windows.Storage.ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
            localSettings.Values["userName"] = userNameTextBox.Text;
        }

        private void ClearUserName()
        {
            Windows.Storage.ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
            localSettings.Values["userName"] = null;
            userNameTextBox.Text = string.Empty;
        }

        private void UserNameTextBox_TextChanged(object sender, TextChangedEventArgs e)
        {
            // Clear the error if the user name field isn't empty.
            if (!string.IsNullOrEmpty(userNameTextBox.Text))
            {
                errorInfoBar.Message = string.Empty;
                errorInfoBar.IsOpen = false;
            }
        }

        private void PasswordTextBox_PasswordChanged(object sender, RoutedEventArgs e)
        {
            // Clear the error if the password field isn't empty.
            if (!string.IsNullOrEmpty(passwordTextBox.Password))
            {
                errorInfoBar.Message = string.Empty;
                errorInfoBar.IsOpen = false;
            }
        }
    }
}

下面的代码显示 SignInContentDialog 并使用其自定义 SignInResult。

private async void ShowSignInDialogButton_Click(object sender, RoutedEventArgs e)
{
    SignInContentDialog signInDialog = new SignInContentDialog()
    {
        XamlRoot = rootPanel.XamlRoot
    };
    await signInDialog.ShowAsync();

    if (signInDialog.Result == SignInResult.SignInOK)
    {
        // Sign in was successful.
    }
    else if (signInDialog.Result == SignInResult.SignInFail)
    {
        // Sign in failed.
    }
    else if (signInDialog.Result == SignInResult.SignInCancel)
    {
        // Sign in was cancelled by the user. 
    }
}

注解

使用 ContentDialog 请求用户输入，或在模式对话框中显示信息。 可以使用代码或 XAML 将 ContentDialog 添加到应用页面，也可以创建派生自 ContentDialog 的自定义对话类。 本主题的示例部分介绍了这两种方式。

标题

使用 Title 属性可在对话框中放置标题。 若要添加包含多个简单文本的复杂 title 元素，可以使用 TitleTemplate 属性。

命令按钮

ContentDialog 有 3 个内置按钮，用于描述用户为响应对话框提示而可能执行的操作。 所有对话都应具有安全、非破坏性的操作。 对话还可以选择包含一两个特定的“执行”操作，以响应提示。

使用 PrimaryButtonText 和 SecondaryButtonText 属性可显示对对话框提出的main问题或操作的响应。

使用 CloseButtonText 属性可设置安全、非破坏性按钮的显示文本。 当用户执行 “取消” 操作（如按 ESC 键或按系统后退按钮）时，也会调用对话框的关闭按钮。

可以选择三个按钮之一作为对话框的默认按钮。 使用 DefaultButton 属性来区分其中一个按钮。 此按钮将接收强调按钮视觉处理，自动响应 ENTER 键，并在打开对话框时接收焦点，除非对话框的内容包含可聚焦元素。

显示对话框并使用其结果

若要显示对话框，请调用 ShowAsync 方法。 使用此方法返回的 ContentDialogResult 确定单击了哪些按钮（如果有）。 如果用户按 ESC、系统后退箭头或游戏板 B，则此方法的结果将是 None。

设置 XamlRoot

显示 ContentDialog 时，需要手动将对话框的 XamlRoot 设置为 XAML 主机的根目录。 为此，请将 ContentDialog 的 XamlRoot 属性设置为与 XAML 树中已有的元素相同的 XamlRoot。

如果从 Page 显示 ContentDialog，则可以将 ContentDialog 的 XamlRoot 属性设置为 Page ( XamlRoot = this.XamlRoot) 的 XamlRoot。

Window 没有 XamlRoot 属性，因此，如果对话框是从 Window 显示的，请将对话框的 XamlRoot 属性设置为 Window 的根内容元素的 XamlRoot 属性，如下所示。

<Window
    ... >
    <Grid x:Name="rootPanel">

    </Grid>
</Window>

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

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

关闭对话框

您可能希望在对话框关闭之前执行一些工作 (例如，在提交请求之前验证用户是否已将数据输入表单字段) 。 在对话框关闭之前，有两种方法可以完成工作。 可以处理 PrimaryButtonClick、 SecondaryButtonClick 或 CloseButtonClick 事件，以在用户按下按钮时获取用户的响应，并在对话框关闭前验证对话框的状态。 还可以处理 Closing 事件以在对话框关闭之前执行工作。

一次只能显示一个 ContentDialog。 若要将多个 ContentDialog 链接在一起，请处理第一个 ContentDialog 的 Closing 事件。 在 Closing 事件处理程序中，对第二个对话框调用 ShowAsync 以显示它。

具有 WinUI 样式的派生控件

如果从现有 XAML 控件派生自定义控件，则默认情况下不会获取 WinUI 样式。 应用 WinUI 样式：

• 创建新的 Style，并将其 TargetType 设置为自定义控件。
• 使 Style 基于从其派生的控件的默认样式。

一种常见的情况是从 ContentDialog 派生新控件。 本示例演示如何创建将 DefaultContentDialogStyle 应用于自定义对话框的新 Style。

<ContentDialog
    x:Class="ExampleApp.SignInContentDialog"
    ... >
    <ContentDialog.Resources>
        <Style TargetType="local:SignInContentDialog" 
               BasedOn="{StaticResource DefaultContentDialogStyle}"/>
    </ContentDialog.Resources> 
    <!-- CONTENT -->
</ContentDialog>

控件样式和模板

可以修改默认 的 Style 和 ControlTemplate ，使控件具有唯一的外观。 有关修改控件的样式和模板的信息，请参阅 XAML 样式。 文件中包括 generic.xaml 定义控件外观的默认样式、模板和资源。 出于设计目的， generic.xaml 随 Windows 应用 SDK NuGet 包一起安装。 默认情况下，此位置是 \Users\<username>\.nuget\packages\microsoft.windowsappsdk\<version>\lib\uap10.0\Microsoft.UI\Themes\generic.xaml。 不同版本的 SDK 中的样式和资源可能具有不同的值。

XAML 还包括可用于在不修改控件模板的情况下修改不同视觉状态中的控件颜色的资源。 修改这些资源是首选设置属性，如 Background 和 Foreground。 有关详细信息，请参阅 XAML 样式一文的轻量级样式部分。

构造函数

属性

方法

事件

适用于

另请参阅

• ContentControl
• 对话框和浮出控件