WPF UI 上手指南：让 WPF 桌面应用获得 Fluent 风格的实用教程-开发者社区

WPF UI 上手指南：让 WPF 桌面应用获得 Fluent 风格的实用教程

【免费下载链接】wpfuiWPF UI provides the Fluent experience in your known and loved WPF framework. Intuitive design, themes, navigation and new immersive controls. All natively and effortlessly.项目地址: https://gitcode.com/GitHub_Trending/wp/wpfui

做 WPF 的人多半熟悉这个状态：默认控件样式还停留在 WinForms 年代，灰按钮、普通列表框、系统原生标题栏。WPF UI 是一个面向 WPF 的 .NET 控件库，把 Windows 11 的 Fluent 设计带入 WPF：主题跟随系统、Mica 窗口背景、现代化导航都在其中。本文用三分钟讲清核心能力，并给出 WPF UI 安装步骤与常见坑清单。

WPF UI 是什么

WPF UI 通过 NuGet 分发（包名WPF-UI，MIT 协议），当前版本 4.3.0，运行在 Windows 上，支持 .NET 8 / 9 / 10（netX.0-windows）以及 .NET Framework 4.6.2 到 4.8.1。它适合两类人：想给存量 WPF 应用换一套现代外观的开发者，以及准备新建 WPF 项目的团队。

它做两件事：一是重绘 WPF 基础控件（Page、ToggleButton、ListView等）的样式；二是提供NavigationView、NumberBox、Snackbar、ContentDialog等原生新控件，不需要引入 WinUI。

如何自动同步 Windows 系统主题

WPF 应用默认不会跟随系统切换深浅色，自己监听 Win32 消息比较繁琐。WPF UI 的SystemThemeWatcher会挂到窗口消息循环上，监听WM_WININICHANGE，用户切换 Windows 外观时自动更新应用的深色/浅色主题、强调色和窗口背景。

用法是一行：在主窗口构造函数里调用SystemThemeWatcher.Watch(this)，默认应用 Mica 背景并同步强调色；不想动强调色时传updateAccents: false。手动切换则用ApplicationThemeManager.Apply(ApplicationTheme.Dark, WindowBackdropType.Mica)。

相关实现：src/Wpf.Ui/Appearance/；文档：系统主题同步、主题系统、强调色。

如何用 NavigationView 配置声明式导航

经典 WPF 里用Frame切页要手写一堆代码，返回按钮和历史都要自己维护。NavigationView把导航结构直接声明在 XAML 里：给每个NavigationViewItem设置TargetPageType指向页面类即可，回退按钮、导航历史、BreadcrumbBar同步都是控件内置的。

<ui:NavigationViewItem Content="首页" Icon="{ui:SymbolIcon Home24}" TargetPageType="{x:Type pages:DashboardPage}" />

MVVM 项目推荐通过依赖注入集成：注册INavigationService（建议 Singleton）和INavigationViewPageProvider，让页面由容器创建；ViewModel 里注入服务即可发起导航。完整写法参考 NavigationView 文档和 MVVM 示例项目，控件实现在 src/Wpf.Ui/Controls/NavigationView/。

如何用 FluentWindow 获得现代标题栏与 Mica 背景

WPF 的Window只有系统默认标题栏，想要 Mica 或 Acrylic 背景需要额外配置。把窗口基类换成ui:FluentWindow，在 XAML 顶部放一个ui:TitleBar，就得到带最小化/最大化/关闭按钮的现代标题栏，Windows 11 上还支持 Snap Layout。Card、InfoBar、ToggleSwitch、AutoSuggestBox等常用控件全部位于Wpf.Ui.Controls命名空间，Visual Studio 设计器可直接预览。

控件源码集中在 src/Wpf.Ui/Controls/，每个控件的用法说明见 Gallery 演示项目。

如何接入系统托盘、通知与任务栏

部分桌面功能 WPF 原生并不直接提供。WPF UI 拆出了几个独立包：Wpf.Ui.Tray提供纯 WPF 的NotifyIcon托盘图标和右键菜单（src/Wpf.Ui.Tray/）；Wpf.Ui.ToastNotifications用于 Windows 系统级弹窗通知（src/Wpf.Ui.ToastNotifications/）；主包内的TaskbarService则负责任务栏按钮上的进度条。需要哪个引用哪个。

📦 WPF UI 安装步骤与第一个窗口

安装命令（.NET CLI）：

dotnet add package WPF-UI

跑通第一个窗口的步骤：

新建一个 WPF 项目（.NET 8 及以上，或 .NET Framework 4.7.2+）。
在App.xaml中合并主题字典与控件字典，Theme属性指定Light或Dark：

<Application.Resources> <ResourceDictionary.MergedDictionaries> <ui:ThemesDictionary Theme="Dark" /> <ui:ControlsDictionary /> </ResourceDictionary.MergedDictionaries> </Application.Resources>

记得在 XAML 根节点声明命名空间：xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"。
把MainWindow改为继承ui:FluentWindow，内容里放ui:TitleBar和一个ui:Card；构造函数中加SystemThemeWatcher.Watch(this)。
dotnet run启动，切换一次 Windows 深浅色，确认应用外观跟随变化。

💡 WPF UI 常见误区

主题画刷必须用DynamicResource：文档明确要求颜色与画刷以DynamicResource引用，用StaticResource的话运行时切换主题不会生效（见 themes.md）。
Segoe Fluent Icons 字体不随库分发：受字体 EULA 限制，库只内置 Fluent System Icons；用到缺少的图标需要自行把 Segoe Fluent Icons 加入应用资源，Windows 11 自带该字体，Windows 10 需手动添加（见 README）。
UnWatch要在窗口加载后调用：对尚未加载的窗口调用SystemThemeWatcher.UnWatch会抛InvalidOperationException，Watch则没有此限制（见 system-theme-watcher.md）。
导航缓存会占内存：NavigationView的CacheHistory默认是 0，设为正数会保留页面状态，只建议用于创建开销大或需要保持状态的页面（见 navigation-view.md）。