WinUI 3 的 XAML 运行时设计工具

Visual Studio包括一组运行时工具，可用于在应用运行时进行设计、循环访问和检查 WinUI 3 XAML。它们一起使用时，可为你提供一个快速的编辑-重载-检查循环，用于显示真实 UI（真实样式、真实数据模板、真实动画），而不是静态近似值。

注意

Visual Studio XAML 设计器（拖放设计选项卡）当前不支持 WinUI 3 项目。如果已打开文件 .xaml 并仅看到 XML 编辑器，则安装不会损坏 - 设计器不适用于 WinUI 3。功能请求在开发者社区上进行跟踪：添加对 WinUI 3 桌面应用的 XAML 设计器支持。有关工程工作的背景信息，请参阅 WindowsAppSDK 讨论 #4710。

无论是否有设计器可用，本文中介绍的运行时工具都很有价值。本文逐步讲解工作流。

你将用到的内容

工具	它的作用是什么	如何打开
XAML 热重载	将 XAML 更改推送到正在运行的应用，而无需重启	自动 — 调试时编辑任何 `.xaml` 文件
实时可视化树	显示完整的运行时元素树，并允许你在应用中选择元素	调试>窗口>实时可视化树
实时属性资源管理器	显示并允许你在运行时编辑所选元素上的每个属性	调试>Windows>实时属性浏览器
XAML 实时预览版	在Visual Studio内呈现正在运行的应用，以便在不切换窗口的情况下进行检查	调试>Windows>XAML 实时预览

Tip

将 实时可视化树 和 实时属性浏览器 并排停靠。它们共同为你提供一个详细的检查视图，其中显示实际的运行时值。

Prerequisites

Visual Studio 2022 版本 17.0 或更高版本（包括 XAML 热重载和实时可视化树）。
使用 Windows 应用 SDK 的 WinUI 3 项目。请参阅 “创建并运行 WinUI 3 项目 ”以创建一个项目。
你的项目应面向 .NET 6 或更高版本（C#），或使用 C++/WinRT。

步骤 1：在调试器下启动应用

按 F5 （或调试>开始调试）。 XAML 热重载会在调试器附加后自动激活。

XAML 热重载 工具栏显示在应用内叠加层上。如果未看到该设置，请验证是否已启用该设置：

转到工具>选项>调试>XAML 热重载。
确认已勾选启用 XAML 热重载。

Important

XAML 热重载需要调试器。在没有调试的情况下运行（Ctrl+F5）将禁用热重载、实时可视化树和实时属性资源管理器。

步骤 2：编辑 XAML 并立即查看更改

运行应用后，切换到编辑器中的任何 .xaml 文件并进行更改，例如更改 Background 颜色或添加新 Button文件。运行的应用在一两秒钟内更新，无需重启。

热重载能做什么和不能做什么

热重载处理最常见的编辑：

添加、删除或重新排序元素
更改属性值（颜色、边距、文本、大小）
添加或修改样式和资源字典
更改数据模板内容

某些更改需要重启：

添加新类、代码隐藏中的事件处理程序，或对x:Class的更改
修改 App.xaml 合并字典（有时）
更改 x:Bind 引用新属性的表达式

当热重载无法应用更改时，工具栏会显示通知。只需重启应用即可使这些更改生效。

有关详细信息，请参阅 XAML 热重载。

步骤 3：检查可视化树和属性

打开实时可视化树窗口（调试>Windows>Live 可视化树）。此窗口显示正在运行的应用 UI 树中的每个元素，按父子关系进行组织。

直观地选择元素

在 “实时可视化树” 工具栏上，启用 “在正在运行的应用程序中选择元素”（十字线按钮）。
单击正在运行的应用中的任意元素——树视图会定位到该元素，且 Live 属性资源管理器 会显示该元素的属性。

这在运行时就相当于在设计图面上点击某个元素，不同的是，它会精确反映应用程序实际渲染的内容，包括在代码中动态创建的元素。

在运行时编辑属性

在 Live 属性资源管理器中，可以实时更改属性值。例如：

更改 a Margin 以调整间距并立即查看效果。
Collapsed设置为Visibility测试隐藏元素时会发生什么。
调整 Width 或 Height 测试响应式布局。

这些运行时编辑不会保存回 XAML 文件，它们用于试验。找到喜欢的值后，请将它们键入到.xaml文件中（热重载选取它们并将其永久化）。

步骤 4：使用 XAML Live Preview

XAML Live Preview 在Visual Studio选项卡中呈现正在运行的应用，因此无需切换窗口即可并排查看应用和 XAML 源。

