适用于 UWP 的 WinUI 2 入门

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

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

注释

有关使用最新版本 的 WinUI 3 生成 Windows 桌面应用的详细信息，请参阅 WinUI 3。

设置 Visual Studio 进行 UWP 开发

下载 Visual Studio 2022 并安装用于 UWP 开发的工具。 有关更详细的说明，请参阅 Visual Studio 文档中 的“创建 UWP 应用 ”。

在 Visual Studio 安装程序应用的 “工作负荷 ”选项卡上，选择以下工作负载和组件：

  • 选择 WinUI 应用程序开发 工作负载。 然后，在 “安装详细信息 ”窗格中的 WinUI 应用程序开发 节点下，选择所需的 UWP 选项（这还将选择任何其他必需的组件）。

    • 对于 C#，请选择 通用 Windows 平台工具。
    • 对于C++，请选择 C++（v14x）通用 Windows 平台工具 （除非有使用早期版本的具体原因）。

注释

在 Visual Studio 17.10 - 17.12 中，此工作负载称为 Windows 应用程序开发。

下载并安装 WinUI

  1. 打开现有项目，或使用 Visual C# > Windows > Universal 下的空白应用模板或语言投影的相应模板创建新项目。

    重要

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

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

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

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

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

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

  4. 将 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>

  5. 将对 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>
...

有关将 WinUI 简单支持添加到 C++/WinRT 项目的完整分步演练，请参阅 简单的C++/WinRT WinUI 示例。

GitHub 上的 WinUI

欢迎 GitHub 上的 microsoft-ui-xaml 存储库 中的 bug 报告。

  • 上次更新时间为