尧图网站建设 
Wpf.Ui v2 迁移指南命名空间重构、导航体系重写与标题栏适配全解析【免费下载链接】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.UiWPF UIv2.0 的关键破坏性变更展开聚焦全局命名空间调整、导航控件体系重写与标题栏重构三大主题并对照当前仓库源码说明迁移后的实际形态与后续演进。读完本文你将掌握从 WPF-UI 旧命名空间平滑切换至Wpf.Ui的路径、v2 导航控件的声明方式与核心参数语义以及重写后的标题栏在自定义窗口中的适配要点。本文是 v2 迁移的快速参考手册而非逐行逐步的完整教程它不覆盖每个 API 的逐一替换而是把迁移过程中最容易踩坑、影响面最大的部分拎出来让你在动手升级前对全局变化心中有数。对应的迁移指南索引见 docs/migration/index.md。迁移概览v2 到底改了什么v2.0 是 Wpf.Ui 的一次大规模重构版本。从官方迁移文档docs/migration/v2-migration.md可以看出升级到 v2 主要面临三处关键变更全局命名空间变更WPF-UI更名为 .NET 生态更兼容的Wpf.Ui导航控件重写导航体系被再次重写几乎完全不兼容旧版本标题栏TitleBar重写同样几乎完全不兼容需要重新适配。这三点共同决定了v2 升级不是简单的包版本号替换而是需要动代码、动 XAML 的一次系统性迁移。下面逐一展开。全局命名空间变更从 WPF-UI 到 Wpf.Ui变更内容在 v2.0 中命名空间从WPF-UI改为与 .NET 生态更兼容的Wpf.Ui。NuGet 包名保持不变以维持品牌一致性与既有包引用习惯但代码层面的所有命名空间引用都需要更新。这一变更直接影响C# 代码中的using语句所有using WPFUI.*;需要替换为对应的using Wpf.Ui.*;XAML 中的命名空间声明xmlns:uiclr-namespace:WPFUI...;assembly...形式的声明需要同步更新到Wpf.Ui命名空间类型全名引用typeof()、反射、字符串化类型名等场景同样需要跟进。从当前仓库的源码结构可以确认这一演进的结果全部核心代码位于 src/Wpf.Ui 目录源码中的命名空间统一为Wpf.Ui.Controls例如 NavigationView.Base.cs 中的namespace Wpf.Ui.Controls;。迁移建议由于包名未变迁移步骤可以简化为将包版本升级到 v2.x全局搜索并替换命名空间前缀WPFUI→Wpf.Ui优先处理using与 XAMLxmlns声明重新编译根据编译错误逐个修复剩余的类型引用因为 v2 中部分控件已被重写见下文编译错误往往对应真实的行为差异。导航控件重写NavigationStore / NavigationFluent / NavigationCompact全新的导航基类体系v2 中导航控件被再次重写官方文档明确指出其兼容性几乎完全丧失。所有导航控件统一继承自Wpf.Ui.Controls.Navigation.NavigationBase基类并演化出三种面向不同界面形态的导航容器控件定位NavigationStore面向 Store 风格的导航容器支持Items与Footer区块NavigationFluent面向 Fluent 设计语言的导航容器结构与前者一致NavigationCompact紧凑型导航容器适合窄窗格 / 折叠侧栏场景三者共享相同的NavigationBase基类能力绑定Frame承载页面内容、通过Items/Footer组织导航项、内置页面预缓存与切换动画。完整 XAML 声明示例NavigationStore的典型声明如下来自 v2-migration.mdui:NavigationStore Frame{Binding ElementNameRootFrame} PrecacheFalse SelectedPageIndex-1 TransitionDuration200 TransitionTypeFadeInWithSlide ui:NavigationStore.Items ui:NavigationItem CacheTrue ContentHome IconHome24 PageTagdashboard PageType{x:Type pages:Dashboard} / ui:NavigationSeparator / /ui:NavigationStore.Items ui:NavigationStore.Footer ui:NavigationItem ClickNavigationButtonTheme_OnClick ContentTheme IconDarkTheme24 / /ui:NavigationStore.Footer /ui:NavigationStoreNavigationFluent除容器标签名不同外结构与用法完全一致ui:NavigationFluent Frame{Binding ElementNameRootFrame} PrecacheFalse SelectedPageIndex-1 TransitionDuration200 TransitionTypeFadeInWithSlide ui:NavigationFluent.Items ui:NavigationItem CacheTrue ContentHome IconHome24 PageTagdashboard PageType{x:Type pages:Dashboard} / ui:NavigationSeparator / /ui:NavigationFluent.Items ui:NavigationFluent.Footer ui:NavigationItem ClickNavigationButtonTheme_OnClick ContentTheme IconDarkTheme24 / /ui:NavigationFluent.Footer /ui:NavigationFluentNavigationCompact同理仅容器名不同ui:NavigationCompact Frame{Binding ElementNameRootFrame} PrecacheFalse SelectedPageIndex-1 TransitionDuration200 TransitionTypeFadeInWithSlide ui:NavigationCompact.Items ui:NavigationItem CacheTrue ContentHome IconHome24 PageTagdashboard PageType{x:Type pages:Dashboard} / ui:NavigationSeparator / /ui:NavigationCompact.Items ui:NavigationCompact.Footer ui:NavigationItem ClickNavigationButtonTheme_OnClick ContentTheme IconDarkTheme24 / /ui:NavigationCompact.Footer /ui:NavigationCompact核心属性与子元素语义上述三份示例中的属性与子元素是 v2 导航声明中最常使用的部分含义如下Frame绑定导航容器内部承载页面内容的Frame控件示例中通过ElementNameRootFrame引用是导航跳转的目标宿主Precache是否预缓存所有导航页面设为False表示按需加载降低启动开销SelectedPageIndex初始选中的导航项索引-1表示初始不选中任何项TransitionDuration页面切换动画时长毫秒示例中200即 200msTransitionType切换动画类型示例中使用FadeInWithSlide淡入伴随滑动Items导航容器集合属性定义主导航区可包含NavigationItem、NavigationSeparator等元素Footer导航容器集合属性定义导航底部区域常用于主题切换、设置入口等次级操作NavigationItemCache是否缓存该页面实例Content导航项显示文本如HomeIcon图标名如Home24、DarkTheme24对应 Fluent 图标字体的字符名PageTag页面的字符串标识如dashboard供代码按标签导航PageType页面类型如pages:Dashboard声明后导航即可据此实例化并跳转Click事件处理器Footer中的导航项常直接绑定点击事件如示例中的NavigationButtonTheme_OnClick切换主题NavigationSeparator导航分组之间的分隔线。从当前仓库源码看 v2 导航的后续演进需要特别说明的是上述三个 v2 控件在当前仓库源码中已不存在——搜索src目录找不到NavigationStore、NavigationFluent、NavigationCompact或NavigationBase的定义。原因是 v3 再次重构了导航体系根据 v3-migration.md所有导航控件被合并为单一的NavigationView受 WinUI 启发。这一点在源码中得到印证NavigationView.Base.cs 中NavigationView直接继承System.Windows.Controls.Control并实现INavigationView其头注释明确标注 Based on Windows UI Library。对迁移者的实际意义在于如果从 v1 直接升到 v3/v4应直接使用新的 NavigationView 体系而不是 v2 的三种容器如果按 v2 的 XAML 写法迁移到现代版本需要把NavigationStore/Fluent/Compact统一替换为NavigationViewv2 引入的缓存与导航字典思想被完整继承当前NavigationView内部维护了PageIdOrTargetTagNavigationViewsDictionary按PageTag索引、PageTypeNavigationViewsDictionary按页面类型索引等字典结构见 NavigationView.Base.cs这与 v2 中PageTagPageType的设计一脉相承页面缓存策略则对应 NavigationCache.cs 与 NavigationCacheMode.cs。标题栏重写从自定义模板到内置窗口集成变更内容与导航控件一样v2 的TitleBar 控件也被重写且几乎完全不兼容。对使用旧版标题栏样式的项目升级后原有的自定义模板、样式键和附加属性很可能失效需要按新版本 API 重新声明。当前仓库中的 TitleBar 实现从当前仓库源码看标题栏能力已被深度重构并集成进窗口体系TitleBar.cs 中的TitleBar控件实现了IThemeControl接口意味着它直接参与 Wpf.Ui 的主题体系可感知并跟随应用主题切换该控件通过TemplatePart声明了完整的内建结构PART_Icon窗口图标、PART_MainGrid、PART_HelpButton帮助按钮、PART_MinimizeButton最小化、PART_MaximizeButton最大化、PART_RestoreButton还原、PART_CloseButton关闭见 TitleBar.cs标题栏不再作为孤立控件拼装而是与 FluentWindow.cs继承System.Windows.Window深度绑定由窗口负责标题栏的呈现与窗口消息如WndProcInvoked事件见 TitleBar.cs处理。迁移适配建议放弃旧版标题栏模板v2 起不要继续沿用 v1 的自定义 TitleBar 样式与模板应改为使用窗口自带的标题栏能力改用FluentWindow自定义窗口优先以FluentWindow作为基类从而获得内置标题栏与主题联动而不是在普通Window上手动拼装标题栏控件自定义按钮行为如需在标题栏追加自定义操作可从PART_HelpButton等内建按钮的模板部件入手或参考 TitleBarButton.cs 的按钮类型进行扩展验证窗口交互由于 v2 起标题栏深度介入 Win32 窗口过程涉及窗口拖动、大小调整与系统菜单升级后需重点回归窗口的缩放、拖动、贴靠等交互行为。相关实现可进一步查阅 TitleBar.WindowResize.cs。迁移检查清单综合以上三个核心变更将 v1 项目升级到 v2 时的最小检查项如下命名空间全局替换WPF-UI→Wpf.Uiusing与 XAMLxmlns确认包名保持不变导航声明将旧导航 XAML 重写为NavigationStore/NavigationFluent/NavigationCompact之一按需设置Frame、Precache、SelectedPageIndex、TransitionDuration、TransitionType并用NavigationItemContent/Icon/PageTag/PageType与NavigationSeparator组织Items和Footer标题栏弃用旧版 TitleBar 自定义模板改以FluentWindow为窗口基类借助内建TitleBar部件完成最小化、最大化、关闭与主题联动编译验证以编译器报错为向导逐个清理被重写 API 的残留引用行为回归重点回归导航缓存/切换动画与窗口系统交互。附v2 之后的版本脉络了解 v2 之后的路有助于迁移时选择合适的目标版本详见 docs/migration/index.mdv3导航控件合并为单一NavigationView引入新的IconElement图标体系FontIcon、SymbolIcon、ImageIcon等见 src/Wpf.Ui/Controls/IconElement取代旧图标方案ContentDialog、MessageBox、Snackbar接口不完全兼容v3-migration.mdv4接口层拆分出独立的Wpf.Ui.Abstractions包自动随主包引入IPageService更名为INavigationViewPageProvider并可通过services.AddNavigationViewPageProvider()实现基于依赖注入的页面创建v4-migration.md。如果你正从 v1 直接迁移到 v3/v4建议把本文 v2 的导航示例作为理解NavigationView属性和页面组织方式的背景知识再按 v3-migration.md 与 v4-migration.md 完成后续两步即可一步到位。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wpf.Ui v2 迁移指南：命名空间重构、导航体系重写与标题栏适配全解析
Wpf.Ui v2 迁移指南命名空间重构、导航体系重写与标题栏适配全解析【免费下载链接】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.UiWPF UIv2.0 的关键破坏性变更展开聚焦全局命名空间调整、导航控件体系重写与标题栏重构三大主题并对照当前仓库源码说明迁移后的实际形态与后续演进。读完本文你将掌握从 WPF-UI 旧命名空间平滑切换至Wpf.Ui的路径、v2 导航控件的声明方式与核心参数语义以及重写后的标题栏在自定义窗口中的适配要点。本文是 v2 迁移的快速参考手册而非逐行逐步的完整教程它不覆盖每个 API 的逐一替换而是把迁移过程中最容易踩坑、影响面最大的部分拎出来让你在动手升级前对全局变化心中有数。对应的迁移指南索引见 docs/migration/index.md。迁移概览v2 到底改了什么v2.0 是 Wpf.Ui 的一次大规模重构版本。从官方迁移文档docs/migration/v2-migration.md可以看出升级到 v2 主要面临三处关键变更全局命名空间变更WPF-UI更名为 .NET 生态更兼容的Wpf.Ui导航控件重写导航体系被再次重写几乎完全不兼容旧版本标题栏TitleBar重写同样几乎完全不兼容需要重新适配。这三点共同决定了v2 升级不是简单的包版本号替换而是需要动代码、动 XAML 的一次系统性迁移。下面逐一展开。全局命名空间变更从 WPF-UI 到 Wpf.Ui变更内容在 v2.0 中命名空间从WPF-UI改为与 .NET 生态更兼容的Wpf.Ui。NuGet 包名保持不变以维持品牌一致性与既有包引用习惯但代码层面的所有命名空间引用都需要更新。这一变更直接影响C# 代码中的using语句所有using WPFUI.*;需要替换为对应的using Wpf.Ui.*;XAML 中的命名空间声明xmlns:uiclr-namespace:WPFUI...;assembly...形式的声明需要同步更新到Wpf.Ui命名空间类型全名引用typeof()、反射、字符串化类型名等场景同样需要跟进。从当前仓库的源码结构可以确认这一演进的结果全部核心代码位于 src/Wpf.Ui 目录源码中的命名空间统一为Wpf.Ui.Controls例如 NavigationView.Base.cs 中的namespace Wpf.Ui.Controls;。迁移建议由于包名未变迁移步骤可以简化为将包版本升级到 v2.x全局搜索并替换命名空间前缀WPFUI→Wpf.Ui优先处理using与 XAMLxmlns声明重新编译根据编译错误逐个修复剩余的类型引用因为 v2 中部分控件已被重写见下文编译错误往往对应真实的行为差异。导航控件重写NavigationStore / NavigationFluent / NavigationCompact全新的导航基类体系v2 中导航控件被再次重写官方文档明确指出其兼容性几乎完全丧失。所有导航控件统一继承自Wpf.Ui.Controls.Navigation.NavigationBase基类并演化出三种面向不同界面形态的导航容器控件定位NavigationStore面向 Store 风格的导航容器支持Items与Footer区块NavigationFluent面向 Fluent 设计语言的导航容器结构与前者一致NavigationCompact紧凑型导航容器适合窄窗格 / 折叠侧栏场景三者共享相同的NavigationBase基类能力绑定Frame承载页面内容、通过Items/Footer组织导航项、内置页面预缓存与切换动画。完整 XAML 声明示例NavigationStore的典型声明如下来自 v2-migration.mdui:NavigationStore Frame{Binding ElementNameRootFrame} PrecacheFalse SelectedPageIndex-1 TransitionDuration200 TransitionTypeFadeInWithSlide ui:NavigationStore.Items ui:NavigationItem CacheTrue ContentHome IconHome24 PageTagdashboard PageType{x:Type pages:Dashboard} / ui:NavigationSeparator / /ui:NavigationStore.Items ui:NavigationStore.Footer ui:NavigationItem ClickNavigationButtonTheme_OnClick ContentTheme IconDarkTheme24 / /ui:NavigationStore.Footer /ui:NavigationStoreNavigationFluent除容器标签名不同外结构与用法完全一致ui:NavigationFluent Frame{Binding ElementNameRootFrame} PrecacheFalse SelectedPageIndex-1 TransitionDuration200 TransitionTypeFadeInWithSlide ui:NavigationFluent.Items ui:NavigationItem CacheTrue ContentHome IconHome24 PageTagdashboard PageType{x:Type pages:Dashboard} / ui:NavigationSeparator / /ui:NavigationFluent.Items ui:NavigationFluent.Footer ui:NavigationItem ClickNavigationButtonTheme_OnClick ContentTheme IconDarkTheme24 / /ui:NavigationFluent.Footer /ui:NavigationFluentNavigationCompact同理仅容器名不同ui:NavigationCompact Frame{Binding ElementNameRootFrame} PrecacheFalse SelectedPageIndex-1 TransitionDuration200 TransitionTypeFadeInWithSlide ui:NavigationCompact.Items ui:NavigationItem CacheTrue ContentHome IconHome24 PageTagdashboard PageType{x:Type pages:Dashboard} / ui:NavigationSeparator / /ui:NavigationCompact.Items ui:NavigationCompact.Footer ui:NavigationItem ClickNavigationButtonTheme_OnClick ContentTheme IconDarkTheme24 / /ui:NavigationCompact.Footer /ui:NavigationCompact核心属性与子元素语义上述三份示例中的属性与子元素是 v2 导航声明中最常使用的部分含义如下Frame绑定导航容器内部承载页面内容的Frame控件示例中通过ElementNameRootFrame引用是导航跳转的目标宿主Precache是否预缓存所有导航页面设为False表示按需加载降低启动开销SelectedPageIndex初始选中的导航项索引-1表示初始不选中任何项TransitionDuration页面切换动画时长毫秒示例中200即 200msTransitionType切换动画类型示例中使用FadeInWithSlide淡入伴随滑动Items导航容器集合属性定义主导航区可包含NavigationItem、NavigationSeparator等元素Footer导航容器集合属性定义导航底部区域常用于主题切换、设置入口等次级操作NavigationItemCache是否缓存该页面实例Content导航项显示文本如HomeIcon图标名如Home24、DarkTheme24对应 Fluent 图标字体的字符名PageTag页面的字符串标识如dashboard供代码按标签导航PageType页面类型如pages:Dashboard声明后导航即可据此实例化并跳转Click事件处理器Footer中的导航项常直接绑定点击事件如示例中的NavigationButtonTheme_OnClick切换主题NavigationSeparator导航分组之间的分隔线。从当前仓库源码看 v2 导航的后续演进需要特别说明的是上述三个 v2 控件在当前仓库源码中已不存在——搜索src目录找不到NavigationStore、NavigationFluent、NavigationCompact或NavigationBase的定义。原因是 v3 再次重构了导航体系根据 v3-migration.md所有导航控件被合并为单一的NavigationView受 WinUI 启发。这一点在源码中得到印证NavigationView.Base.cs 中NavigationView直接继承System.Windows.Controls.Control并实现INavigationView其头注释明确标注 Based on Windows UI Library。对迁移者的实际意义在于如果从 v1 直接升到 v3/v4应直接使用新的 NavigationView 体系而不是 v2 的三种容器如果按 v2 的 XAML 写法迁移到现代版本需要把NavigationStore/Fluent/Compact统一替换为NavigationViewv2 引入的缓存与导航字典思想被完整继承当前NavigationView内部维护了PageIdOrTargetTagNavigationViewsDictionary按PageTag索引、PageTypeNavigationViewsDictionary按页面类型索引等字典结构见 NavigationView.Base.cs这与 v2 中PageTagPageType的设计一脉相承页面缓存策略则对应 NavigationCache.cs 与 NavigationCacheMode.cs。标题栏重写从自定义模板到内置窗口集成变更内容与导航控件一样v2 的TitleBar 控件也被重写且几乎完全不兼容。对使用旧版标题栏样式的项目升级后原有的自定义模板、样式键和附加属性很可能失效需要按新版本 API 重新声明。当前仓库中的 TitleBar 实现从当前仓库源码看标题栏能力已被深度重构并集成进窗口体系TitleBar.cs 中的TitleBar控件实现了IThemeControl接口意味着它直接参与 Wpf.Ui 的主题体系可感知并跟随应用主题切换该控件通过TemplatePart声明了完整的内建结构PART_Icon窗口图标、PART_MainGrid、PART_HelpButton帮助按钮、PART_MinimizeButton最小化、PART_MaximizeButton最大化、PART_RestoreButton还原、PART_CloseButton关闭见 TitleBar.cs标题栏不再作为孤立控件拼装而是与 FluentWindow.cs继承System.Windows.Window深度绑定由窗口负责标题栏的呈现与窗口消息如WndProcInvoked事件见 TitleBar.cs处理。迁移适配建议放弃旧版标题栏模板v2 起不要继续沿用 v1 的自定义 TitleBar 样式与模板应改为使用窗口自带的标题栏能力改用FluentWindow自定义窗口优先以FluentWindow作为基类从而获得内置标题栏与主题联动而不是在普通Window上手动拼装标题栏控件自定义按钮行为如需在标题栏追加自定义操作可从PART_HelpButton等内建按钮的模板部件入手或参考 TitleBarButton.cs 的按钮类型进行扩展验证窗口交互由于 v2 起标题栏深度介入 Win32 窗口过程涉及窗口拖动、大小调整与系统菜单升级后需重点回归窗口的缩放、拖动、贴靠等交互行为。相关实现可进一步查阅 TitleBar.WindowResize.cs。迁移检查清单综合以上三个核心变更将 v1 项目升级到 v2 时的最小检查项如下命名空间全局替换WPF-UI→Wpf.Uiusing与 XAMLxmlns确认包名保持不变导航声明将旧导航 XAML 重写为NavigationStore/NavigationFluent/NavigationCompact之一按需设置Frame、Precache、SelectedPageIndex、TransitionDuration、TransitionType并用NavigationItemContent/Icon/PageTag/PageType与NavigationSeparator组织Items和Footer标题栏弃用旧版 TitleBar 自定义模板改以FluentWindow为窗口基类借助内建TitleBar部件完成最小化、最大化、关闭与主题联动编译验证以编译器报错为向导逐个清理被重写 API 的残留引用行为回归重点回归导航缓存/切换动画与窗口系统交互。附v2 之后的版本脉络了解 v2 之后的路有助于迁移时选择合适的目标版本详见 docs/migration/index.mdv3导航控件合并为单一NavigationView引入新的IconElement图标体系FontIcon、SymbolIcon、ImageIcon等见 src/Wpf.Ui/Controls/IconElement取代旧图标方案ContentDialog、MessageBox、Snackbar接口不完全兼容v3-migration.mdv4接口层拆分出独立的Wpf.Ui.Abstractions包自动随主包引入IPageService更名为INavigationViewPageProvider并可通过services.AddNavigationViewPageProvider()实现基于依赖注入的页面创建v4-migration.md。如果你正从 v1 直接迁移到 v3/v4建议把本文 v2 的导航示例作为理解NavigationView属性和页面组织方式的背景知识再按 v3-migration.md 与 v4-migration.md 完成后续两步即可一步到位。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考