CustomWPFUI 1.2.0

说明

此工程基于开源的WPFUI控件库，进行二次开发。
为了更好的区分新增功能，会使用 Custom作为新增目录的命名前缀
具体文件的命名，跟随WPFUI库的命名规范

命名规范：

Style : 尽可能使用key，而不是全局默认样式，
        key命名参考Nodify库，控件名+"."+样式名，
例如"Button.neon" //霓虹灯效果的Button

计划：

主题优化

1. Light主题在WPFGallery中效果不太好，太白，期望增加LightBlue/Light紫色【已实现 ✅️】
2. 增加深蓝主题 【已实现 ✅️】

框架优化：

1. 支持key资源枚举化，方便在设计时选择【未实现 ❌️】
2. 增加插件框架

资源补充：

1. 增加自定义颜色与画刷（尽量采用wpfui的定义），增加常用渐变画刷
2. 增加语义化的动画效果

控件优化：

- 导航控件：增加Gridsplit，建议手动调整宽度【已实现 ✅️】
- 导航控件：增加前进功能【已实现 ✅️】
- 修改DataGrid行选择bug【已实现 ✅️】
- listview/DataGrid，插入行时有动画效果【未实现 ❌️】
- Textbox增加输入文字校验功能
- TitilBar优化，支持Xaml中设置Margin
- 带筛选/搜索功能的下拉框【未实现 ❌️】
- TabControlEx："可关闭的Tab"【已实现 ✅️】
- 支持拖动调整Tab位置【未实现 ❌️】
- TabControl，Tab页面较多时，支持Tab标题的滚动（ 优化滚动条功能）【未实现 ❌️】
- 优化TabControl样式，使得当前选中的Tab标题更明显（下划线、字体加粗、背景色变化）【已实现 ✅️】
- 优化DataTime控件【已实现 ✅️】
- 优化ToolBar样式【ToolBar中的Combobox/ ToggleButton】【已实现 ✅️】
- 

控件：

- 增加"抽屉"控件【已实现 ✅️】
- 合并 Wpf.Ui.ToastNotifications 到工程中，提供了应用内的通知功能

WPF UI 主题与配色应用文档

本文档详细介绍如何在WPF UI应用程序中使用主题和配色系统，包括内置颜色的使用、自定义控件的适配以及主题切换的实现。

1. WPF UI 配色系统概述

1.1 主题资源架构

WPF UI 提供了一套完整的主题系统，位于 Wpf.Ui.Resources.Theme 命名空间下：

Wpf.Ui/Resources/Theme/
├── Light.xaml          # 浅色主题
├── Dark.xaml           # 深色主题
├── SlateDark.xaml      # 石板深色主题
├── LightBlue.xaml      # 浅蓝色主题
├── LightPurple.xaml    # 浅紫色主题
├── HC1.xaml            # 高对比度主题1
├── HC2.xaml            # 高对比度主题2
├── HCBlack.xaml        # 高对比度黑色主题
└── HCWhite.xaml        # 高对比度白色主题

1.2 颜色资源分类

WPF UI 的颜色资源按功能分为以下几类：

文本颜色 (Text Fill Colors)

• TextFillColorPrimary - 主要文本颜色
• TextFillColorSecondary - 次要文本颜色
• TextFillColorTertiary - 第三级文本颜色
• TextFillColorDisabled - 禁用状态文本颜色
• TextPlaceholderColor - 占位符文本颜色

控件填充颜色 (Control Fill Colors)

• ControlFillColorDefault - 默认控件背景
• ControlFillColorSecondary - 次要控件背景
• ControlFillColorTertiary - 第三级控件背景
• ControlFillColorDisabled - 禁用状态背景
• ControlFillColorTransparent - 透明背景
• ControlFillColorInputActive - 输入框激活状态

控件边框颜色 (Control Stroke Colors)

• ControlStrokeColorDefault - 默认边框颜色
• ControlStrokeColorSecondary - 次要边框颜色
• ControlStrokeColorTertiary - 第三级边框颜色

强调色 (Accent Colors)

• SystemAccentColor - 系统强调色
• SystemAccentColorPrimary - 主要强调色
• SystemAccentColorSecondary - 次要强调色
• SystemAccentColorTertiary - 第三级强调色

背景和图层颜色

• ApplicationBackgroundColor - 应用背景色
• LayerFillColorDefault - 默认图层颜色
• CardBackgroundFillColorDefault - 卡片背景色

1.3 使用方式

所有颜色都提供两种形式：

• Color - 原始颜色值（如 TextFillColorPrimary）
• Brush - 画刷形式（如 TextFillColorPrimaryBrush）

1.4 ThemeResource 枚举参考

WPF UI 提供了 ThemeResource 枚举，包含所有可用的主题资源。以下是完整的枚举列表：

基础与未定义

枚举值	中文说明	使用场景
Unknown	未指定的主题资源	默认值，表示未指定

强调色 (Accent Colors)

