WinUI 2 入门

项目
06/05/2024

WinUI 2.8 是 WinUI 的最新稳定版本，可用于生成 UWP 生产应用程序（以及使用 XAML 岛生成桌面应用程序）。

该库以 NuGet 包的形式提供，可以添加到任何新的或现有的 Visual Studio 项目中。

注意

若要详细了解如何使用最新版本的 WinUI 3 生成 Windows 桌面应用，请参阅 WinUI 3。

下载并安装 WinUI

下载 Visual Studio 2022，确保在 Visual Studio 安装程序中选择“通用 Windows 平台开发”工作负载。
打开现有项目，或使用“Visual C#”->“Windows”->“通用”下的“空白应用”模板或适用于语言投影的模板创建一个新项目。

重要

若要使用 WinUI 2.8，必须在项目属性中设置 TargetPlatformVersion >= 10.0.18362.0 和 TargetPlatformMinVersion >= 10.0.17763.0。
在“解决方案资源管理器”面板中，右键单击项目名称，然后选择“管理 NuGet 包”。

“解决方案资源管理器”面板，其中右键单击了项目，并突出显示了“管理 NuGet 包”选项。
在“NuGet 包管理器”中，选择“浏览”选项卡，然后搜索“Microsoft.UI.Xaml”或“WinUI” 。选择要使用的 WinUI NuGet 包（Microsoft.UI.Xaml 包内含适用于所有应用的 Fluent 控件和功能）。单击“安装”。

选中“包括预发行版”复选框，了解包含实验性新功能的最新预发行版。

“NuGet 包管理器”对话框，其中显示了搜索字段中包含 winui 的“浏览”选项卡，并且选中了“包含预发行版”。

将 WinUI 主题资源添加到 App.xaml 文件。

可以通过两种方式来这样做，具体取决于你是否有其他应用程序资源。

a. 如果不需要其他应用程序资源，请添加 WinUI 资源元素 <XamlControlsResources，如下例所示：

<Application
    x:Class="ExampleApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    RequestedTheme="Light">

    <Application.Resources>
        <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
    </Application.Resources>

</Application>

b. 如果你有其他资源，我们建议将它们添加到 XamlControlsResources.MergedDictionaries。这适用于平台的资源系统，以允许覆盖 XamlControlsResources 资源。

<Application
    x:Class="ExampleApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:controls="using:Microsoft.UI.Xaml.Controls"
    RequestedTheme="Light">

    <Application.Resources>
        <controls:XamlControlsResources>
            <controls:XamlControlsResources.MergedDictionaries>
                <ResourceDictionary Source="/Styles/Styles.xaml"/>
                <!-- Other app resources here -->
            </controls:XamlControlsResources.MergedDictionaries>
        </controls:XamlControlsResources>
    </Application.Resources>

</Application>

将对 WinUI 包的引用添加到 XAML 页和/或代码隐藏页。
- 在 XAML 页的页面顶部添加引用
```
xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
```
- 在代码中（如果想要使用类型名称而不对其进行限定），可以添加 using 指令。
```
using MUXC = Microsoft.UI.Xaml.Controls;
```

C++/WinRT 项目的其他步骤

将 NuGet 包添加到 C++/WinRT 项目时，此工具会在项目的 \Generated Files\winrt 文件夹中生成一组投影头文件。若要将这些头文件引入项目中，以便解析对这些新类型的引用，可以进入预编译的头文件（通常为 pch.h）中，将它们包括进去。下面是一个示例，其中包含为 Microsoft.UI.Xaml 包生成的头文件。

// pch.h
...
#include <winrt/Microsoft.UI.Xaml.Automation.Peers.h>
#include <winrt/Microsoft.UI.Xaml.Controls.Primitives.h>
#include <winrt/Microsoft.UI.Xaml.Media.h>
#include <winrt/Microsoft.UI.Xaml.XamlTypeInfo.h>
...

如果需要通过完整的分步演练来了解如何为 C++/WinRT 项目添加对 WinUI 的简单支持，请参阅一个简单的 C++/WinRT WinUI 示例。

参与 WinUI

我们欢迎你在 GitHub 上的 microsoft-ui-xaml 存储库中提供 Bug 报告、提交功能请求和贡献社区代码。

其他资源

如果不熟悉 UWP，建议在开发人员门户中访问 UWP 开发入门页。