winui 3 是 windows 11 原生桌面 ui 框架，需搭配 windows app sdk 使用，不兼容 uwp；systembackdrop 必须设在 window 层级并启用 extendscontentintotitlebar；xaml 控件应通过事件绑定而非 findname 访问；应用运行于沙箱中，文件操作需校验权限。
WinUI 3 不是 UWP 的升级版，也不是 WPF 的替代品；它是 Windows 11 原生桌面应用的 UI 框架，必须搭配 Windows App SDK 使用，且不支持 .NET Native AOT 编译目标为 UWP。
WinUI 3 项目必须用 Windows App SDK，不是 .NET SDK
新建 WinUI 3 项目时，Visual Studio（2022 v17.8+ 或 2026）默认模板已绑定 Microsoft.WindowsAppSDK NuGet 包（如 Microsoft.WinUI 和 Microsoft.Windows.SDK.NET）。如果你手动创建空项目或从旧模板迁移，必须显式安装这些包，否则 Window、NavigationView 等类型根本不存在。
常见错误现象：The type or namespace name 'WinUI' does not exist in the namespace 'Microsoft' 或 Cannot resolve symbol 'MicaBackdrop' —— 这不是引用缺失，而是 SDK 版本没对齐。
- 检查
.csproj中是否含<targetframework>net8.0-windows10.0.22621.0</targetframework>（或 net9.0），且含<windowssdkpackageversion>10.0.22621.0</windowssdkpackageversion> - 确保项目属性 → “目标平台版本” ≥ 22621（即 Windows 11 22H2）
- 不要试图在 UWP 项目中“添加 WinUI 3 引用”——UWP 项目使用的是
Microsoft.UI.Xaml2.x，与 WinUI 3 的Microsoft.UI.Xaml3.x 完全不兼容
SystemBackdrop 在 WinUI 3 中必须设在 Window 层级
MicaBackdrop 和 DesktopAcrylicBackdrop 只能在 Window 或 AppWindow 实例上生效，不能设在 Page、UserControl 或 Grid 上。这是很多人写完 XAML 却看不到材质效果的主因。
正确做法是：在 MainWindow.xaml 根元素设置 SystemBackdrop，且必须配合 ExtendsContentIntoTitleBar="True" 和手动隐藏默认标题栏：
<window x:class="MyApp.MainWindow" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:winui="using:Microsoft.UI.Xaml.Controls" extendscontentintotitlebar="True" title="MyApp"><window.systembackdrop><micabackdrop kind="BaseAlt"></micabackdrop></window.systembackdrop><grid><!-- 内容区域 --></grid></window>
- 如果只设
SystemBackdrop但没开ExtendsContentIntoTitleBar，材质会显示在窗口内容区下方，被默认标题栏遮挡 -
Kind="BaseAlt"是推荐值，比Base更适配深色/浅色主题切换；Kind="Background"仅用于全屏或无边框场景 - 在代码后台设置时，必须在
this.InitializeComponent()之后调用，否则SystemBackdrop属性会被重置
WinUI 3 的 XAML 与 C# 交互不是靠 FindName，而是依赖 NameScope 和强类型访问
WinUI 3 中，FindName("xxx") 返回 null 是常态。XAML 中声明的控件名（x:Name）不会自动注入到代码后置类字段，除非你显式启用生成器支持或使用 partial void 初始化钩子。
更可靠的做法是：用 Loaded 事件 + GetTemplateChild，或直接在 XAML 中绑定 Click、SelectionChanged 等事件到方法，避免手动查找：
<button x:name="SubmitButton" content="提交" click="OnSubmitClicked"></button>
private void OnSubmitClicked(object sender, RoutedEventArgs e) { /* sender 是 Button 实例，可安全转换 */ }
- 不要在构造函数里调用
FindName—— 此时 XAML 尚未加载，返回必为 null - 若需动态访问子控件（比如
NavigationView.MenuItems中的某项），优先用Tag或绑定DataContext，而非依赖名字查找 - WinUI 3 的
ElementTheme切换会影响TextBlock等控件的默认颜色，但不会自动更新Background属性值；需要监听ActualThemeChanged事件手动刷新
调试 WinUI 3 应用时，ApplicationData.Current.LocalFolder 路径和权限容易出错
WinUI 3 应用默认运行在 AppContainer 沙箱中，ApplicationData.Current.LocalFolder 指向类似 C:\Users\XXX\AppData\Local\Packages\XXXX_XXXX\LocalState 的路径，但该路径在调试时可能被 Visual Studio 锁定，导致 StorageFile.GetFileFromPathAsync 报 Access is denied。
- 首次访问前务必检查
LocalFolder是否可写：await ApplicationData.Current.LocalFolder.CreateFileAsync("test.tmp", CreationCollisionOption.ReplaceExisting) - 不要硬编码绝对路径；所有用户数据应走
ApplicationData或KnownFolders（如KnownFolders.DocumentsLibrary需声明capabilities） - 若需访问系统目录（如
C:\Program Files），必须用Windows.Storage.AccessCache.StorageApplicationPermissions.FutureAccessList并请求用户选取，不能直连
最常被忽略的一点：WinUI 3 的 WebView2 控件默认禁用脚本执行，且不继承父窗口的 SystemBackdrop 效果——它始终是纯白或纯黑背景，这是由 Chromium 渲染层决定的，无法通过 XAML 属性覆盖。