枚举值	中文说明	使用场景
SystemAccentColor	系统强调色	获取系统当前强调色
SystemAccentColorPrimary	主要强调色	主要按钮、选中状态
SystemAccentColorSecondary	次要强调色	次要强调元素
SystemAccentColorTertiary	第三级强调色	轻微强调
SystemAccentColorPrimaryBrush	主要强调色画刷	绑定到主要强调色
SystemAccentColorSecondaryBrush	次要强调色画刷	绑定到次要强调色
SystemAccentColorTertiaryBrush	第三级强调色画刷	绑定到第三级强调色
AccentTextFillColorPrimaryBrush	强调文本主要填充色画刷	强调背景上的文本
AccentTextFillColorSecondaryBrush	强调文本次要填充色画刷	强调背景上的次要文本
AccentTextFillColorTertiaryBrush	强调文本第三级填充色画刷	强调背景上的提示文本

背景色 (Background)

枚举值	中文说明	使用场景
ApplicationBackgroundColor	应用背景色	窗口背景
ApplicationBackgroundBrush	应用背景色画刷	绑定到窗口背景

焦点 (Focus)

枚举值	中文说明	使用场景
KeyboardFocusBorderColor	键盘焦点边框色	焦点状态边框
KeyboardFocusBorderColorBrush	键盘焦点边框色画刷	绑定到焦点边框

文本颜色 (Text Colors)

枚举值	中文说明	使用场景
TextFillColorPrimary	文本主要填充色	正文、标题
TextFillColorSecondary	文本次要填充色	描述、副标题
TextFillColorTertiary	文本第三级填充色	提示、占位符
TextFillColorDisabled	文本禁用填充色	禁用状态文本
TextPlaceholderColor	占位符文本颜色	输入框占位符
TextFillColorInverse	文本反色填充	深色背景上的浅色文本
AccentTextFillColorDisabled	强调文本禁用填充色	禁用状态的强调文本
TextOnAccentFillColorSelectedText	强调背景上的选中文本色	选中状态的文本
TextOnAccentFillColorPrimary	强调背景上的主要文本色	强调色背景上的主文本
TextOnAccentFillColorSecondary	强调背景上的次要文本色	强调色背景上的次文本
TextOnAccentFillColorDisabled	强调背景上的禁用文本色	强调色背景上的禁用文本

控件填充色 (Control Fill Colors)

枚举值	中文说明	使用场景
ControlFillColorDefault	控件默认填充色	按钮、输入框背景
ControlFillColorSecondary	控件次要填充色	悬停状态背景
ControlFillColorTertiary	控件第三级填充色	按下状态背景
ControlFillColorDisabled	控件禁用填充色	禁用状态背景
ControlFillColorTransparent	控件透明填充色	透明背景
ControlFillColorInputActive	控件输入激活填充色	输入框激活状态
ControlStrongFillColorDefault	控件强填充默认色	强对比度背景
ControlStrongFillColorDisabled	控件强填充禁用色	强对比度禁用背景
ControlSolidFillColorDefault	控件实色填充默认色	实色背景
SubtleFillColorTransparent	微妙填充透明色	微妙透明效果
SubtleFillColorSecondary	微妙填充次要色	微妙次要效果
SubtleFillColorTertiary	微妙填充第三级色	微妙第三级效果
SubtleFillColorDisabled	微妙填充禁用色	微妙禁用效果
ControlAltFillColorTransparent	控件替代填充透明色	替代透明背景
ControlAltFillColorSecondary	控件替代填充次要色	替代次要背景
ControlAltFillColorTertiary	控件替代填充第三级色	替代第三级背景
ControlAltFillColorQuarternary	控件替代填充第四级色	替代第四级背景
ControlAltFillColorDisabled	控件替代填充禁用色	替代禁用背景
ControlOnImageFillColorDefault	图片上控件默认填充色	图片上的控件背景
ControlOnImageFillColorSecondary	图片上控件次要填充色	图片上的悬停状态
ControlOnImageFillColorTertiary	图片上控件第三级填充色	图片上的按下状态
ControlOnImageFillColorDisabled	图片上控件禁用填充色	图片上的禁用状态
AccentFillColorDisabled	强调填充禁用色	强调色的禁用状态

控件边框色 (Control Stroke Colors)

枚举值	中文说明	使用场景
ControlStrokeColorDefault	控件默认边框色	默认边框
ControlStrokeColorSecondary	控件次要边框色	悬停状态边框
ControlStrokeColorTertiary	控件第三级边框色	按下状态边框
ControlStrokeColorOnAccentDefault	强调背景上控件默认边框色	强调色上的默认边框
ControlStrokeColorOnAccentSecondary	强调背景上控件次要边框色	强调色上的次要边框
ControlStrokeColorOnAccentTertiary	强调背景上控件第三级边框色	强调色上的第三级边框
ControlStrokeColorOnAccentDisabled	强调背景上控件禁用边框色	强调色上的禁用边框
ControlStrokeColorForStrongFillWhenOnImage	图片上强填充控件边框色	图片上的强边框
CardStrokeColorDefault	卡片默认边框色	卡片边框
CardStrokeColorDefaultSolid	卡片默认实色边框	卡片实色边框
ControlStrongStrokeColorDefault	控件强边框默认色	强对比度边框
ControlStrongStrokeColorDisabled	控件强边框禁用色	强对比度禁用边框
SurfaceStrokeColorDefault	表面默认边框色	表面边框
SurfaceStrokeColorFlyout	浮出控件边框色	菜单、弹出框边框
SurfaceStrokeColorInverse	表面反色边框	反色表面边框
DividerStrokeColorDefault	分隔线默认边框色	分隔线
FocusStrokeColorOuter	焦点外边框色	焦点外圈
FocusStrokeColorInner	焦点内边框色	焦点内圈

