Windows平台MAUI项目如何集成使用WinUI3控件

仅面向Windows平台的MAUI项目可以使用WinUI 3现有控件，包括WinUI-Gallery中提供的各类控件，你当前配置存在三类错误，导致控件无法被识别。

• 移除不兼容的依赖：卸载项目中安装的Microsoft.UI.Xaml 2.7.1包，这个包是WinUI 2（UWP版本）的专属依赖，和WinUI 3不兼容。仅保留Microsoft.WindowsAppSDK包即可，建议将版本升级到1.4以上的稳定版，规避旧版本兼容问题。
• 清理跨平台层错误资源配置：删除项目根目录App.xaml中所有和Microsoft.UI.Xaml.Controls相关的命名空间声明、XamlControlsResources资源配置。根目录的App.xaml是MAUI跨平台资源字典，无法解析WinUI专属资源，强行添加会导致解析失败。WinUI相关的资源只需要保留你在Platform/Windows/App.xaml中已经写好的XamlControlsResources配置即可，该配置会在Windows端运行时自动生效。
• 修正控件使用逻辑：不能直接在MAUI共享层的XAML页面（即MainPage.xaml这类跨平台通用页面）中直接声明WinUI控件。MAUI共享层的XAML解析器仅识别MAUI抽象过的跨平台控件，不会直接识别Windows平台专属的原生类型，就算项目仅面向Windows编译也不支持直接在共享层XAML中写原生平台标签。

根据使用场景二选一即可：

方式1：和MAUI控件混排 #

如果需要WinUI控件和MAUI原生控件在同一个页面混合使用，用占位容器+平台注入的方式实现：

1. 在共享层的页面XAML中添加ContentView作为WinUI控件的占位容器，示例代码：

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MauiWithWinui.MainPage">
    <Grid>
        <ContentView x:Name="WinuiControlContainer" />
    </Grid>
</ContentPage>

2. 在页面对应的.cs文件中，通过Windows条件编译逻辑，创建WinUI控件实例并挂载到占位容器中，示例代码：

using Microsoft.Maui.Platform;
#if WINDOWS
using Microsoft.UI.Xaml.Controls;
#endif

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
#if WINDOWS
        Loaded += (s, e) =>
        {
            var ratingControl = new RatingControl
            {
                PlaceholderValue = 3,
                AutomationPropertiesName = "RatingControl with placeholder"
            };
            WinuiControlContainer.Content = ratingControl.ToMauiView();
        };
#endif
    }
}

所有WinUI 3控件都可以通过这种方式创建后嵌入MAUI可视化树，使用方式和纯WinUI 3项目完全一致。

方式2：纯WinUI页面开发 #

如果项目完全不需要使用MAUI跨平台控件，可以直接跳过MAUI的页面渲染层，在Windows平台启动时直接加载纯WinUI 3页面，开发逻辑和普通WinUI 3项目没有区别，WinUI-Gallery中的所有示例代码可以直接复用。操作方式是修改Platform/Windows/App.xaml.cs中的启动逻辑，直接将应用窗口的Content设置为你编写的WinUI页面即可。

内容的提问来源于stack exchange，提问作者Fruio Nik