对话框控件是用于提供上下文应用信息的模态 UI 覆盖层。 除非显式取消这些控件，否则它们会阻止与应用窗口的交互。 他们经常要求用户执行某种动作。
这是正确的控制吗？
使用对话框通知用户重要信息或在可以完成某个操作之前请求确认或其他信息。
有关何时使用对话框以及何时使用浮出控件（类似控件）的建议，请参阅对话框和浮出控件。
一般指南
在对话文本的第一行中清楚地确定问题或用户的目标。
对话框标题是主要指令，是可选的。
使用简短标题解释用户在对话框中需要执行的操作。
如果使用对话框传递简单的消息、错误或问题，可以选择省略标题。 依靠内容文本传送该核心信息。
请确保标题与按钮选项直接相关。
对话框内容包含描述性文本，并且是必需的。
尽可能简单地呈现消息、错误或阻塞性问题。
如果使用对话框标题，请使用内容区域提供更多详细信息或定义术语。 不要用略有不同的措辞重复标题。
必须至少显示一个对话框按钮。
确保你的对话框至少有一个按钮对应于安全、没有破坏性的操作，如“明白了!”、“关闭”或“取消”。 使用 CloseButton API 可添加该按钮。
使用与主要指令或内容相关的具体响应作为按钮文本。 例如，“是否允许 AppName 访问你的位置？”，后跟“允许”和“阻止”按钮。 可以更快地理解特定响应，从而做出高效的决策。
确保操作按钮的文本保持简明。 简短的字符串使用户能够快速、自信地做出选择。
除了安全、无破坏性的操作外，你还可以选择为用户提供一个或两个与主要说明相关的操作按钮。 这些“执行”操作按钮用于确认对话框的重点。 使用 PrimaryButton 和 SecondaryButton API 添加这些“执行任务”的操作。
“执行”操作按钮应显示为最左侧按钮。 安全、无破坏性的操作应显示为最右侧的按钮。
可以选择性地将三个按钮之一设置为对话框的默认按钮。 使用 DefaultButton API 可区分其中一个按钮。
不要使用弹窗显示与页面上特定位置相关的错误，例如验证错误（如密码字段中的错误），而应使用应用的画布直接显示内联错误。
使用 ContentDialog 类生成对话框体验。 不要使用已弃用的 MessageDialog API。
创建对话框
重要 API： ContentDialog 类
打开 WinUI 3 库应用并查看 ContentDialog 运行情况
WinUI 3 示例库应用包含 WinUI 控件和功能的交互式示例。 从 Microsoft Store 或浏览 GitHub 上的源代码获取应用。
若要创建对话框，请使用 ContentDialog 类。 可以在代码或标记中创建对话框。 尽管在 XAML 中定义 UI 元素通常更容易，但在简单对话框中，只需使用代码就更容易了。 本示例创建一个对话框，通知用户没有 WiFi 连接，然后使用 ShowAsync 方法显示它。
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();
}
如果内容对话框更为复杂，则使用 XAML 创建它可能更容易。 可以在页面的 XAML 文件中创建它，也可以使用其自己的 .xaml 和代码隐藏文件创建 ContentDialog 的子类。 有关这两者的完整示例，请参阅 [ContentDialog] 类引用。
Visual Studio中没有项模板可以创建新的内容对话框文件，但你可以使用空白页模板修改生成的文件来创建对话。
使用 XAML 和后台代码创建新内容对话框
在 解决方案资源管理器 窗格中，右键单击项目名称并选择 Add > 新建项...
在“ 添加新项 ”对话框中，选择窗口左侧模板列表中的 WinUI 。
选择 空白页 模板。
为文件命名。 在此示例中，文件名为XamlContentDialog。
按 Add。
在新 .xaml 文件中，将开始和结束页标记更改为内容对话框。
x:Class="ContentDialog_WinUI3.XamlContentDialog" ...> 在.xaml.cs文件中，使类继承自 ContentDialog 而不是 Page。 // public sealed partial class XamlContentDialog : Page public sealed partial class XamlContentDialog : ContentDialog 显示对话框 若要显示对话框，请调用 ShowAsync 方法。 XamlContentDialog xamlDialog = new XamlContentDialog() { XamlRoot = this.XamlRoot }; await xamlDialog.ShowAsync(); 警告 每个窗口一次只能打开一个 ContentDialog。 尝试打开两个内容对话框将引发异常。 设置 XamlRoot 显示 ContentDialog 时，需要手动将对话框的 XamlRoot 设置为 XAML 主机的根目录。 因此，请将 ContentDialog 的 XamlRoot 属性设置为与 XAML 树中已有的元素的 XamlRoot 相同。 如果从 Page 显示 ContentDialog，则可以将 ContentDialog 的 XamlRoot 属性设置为页面的 XamlRoot，如前面的示例所示。 窗口 没有 XamlRoot 属性，因此，如果从 Window 显示对话框，请将对话框的 XamlRoot 属性设置为 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(); } 响应对话框按钮 当用户单击对话框按钮时，ShowAsync 方法将返回 ContentDialogResult，告知用户单击哪个按钮。 此示例中的对话框提出问题，并使用返回 的 ContentDialogResult 来确定用户的响应。 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. } } 确保操作安全 由于对话框会阻止用户交互，而且按钮是用户消除对话框的主要机制，因此请确保你的对话框至少包含一个“安全”且无破坏性的按钮，如“关闭”或“明白!”。 所有对话应都至少应包含一个安全操作按钮来关闭对话框。 这可以确保用户能自信地关闭对话框，而未执行操作。 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(); } 当对话框用于显示阻止问题时，你的对话框应向用户显示与该问题相关的操作按钮。 “安全的”且无破坏性的按钮可能会伴随一个或两个“执行操作”按钮。 在向用户提供多个选项时，请确保按钮可清晰地说明与所提出问题相关的“执行”和安全的“不执行”操作。 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(); } 向用户提供两个“执行”操作和一个“不执行”操作时，可以使用三个按钮对话框。 应慎用三个按钮对话框，辅助操作与安全/关闭操作之间应有清晰的区别。 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(); } 三个对话框按钮 ContentDialog 有三种不同类型的按钮可用于构建对话框体验。 CloseButton - 必需 - 表示允许用户退出对话框的安全、无破坏性操作。 显示为最右侧的按钮。 PrimaryButton - 可选 - 表示第一个“执行”操作。 显示为最左侧的按钮。 SecondaryButton - 可选 - 表示第二个“执行操作”指令。 显示为中间的按钮。 使用内置按钮可相应放置按钮、确保按钮可正确响应键盘事件、确保在屏幕键盘启动时命令区域仍保持可见并使该对话框与其他对话框看起来一致。 关闭按钮 每个对话框都应包含一个可使用户安心退出对话框的安全、无破坏性的操作按钮。 使用 ContentDialog.CloseButton API 可创建此按钮。 这样便可以为包括鼠标、键盘、触控和游戏板在内的所有输入创建适当的用户体验。 此体验将在以下情况下发生： 用户单击或轻触 CloseButton。 用户按系统后退按钮。 用户按下键盘上的 ESC 按钮。 用户按下游戏手柄的B键。 当用户单击对话框按钮时，ShowAsync 方法将返回 ContentDialogResult，告知用户单击哪个按钮。 点击 CloseButton 返回 ContentDialogResult.None。 主按钮 和 次要按钮 除了 CloseButton，还可以选择向用户提供与主要说明相关的一个或两个操作按钮。 使用 PrimaryButton 执行第一个“实施”操作，使用 SecondaryButton 执行第二个“实施”操作。 在包含三个按钮的对话框中，主按钮通常表示肯定的“执行”操作，而次按钮通常表示中性或次要的“执行”操作。 例如，应用可能会提示用户订阅服务。 作为肯定“执行”操作的 PrimaryButton 将托管“订阅”文本，而作为中性“执行”操作的 SecondaryButton 将托管“尝试”文本。 CloseButton 允许用户取消，而不执行任何操作。 当用户单击 PrimaryButton 时，ShowAsync 方法将返回 ContentDialogResult.Primary。 当用户单击 SecondaryButton 时，ShowAsync 方法将返回 ContentDialogResult.Secondary。 默认按钮 可以选择区分三个按钮之一，使其作为默认按钮。 指定默认按钮将导致发生以下情况： 该按钮接收“突出”按钮视觉处理 该按钮将自动响应 ENTER 键 当用户在键盘上按 ENTER 键时，与“默认”按钮关联的单击处理程序将激发，并且 ContentDialogResult 将返回与“默认”按钮关联的值 如果用户已将键盘焦点放在处理 ENTER 的控件上，默认按钮将不响应 ENTER 按下操作 当打开对话框时，除非对话框内容包含可聚焦的 UI 元素，否则按钮会自动获得焦点。 使用 ContentDialog.DefaultButton 属性指示默认按钮。 默认情况下，不设置默认按钮。 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(); } 确认对话框 （确定/取消） 通过确认对话框，用户可以确认他们是否要执行操作。 他们可以确认操作，或选择取消。 典型的确认对话框有两个按钮：确认（“确定”）按钮和取消按钮。 一般情况下，确认按钮应位于左侧（主按钮），取消按钮（辅助按钮）应位于右侧。 如常规建议部分所述，使用带有文本的按钮来标识对主要指令或内容的特定响应。 相关文章 工具提示 菜单和上下文菜单 Flyout类 默认情况下，内容对话框会以模态方式相对于根ApplicationView显示。 使用 AppWindow 或 XAML 岛中的 ContentDialog 时，需要手动将对话框中的 XamlRoot 设置为 XAML 宿主的根。