卡片与图层 (Cards & Layers)

枚举值	中文说明	使用场景
CardBackgroundFillColorDefault	卡片背景默认填充色	卡片背景
CardBackgroundFillColorSecondary	卡片背景次要填充色	卡片次要背景
SmokeFillColorDefault	烟雾填充默认色	遮罩层、模态框背景
LayerFillColorDefault	图层默认填充色	默认图层
LayerFillColorAlt	图层替代填充色	替代图层
LayerOnAcrylicFillColorDefault	亚克力图层默认填充色	亚克力效果图层
LayerOnAccentAcrylicFillColorDefault	强调亚克力图层默认填充色	强调色亚克力图层
LayerOnMicaBaseAltFillColorDefault	Mica基底替代图层默认填充色	Mica效果默认图层
LayerOnMicaBaseAltFillColorSecondary	Mica基底替代图层次要填充色	Mica效果次要图层
LayerOnMicaBaseAltFillColorTertiary	Mica基底替代图层第三级填充色	Mica效果第三级图层
LayerOnMicaBaseAltFillColorTransparent	Mica基底替代图层透明填充色	Mica效果透明图层

纯色背景 (Solid Backgrounds)

枚举值	中文说明	使用场景
SolidBackgroundFillColorBase	纯色背景基础填充色	纯色基础背景
SolidBackgroundFillColorSecondary	纯色背景次要填充色	纯色次要背景
SolidBackgroundFillColorTertiary	纯色背景第三级填充色	纯色第三级背景
SolidBackgroundFillColorQuarternary	纯色背景第四级填充色	纯色第四级背景
SolidBackgroundFillColorTransparent	纯色背景透明填充色	纯色透明背景
SolidBackgroundFillColorBaseAlt	纯色背景基础替代填充色	纯色替代基础背景

系统状态色 (System Status Colors)

枚举值	中文说明	使用场景
SystemFillColorSuccess	系统成功填充色	成功状态指示
SystemFillColorCaution	系统警告填充色	警告状态指示
SystemFillColorCritical	系统严重填充色	错误状态指示
SystemFillColorNeutral	系统中性填充色	中性状态指示
SystemFillColorSolidNeutral	系统实色中性填充色	实色中性指示
SystemFillColorAttentionBackground	系统注意背景填充色	注意状态背景
SystemFillColorSuccessBackground	系统成功背景填充色	成功状态背景
SystemFillColorCautionBackground	系统警告背景填充色	警告状态背景
SystemFillColorCriticalBackground	系统严重背景填充色	错误状态背景
SystemFillColorNeutralBackground	系统中性背景填充色	中性状态背景
SystemFillColorSolidAttentionBackground	系统实色注意背景填充色	实色注意背景
SystemFillColorSolidNeutralBackground	系统实色中性背景填充色	实色中性背景

文本画刷 (Text Brushes)

枚举值	中文说明	使用场景
TextFillColorPrimaryBrush	文本主要填充色画刷	绑定到主要文本
TextFillColorSecondaryBrush	文本次要填充色画刷	绑定到次要文本
TextFillColorTertiaryBrush	文本第三级填充色画刷	绑定到第三级文本
TextFillColorDisabledBrush	文本禁用填充色画刷	绑定到禁用文本
TextPlaceholderColorBrush	占位符文本颜色画刷	绑定到占位符
TextFillColorInverseBrush	文本反色填充画刷	绑定到反色文本
AccentTextFillColorDisabledBrush	强调文本禁用填充色画刷	绑定到禁用强调文本
TextOnAccentFillColorSelectedTextBrush	强调背景上的选中文本色画刷	绑定到选中强调文本
TextOnAccentFillColorPrimaryBrush	强调背景上的主要文本色画刷	绑定到主要强调文本
TextOnAccentFillColorSecondaryBrush	强调背景上的次要文本色画刷	绑定到次要强调文本
TextOnAccentFillColorDisabledBrush	强调背景上的禁用文本色画刷	绑定到禁用强调文本

控件填充画刷 (Control Fill Brushes)

