Windows UI 2 库入门

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

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

注意

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

下载并安装 Windows UI 库

1. 下载 Visual Studio 2022，确保在 Visual Studio 安装程序中选择“通用 Windows 平台开发”工作负载。

2. 打开现有项目，或使用“Visual C#”->“Windows”->“通用”下的“空白应用”模板或适用于语言投影的模板创建一个新项目。

   重要

   若要使用 WinUI 2.8，必须在项目属性中设置 TargetPlatformVersion >= 10.0.18362.0 和 TargetPlatformMinVersion >= 10.0.17763.0。

3. 在“解决方案资源管理器”面板中，右键单击项目名称，然后选择“管理 NuGet 包”。

   
   “解决方案资源管理器”面板，其中右键单击了项目，并突出显示了“管理 NuGet 包”选项。

4. 在“NuGet 包管理器”中，选择“浏览”选项卡，然后搜索“Microsoft.UI.Xaml”或“WinUI” 。 选择要使用的 Windows UI 库 NuGet 包（Microsoft.UI.Xaml 包内含适用于所有应用的 Fluent 控件和功能）。 单击“安装”。

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

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

5. 将 Windows UI (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>
   

6. 将对 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 项目添加对 Windows UI 库的简单支持，请参阅一个简单的 C++/WinRT Windows UI 库示例。

为 Windows UI 库贡献内容

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

其他资源

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