Windows UI 2 库入门

Windows UI 库 2.7 是 WinUI 的最新稳定版本,可用于生成 UWP 生产应用程序(以及使用 XAML 岛生成桌面应用程序)。

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

注意

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

下载并安装 Windows UI 库

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

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

    重要

    若要使用 WinUI 2.7,必须在项目属性中设置 TargetPlatformVersion >= 10.0.18362.0 和 TargetPlatformMinVersion >= 10.0.15063.0。

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

    Screenshot of the Solution Explorer panel with the project right-clicked and the Manage NuGet Packages option highlighted.
    “解决方案资源管理器”面板,其中右键单击了项目,并突出显示了“管理 NuGet 包”选项。

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

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

    Screenshot of the NuGet Package Manager dialog box showing the Browse tab with winui in the search field and Include prerelease checked.
    “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 上的 Windows UI 库存储库中提供 Bug 报告、提交功能请求和贡献社区代码。

其他资源

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