枚举值	中文说明	使用场景
ControlFillColorDefaultBrush	控件默认填充色画刷	绑定到默认控件背景
ControlFillColorSecondaryBrush	控件次要填充色画刷	绑定到悬停控件背景
ControlFillColorTertiaryBrush	控件第三级填充色画刷	绑定到按下控件背景
ControlFillColorDisabledBrush	控件禁用填充色画刷	绑定到禁用控件背景
ControlFillColorTransparentBrush	控件透明填充色画刷	绑定到透明控件背景
ControlFillColorInputActiveBrush	控件输入激活填充色画刷	绑定到激活输入框
ControlStrongFillColorDefaultBrush	控件强填充默认色画刷	绑定到强对比度背景
ControlStrongFillColorDisabledBrush	控件强填充禁用色画刷	绑定到强对比度禁用背景
ControlSolidFillColorDefaultBrush	控件实色填充默认色画刷	绑定到实色背景
SubtleFillColorTransparentBrush	微妙填充透明色画刷	绑定到微妙透明效果
SubtleFillColorSecondaryBrush	微妙填充次要色画刷	绑定到微妙次要效果
SubtleFillColorTertiaryBrush	微妙填充第三级色画刷	绑定到微妙第三级效果
SubtleFillColorDisabledBrush	微妙填充禁用色画刷	绑定到微妙禁用效果
ControlAltFillColorTransparentBrush	控件替代填充透明色画刷	绑定到替代透明背景
ControlAltFillColorSecondaryBrush	控件替代填充次要色画刷	绑定到替代次要背景
ControlAltFillColorTertiaryBrush	控件替代填充第三级色画刷	绑定到替代第三级背景
ControlAltFillColorQuarternaryBrush	控件替代填充第四级色画刷	绑定到替代第四级背景
ControlAltFillColorDisabledBrush	控件替代填充禁用色画刷	绑定到替代禁用背景
ControlOnImageFillColorDefaultBrush	图片上控件默认填充色画刷	绑定到图片上控件
ControlOnImageFillColorSecondaryBrush	图片上控件次要填充色画刷	绑定到图片上悬停
ControlOnImageFillColorTertiaryBrush	图片上控件第三级填充色画刷	绑定到图片上按下
ControlOnImageFillColorDisabledBrush	图片上控件禁用填充色画刷	绑定到图片上禁用
AccentFillColorDisabledBrush	强调填充禁用色画刷	绑定到强调禁用状态

控件边框画刷 (Control Stroke Brushes)

枚举值	中文说明	使用场景
ControlStrokeColorDefaultBrush	控件默认边框色画刷	绑定到默认边框
ControlStrokeColorSecondaryBrush	控件次要边框色画刷	绑定到悬停边框
ControlStrokeColorTertiaryBrush	控件第三级边框色画刷	绑定到按下边框
ControlStrokeColorOnAccentDefaultBrush	强调背景上控件默认边框色画刷	绑定到强调默认边框
ControlStrokeColorOnAccentSecondaryBrush	强调背景上控件次要边框色画刷	绑定到强调次要边框
ControlStrokeColorOnAccentTertiaryBrush	强调背景上控件第三级边框色画刷	绑定到强调第三级边框
ControlStrokeColorOnAccentDisabledBrush	强调背景上控件禁用边框色画刷	绑定到强调禁用边框
ControlStrokeColorForStrongFillWhenOnImageBrush	图片上强填充控件边框色画刷	绑定到图片强边框
CardStrokeColorDefaultBrush	卡片默认边框色画刷	绑定到卡片边框
CardStrokeColorDefaultSolidBrush	卡片默认实色边框画刷	绑定到卡片实色边框
ControlStrongStrokeColorDefaultBrush	控件强边框默认色画刷	绑定到强对比度边框
ControlStrongStrokeColorDisabledBrush	控件强边框禁用色画刷	绑定到强对比度禁用边框
SurfaceStrokeColorDefaultBrush	表面默认边框色画刷	绑定到表面边框
SurfaceStrokeColorFlyoutBrush	浮出控件边框色画刷	绑定到浮出控件边框
SurfaceStrokeColorInverseBrush	表面反色边框画刷	绑定到反色表面边框
DividerStrokeColorDefaultBrush	分隔线默认边框色画刷	绑定到分隔线
FocusStrokeColorOuterBrush	焦点外边框色画刷	绑定到焦点外圈
FocusStrokeColorInnerBrush	焦点内边框色画刷	绑定到焦点内圈

卡片与图层画刷 (Card & Layer Brushes)

枚举值	中文说明	使用场景
CardBackgroundFillColorDefaultBrush	卡片背景默认填充色画刷	绑定到卡片背景
CardBackgroundFillColorSecondaryBrush	卡片背景次要填充色画刷	绑定到卡片次要背景
SmokeFillColorDefaultBrush	烟雾填充默认色画刷	绑定到遮罩层
LayerFillColorDefaultBrush	图层默认填充色画刷	绑定到默认图层
LayerFillColorAltBrush	图层替代填充色画刷	绑定到替代图层
LayerOnAcrylicFillColorDefaultBrush	亚克力图层默认填充色画刷	绑定到亚克力图层
LayerOnAccentAcrylicFillColorDefaultBrush	强调亚克力图层默认填充色画刷	绑定到强调亚克力图层
LayerOnMicaBaseAltFillColorDefaultBrush	Mica基底替代图层默认填充色画刷	绑定到Mica默认图层
LayerOnMicaBaseAltFillColorSecondaryBrush	Mica基底替代图层次要填充色画刷	绑定到Mica次要图层
LayerOnMicaBaseAltFillColorTertiaryBrush	Mica基底替代图层第三级填充色画刷	绑定到Mica第三级图层
LayerOnMicaBaseAltFillColorTransparentBrush	Mica基底替代图层透明填充色画刷	绑定到Mica透明图层

纯色背景画刷 (Solid Background Brushes)