若要打开它：调试>Windows>XAML Live Preview。

这在单显示器配置下尤其有用，因为在应用和 Visual Studio 之间来回按 Alt+Tab 切换很不方便。

有关详细信息，请参阅 XAML Live Preview。

建议：创建一个 UI 演示页面

在项目中创建一个专用的 演练页面——这个页面的唯一用途是让你尝试控件、样式和布局。这为你提供了一个始终可用于视觉迭代的暂存板，它与上述运行时工具配对尤其出色。

设置操场

右键单击解决方案资源管理器中的项目，然后选择“添加新>项>空白页”（WinUI 3）。 将其命名为 UIPlayground.xaml。

在 UIPlayground.xaml 中，添加一个 ScrollViewer，其中为你要尝试的每个控件或模式分别设置一个部分：

<Page
    x:Class="MyApp.UIPlayground"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <ScrollViewer Padding="24">
        <StackPanel Spacing="24">

            <!-- Section: Buttons -->
            <TextBlock Text="Buttons" Style="{StaticResource SubtitleTextBlockStyle}"/>
            <StackPanel Orientation="Horizontal" Spacing="8">
                <Button Content="Standard"/>
                <Button Content="Accent" Style="{StaticResource AccentButtonStyle}"/>
                <ToggleButton Content="Toggle"/>
                <HyperlinkButton Content="Link" NavigateUri="https://learn.microsoft.com"/>
            </StackPanel>

            <!-- Section: Text input -->
            <TextBlock Text="Text input" Style="{StaticResource SubtitleTextBlockStyle}"/>
            <TextBox PlaceholderText="Type here..." Width="300" HorizontalAlignment="Left"/>
            <PasswordBox PlaceholderText="Password" Width="300" HorizontalAlignment="Left"/>

            <!-- Add more sections as needed -->

        </StackPanel>
    </ScrollViewer>
</Page>

让操场更容易到达。在开发过程中，将其设置为启动页中的 App.xaml.cs：

// In App.xaml.cs, OnLaunched method — swap in for quick playground access:
// rootFrame.Navigate(typeof(UIPlayground));

或者，如果你的应用使用了 NavigationView，则添加一个仅在调试构建版本中显示的菜单项。例如，在主窗口的后台代码中：

// In your main window or shell page constructor, after InitializeComponent():
#if DEBUG
    NavView.MenuItems.Add(new NavigationViewItem
    {
        Content = "UI Playground",
        Tag = typeof(UIPlayground)
    });
#endif

其中，NavView 是你的 NavigationView 控件的 x:Name。

如何使用操场

按 F5 启动应用并导航到操场页面。
将 .xaml 文件与正在运行的应用并排打开（或使用 XAML Live Preview）。
在 XAML 编辑器中添加或修改控件 - 热重载立即推送更改。
使用 实时可视化树 单击呈现的控件并在 Live 属性资源管理器中检查其实际布局值。
当你对控件的外观感到满意时，请将 XAML 复制到真实页面。

此模式提供一个“类型重载-检查”周期，因为它运行了实际代码，因此你会看到真实的数据模板、真实样式和真实动画。

比较设计时和运行时方法

下面是常见的 UI 设计任务如何映射到运行时工具：

任务	运行时工具
向页面添加控件	键入 XAML 元素 — IntelliSense 完成标记和所需属性
预览控件	通过热重载在正在运行的应用中查看它
选择要检查的元素	使用实时可视化树>选择元素（十字线）
查看或编辑属性	使用 Live 属性资源管理器
调整大小或位置	在 XAML 或实时属性资源管理器中编辑 `Width`、`Height`、`Margin`

高效工作流程技巧

使用 WinUI 3 Gallery 应用。 从Microsoft Store安装它，或从GitHub生成它。它展示了所有 WinUI 3 控件，并配有交互式示例和可直接复制的 XAML。将其视为可在编写 XAML 之前浏览的可视目录。
保持 Playground 页面处于打开状态。 将其视为应用的生活风格指南。
使用 d:DesignHeight 和 d:DesignWidth。 即使没有设计器，这些属性也有助于 IntelliSense 并在编辑器中打开页面时保持页面大小一致。
合并到 XAML 绑定失败窗口中。 在调试>Windows>XAML 绑定失败中打开它，以捕获设计器根本不会显示的绑定错误。
使用社区工具包。 Windows Community Toolkit 提供了减少手动代码所需的布局量的控件和帮助程序。

反馈

此页面是否有帮助？

Last updated on 2026-09-10