枚举值	中文说明	使用场景
SolidBackgroundFillColorBaseBrush	纯色背景基础填充色画刷	绑定到纯色基础背景
SolidBackgroundFillColorSecondaryBrush	纯色背景次要填充色画刷	绑定到纯色次要背景
SolidBackgroundFillColorTertiaryBrush	纯色背景第三级填充色画刷	绑定到纯色第三级背景
SolidBackgroundFillColorQuarternaryBrush	纯色背景第四级填充色画刷	绑定到纯色第四级背景
SolidBackgroundFillColorBaseAltBrush	纯色背景基础替代填充色画刷	绑定到纯色替代基础背景

系统状态画刷 (System Status Brushes)

枚举值	中文说明	使用场景
SystemFillColorSuccessBrush	系统成功填充色画刷	绑定到成功状态
SystemFillColorCautionBrush	系统警告填充色画刷	绑定到警告状态
SystemFillColorCriticalBrush	系统严重填充色画刷	绑定到错误状态
SystemFillColorNeutralBrush	系统中性填充色画刷	绑定到中性状态
SystemFillColorSolidNeutralBrush	系统实色中性填充色画刷	绑定到实色中性状态
SystemFillColorAttentionBackgroundBrush	系统注意背景填充色画刷	绑定到注意背景
SystemFillColorSuccessBackgroundBrush	系统成功背景填充色画刷	绑定到成功背景
SystemFillColorCautionBackgroundBrush	系统警告背景填充色画刷	绑定到警告背景
SystemFillColorCriticalBackgroundBrush	系统严重背景填充色画刷	绑定到错误背景
SystemFillColorNeutralBackgroundBrush	系统中性背景填充色画刷	绑定到中性背景
SystemFillColorSolidAttentionBackgroundBrush	系统实色注意背景填充色画刷	绑定到实色注意背景
SystemFillColorSolidNeutralBackgroundBrush	系统实色中性背景填充色画刷	绑定到实色中性背景

渐变画刷 (Gradient Brushes)

枚举值	中文说明	使用场景
ControlElevationBorderBrush	控件提升边框渐变画刷	提升效果边框
CircleElevationBorderBrush	圆形提升边框渐变画刷	圆形提升效果
AccentControlElevationBorderBrush	强调控件提升边框渐变画刷	强调色提升效果

---

2. 在应用中使用WPF UI颜色

2.1 基础用法 - DynamicResource

在XAML中使用 DynamicResource 引用主题颜色：

<Window xmlns:ui="http://CustomWPFUI.co/2022/xaml">
    <Grid>
        
        <TextBlock 
            Text="主要文本"
            Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
        
        
        <Border 
            Background="{DynamicResource ControlFillColorDefaultBrush}"
            BorderBrush="{DynamicResource ControlStrokeColorDefaultBrush}"
            BorderThickness="1">
            <TextBlock Text="带边框的内容" />
        </Border>
    </Grid>
</Window>

2.2 使用 ThemeResource 标记扩展

WPF UI 提供了 ThemeResource 标记扩展，提供更类型安全的方式：

<Window xmlns:ui="http://CustomWPFUI.co/2022/xaml">
    <StackPanel>
        
        <TextBlock 
            Text="次要文本"
            Foreground="{ui:ThemeResource TextFillColorSecondaryBrush}" />
        
        <Button 
            Content="强调色按钮"
            Background="{ui:ThemeResource SystemAccentColorPrimaryBrush}" />
    </StackPanel>
</Window>

2.3 常用控件示例

Button 按钮

<StackPanel>
    
    <ui:Button 
        Content="标准按钮"
        Appearance="Primary"
        Foreground="{DynamicResource TextOnAccentFillColorPrimaryBrush}"
        Background="{DynamicResource SystemAccentColorPrimaryBrush}" />
    
    
    <ui:Button 
        Content="次要按钮"
        Appearance="Secondary"
        Foreground="{DynamicResource TextFillColorPrimaryBrush}"
        Background="{DynamicResource ControlFillColorSecondaryBrush}" />
    
    
    <ui:Button 
        Content="透明按钮"
        Appearance="Transparent"
        Foreground="{DynamicResource TextFillColorSecondaryBrush}"
        Background="{DynamicResource ControlFillColorTransparentBrush}" />
</StackPanel>

TextBlock 文本

<StackPanel>
    
    <ui:TextBlock 
        Text="页面标题"
        FontTypography="Title"
        Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
    
    
    <ui:TextBlock 
        Text="这是正文内容"
        FontTypography="Body"
        Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
    
    
    <ui:TextBlock 
        Text="禁用状态"
        FontTypography="Caption"
        Foreground="{DynamicResource TextFillColorDisabledBrush}" />
</StackPanel>

ListView 列表

<ui:ListView 
    Background="{DynamicResource ControlFillColorDefaultBrush}"
    BorderBrush="{DynamicResource ControlStrokeColorDefaultBrush}">
    <ListView.ItemContainerStyle>
        <Style TargetType="ListViewItem">
            <Setter Property="Background" Value="{DynamicResource ControlFillColorTransparentBrush}" />
            <Setter Property="Foreground" Value="{DynamicResource TextFillColorPrimaryBrush}" />
            <Style.Triggers>
                <Trigger Property="IsSelected" Value="True">
                    <Setter Property="Background" Value="{DynamicResource SystemAccentColorPrimaryBrush}" />
                    <Setter Property="Foreground" Value="{DynamicResource TextOnAccentFillColorPrimaryBrush}" />
                </Trigger>
                <Trigger Property="IsMouseOver" Value="True">
                    <Setter Property="Background" Value="{DynamicResource ControlFillColorSecondaryBrush}" />
                </Trigger>
            </Style.Triggers>
        </Style>
    </ListView.ItemContainerStyle>
</ui:ListView>

TextBox 输入框

<ui:TextBox 
    PlaceholderText="请输入内容..."
    Background="{DynamicResource ControlFillColorDefaultBrush}"
    Foreground="{DynamicResource TextFillColorPrimaryBrush}"
    BorderBrush="{DynamicResource ControlStrokeColorDefaultBrush}"
    CaretBrush="{DynamicResource TextFillColorPrimaryBrush}" />

Card 卡片

<ui:Card 
    Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
    BorderBrush="{DynamicResource CardStrokeColorDefault}"
    Padding="16">
    <StackPanel>
        <TextBlock 
            Text="卡片标题"
            Foreground="{DynamicResource TextFillColorPrimaryBrush}"
            FontWeight="Bold" />
        <TextBlock 
            Text="卡片内容描述"
            Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
    </StackPanel>
</ui:Card>

2.4 在代码中使用颜色

// 获取当前主题的画刷
var foregroundBrush = Application.Current.Resources["TextFillColorPrimaryBrush"] as SolidColorBrush;
var backgroundBrush = Application.Current.Resources["ControlFillColorDefaultBrush"] as SolidColorBrush;

// 监听主题变化
ApplicationThemeManager.Changed += (theme, accent) =>
{
    // 主题变化时的处理逻辑
    Debug.WriteLine($"主题已切换为: {theme}");
};

---

3. 自定义控件适配WPF UI主题

3.1 基础适配原则

自定义控件要适配WPF UI主题，需要遵循以下原则：

1. 使用 DynamicResource 而不是 StaticResource
2. 使用主题提供的颜色资源 而不是硬编码颜色
3. 考虑不同状态（正常、悬停、按下、禁用）

3.2 自定义控件示例

示例1：自定义卡片控件

<UserControl x:Class="MyApp.Controls.CustomCard"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Border x:Name="CardBorder"
            Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
            BorderBrush="{DynamicResource CardStrokeColorDefault}"
            BorderThickness="1"
            CornerRadius="8"
            Padding="16">
        <ContentPresenter Content="{Binding Content, RelativeSource={RelativeSource AncestorType=UserControl}}" />
    </Border>
</UserControl>

// CustomCard.xaml.cs
public partial class CustomCard : UserControl
{
    public CustomCard()
    {
        InitializeComponent();
        
        // 监听鼠标事件以改变状态
        MouseEnter += (s, e) => {
            CardBorder.Background = Application.Current.Resources["ControlFillColorSecondaryBrush"] as Brush;
        };
        
        MouseLeave += (s, e) => {
            CardBorder.Background = Application.Current.Resources["CardBackgroundFillColorDefaultBrush"] as Brush;
        };
    }
}

示例2：带主题的自定义按钮

<Button x:Class="MyApp.Controls.CustomButton"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Button.Style>
        <Style TargetType="Button">
            
            <Setter Property="Background" Value="{DynamicResource ControlFillColorDefaultBrush}" />
            <Setter Property="Foreground" Value="{DynamicResource TextFillColorPrimaryBrush}" />
            <Setter Property="BorderBrush" Value="{DynamicResource ControlStrokeColorDefaultBrush}" />
            <Setter Property="Padding" Value="12,6" />
            <Setter Property="BorderThickness" Value="1" />
            <Setter Property="Template">
                <Setter.Value>
                    <ControlTemplate TargetType="Button">
                        <Border x:Name="Border"
                                Background="{TemplateBinding Background}"
                                BorderBrush="{TemplateBinding BorderBrush}"
                                BorderThickness="{TemplateBinding BorderThickness}"
                                CornerRadius="4">
                            <ContentPresenter HorizontalAlignment="Center" 
                                            VerticalAlignment="Center" />
                        </Border>
                        <ControlTemplate.Triggers>
                            
                            <Trigger Property="IsMouseOver" Value="True">
                                <Setter TargetName="Border" 
                                        Property="Background" 
                                        Value="{DynamicResource ControlFillColorSecondaryBrush}" />
                                <Setter TargetName="Border" 
                                        Property="BorderBrush" 
                                        Value="{DynamicResource ControlStrokeColorSecondaryBrush}" />
                            </Trigger>
                            
                            
                            <Trigger Property="IsPressed" Value="True">
                                <Setter TargetName="Border" 
                                        Property="Background" 
                                        Value="{DynamicResource ControlFillColorTertiaryBrush}" />
                            </Trigger>
                            
                            
                            <Trigger Property="IsEnabled" Value="False">
                                <Setter TargetName="Border" 
                                        Property="Background" 
                                        Value="{DynamicResource ControlFillColorDisabledBrush}" />
                                <Setter Property="Foreground" 
                                        Value="{DynamicResource TextFillColorDisabledBrush}" />
                            </Trigger>
                        </ControlTemplate.Triggers>
                    </ControlTemplate>
                </Setter.Value>
            </Setter>
        </Style>
    </Button.Style>
</Button>

示例3：自定义列表项

<UserControl x:Class="MyApp.Controls.CustomListItem"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Grid x:Name="RootGrid"
          Background="{DynamicResource ControlFillColorTransparentBrush}"
          Height="48">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="Auto" />
            <ColumnDefinition Width="*" />
        </Grid.ColumnDefinitions>
        
        
        <Path x:Name="IconPath"
              Grid.Column="0"
              Width="16" 
              Height="16"
              Margin="12,0"
              Fill="{DynamicResource TextFillColorSecondaryBrush}"
              Data="..." />
        
        
        <TextBlock x:Name="TitleText"
                   Grid.Column="1"
                   VerticalAlignment="Center"
                   Foreground="{DynamicResource TextFillColorPrimaryBrush}"
                   FontSize="14" />
    </Grid>
</UserControl>

// CustomListItem.xaml.cs
public partial class CustomListItem : UserControl
{
    public CustomListItem()
    {
        InitializeComponent();
        
        // 状态管理
        RootGrid.MouseEnter += (s, e) => {
            RootGrid.Background = Application.Current.Resources["ControlFillColorSecondaryBrush"] as Brush;
            IconPath.Fill = Application.Current.Resources["TextFillColorPrimaryBrush"] as Brush;
        };
        
        RootGrid.MouseLeave += (s, e) => {
            RootGrid.Background = Application.Current.Resources["ControlFillColorTransparentBrush"] as Brush;
            IconPath.Fill = Application.Current.Resources["TextFillColorSecondaryBrush"] as Brush;
        };
    }
}

3.3 主题感知控件的最佳实践

1. 始终使用 DynamicResource

   
   <Border Background="{DynamicResource ControlFillColorDefaultBrush}" />
   
   
   <Border Background="{StaticResource ControlFillColorDefaultBrush}" />
   

2. 为所有状态定义样式

   • Normal（正常）
   • MouseOver（悬停）
   • Pressed（按下）
   • Disabled（禁用）
   • Selected（选中）

3. 使用语义化的颜色资源

   
   <TextBlock Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
   
   
   <TextBlock Foreground="{DynamicResource BlackBrush}" />
   

4. 考虑对比度

   
   <Border Background="{DynamicResource SystemAccentColorPrimaryBrush}">
       <TextBlock Foreground="{DynamicResource TextOnAccentFillColorPrimaryBrush}" />
   </Border>
   

---

4. 主题切换实现

4.1 使用 ApplicationThemeManager

WPF UI 提供了 ApplicationThemeManager 类来管理应用主题：

// 应用主题
ApplicationThemeManager.Apply(ApplicationTheme.Dark);

// 应用主题并指定背景效果
ApplicationThemeManager.Apply(
    ApplicationTheme.SlateDark, 
    WindowBackdropType.Mica,  // 背景效果
    updateAccent: true        // 是否更新强调色
);

4.2 可用的主题

public enum ApplicationTheme
{
    Unknown,              // 未知主题
    Dark,                 // 深色主题
    Light,                // 浅色主题
    SlateDark,            // 石板深色主题
    LightBlue,            // 浅蓝色主题
    LightPurple,          // 浅紫色主题
    HighContrastHC1,      // 高对比度主题1
    HighContrastHC2,      // 高对比度主题2
    HighContrastHCBlack,  // 高对比度黑色主题
    HighContrastHCWhite   // 高对比度白色主题
}

4.3 完整示例：设置页面实现

参考 SettingsPage.xaml 和 SettingsViewModel.cs 的实现：

ViewModel 实现

// SettingsViewModel.cs
public sealed partial class SettingsViewModel : ViewModel
{
    private bool _isInitialized = false;

    [ObservableProperty]
    private ApplicationTheme _currentApplicationTheme = ApplicationTheme.SlateDark;

    [ObservableProperty]
    private List<ApplicationTheme> _availableThemes = ApplicationThemeManager.GetAvailableThemes();

    // 主题变更处理
    partial void OnCurrentApplicationThemeChanged(ApplicationTheme oldValue, ApplicationTheme newValue)
    {
        ApplicationThemeManager.Apply(newValue);
    }

    public override void OnNavigatedTo()
    {
        if (!_isInitialized)
        {
            InitializeViewModel();
        }
    }

    private void InitializeViewModel()
    {
        // 获取当前主题
        CurrentApplicationTheme = ApplicationThemeManager.GetAppTheme() is ApplicationTheme.Unknown
            ? ApplicationTheme.SlateDark
            : ApplicationThemeManager.GetAppTheme();

        // 订阅主题变更事件
        ApplicationThemeManager.Changed += OnThemeChanged;

        _isInitialized = true;
    }

    private void OnThemeChanged(ApplicationTheme currentApplicationTheme, Color systemAccent)
    {
        // 如果主题在其他地方被更改，更新UI
        if (CurrentApplicationTheme != currentApplicationTheme)
        {
            CurrentApplicationTheme = currentApplicationTheme;
        }
    }
}

XAML 实现

<Page xmlns:ui="http://CustomWPFUI.co/2022/xaml"
      xmlns:helpers="clr-namespace:MyApp.Helpers">
    
    <Page.Resources>
        
        <helpers:EnumToDisplayConverter x:Key="EnumToDisplayConverter" />
    </Page.Resources>
    
    <StackPanel Margin="24">
        <ui:TextBlock 
            Text="外观设置"
            FontTypography="Title" />
        
        
        <ui:CardControl Margin="0,12,0,0">
            <ui:CardControl.Header>
                <StackPanel>
                    <TextBlock Text="应用主题" />
                    <TextBlock 
                        Text="选择应用的颜色主题"
                        Foreground="{ui:ThemeResource TextFillColorSecondaryBrush}" />
                </StackPanel>
            </ui:CardControl.Header>
            
            <ComboBox 
                MinWidth="200"
                ItemsSource="{Binding ViewModel.AvailableThemes}"
                SelectedItem="{Binding ViewModel.CurrentApplicationTheme, Mode=TwoWay}">
                <ComboBox.ItemTemplate>
                    <DataTemplate>
                        <TextBlock Text="{Binding Converter={StaticResource EnumToDisplayConverter}}" />
                    </DataTemplate>
                </ComboBox.ItemTemplate>
            </ComboBox>
        </ui:CardControl>
    </StackPanel>
</Page>

4.4 枚举显示转换器

// EnumToDisplayConverter.cs
public class EnumToDisplayConverter : IValueConverter
{
    public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
    {
        if (value is ApplicationTheme theme)
        {
            return ApplicationThemeManager.GetThemeDisplayName(theme);
        }
        return value?.ToString() ?? string.Empty;
    }

    public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
    {
        throw new NotImplementedException();
    }
}

4.5 主题变更事件

// 订阅主题变更事件
ApplicationThemeManager.Changed += OnThemeChanged;

// 事件处理
private void OnThemeChanged(ApplicationTheme theme, Color accent)
{
    Debug.WriteLine($"主题已更改为: {theme}");
    Debug.WriteLine($"系统强调色: {accent}");
    
    // 执行自定义逻辑
    UpdateCustomControls();
}

// 取消订阅（在页面卸载时）
ApplicationThemeManager.Changed -= OnThemeChanged;

4.6 在 App.xaml 中配置主题

<Application xmlns:ui="http://CustomWPFUI.co/2022/xaml">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                
                <ui:ThemesDictionary Theme="SlateDark" />
                
                
                <ResourceDictionary Source="pack://application:,,,/YourApp;component/Styles/CustomStyles.xaml" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

4.7 代码中初始化主题

// App.xaml.cs
public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);
        
        // 应用初始主题
        ApplicationThemeManager.Apply(
            ApplicationTheme.SlateDark,
            WindowBackdropType.Mica,
            updateAccent: true
        );
        
        // 设置固定强调色（可选）
        var fixedAccentColor = Color.FromRgb(0, 120, 215);
        ApplicationAccentColorManager.Apply(fixedAccentColor, ApplicationTheme.SlateDark);
    }
}

---

5. 最佳实践

5.1 颜色使用建议

场景	推荐资源
主要文本	TextFillColorPrimaryBrush
次要文本/描述	TextFillColorSecondaryBrush
占位符/提示	TextFillColorTertiaryBrush
禁用文本	TextFillColorDisabledBrush
按钮背景	ControlFillColorDefaultBrush
悬停背景	ControlFillColorSecondaryBrush
卡片背景	CardBackgroundFillColorDefaultBrush
强调色	SystemAccentColorPrimaryBrush
成功状态	SystemFillColorSuccessBrush
警告状态	SystemFillColorCautionBrush
错误状态	SystemFillColorCriticalBrush

5.2 性能优化

1. 缓存频繁使用的资源

   private static readonly Brush PrimaryTextBrush = 
       Application.Current.Resources["TextFillColorPrimaryBrush"] as Brush;
   

2. 避免在代码中频繁读取资源

   // 不推荐 - 每次调用都读取资源
   void UpdateUI()
   {
       TextBlock.Foreground = Application.Current.Resources["TextFillColorPrimaryBrush"] as Brush;
   }
   
   // 推荐 - 使用绑定
   <TextBlock Foreground="{DynamicResource TextFillColorPrimaryBrush}" />
   

5.3 可访问性

1. 确保足够的对比度

   • 文本与背景的对比度至少为 4.5:1
   • 使用 WPF UI 提供的颜色资源可以保证对比度

2. 支持高对比度主题

   // 检测高对比度模式
   if (theme == ApplicationTheme.HighContrastHC1 ||
       theme == ApplicationTheme.HighContrastHC2 ||
       theme == ApplicationTheme.HighContrastHCBlack ||
       theme == ApplicationTheme.HighContrastHCWhite)
   {
       // 应用高对比度特定样式
   }
   

5.4 调试技巧

1. 查看当前主题

   var currentTheme = ApplicationThemeManager.GetAppTheme();
   Debug.WriteLine($"当前主题: {currentTheme}");
   

2. 列出所有可用主题

   var themes = ApplicationThemeManager.GetAvailableThemes();
   foreach (var theme in themes)
   {
       Debug.WriteLine($"主题: {theme} - {ApplicationThemeManager.GetThemeDisplayName(theme)}");
   }