WPFTemplateLib — WPF 帮助类库

简介

是由 独立观察员（DLGCY） 收集、整合、开发和维护的帮助类库，旨在简化 WPF 桌面应用开发，提供MVVM 基础设施、丰富的自定义控件、大量开箱即用的转换器、可绑定的附加属性与行为、样式主题系统、配置管理等全套解决方案。

作者：独立观察员（DLGCY）
当前版本：7.3.1.0
目标框架：.NET Framework 4.7.2 / .NET 6.0（net6.0-windows）
NuGet 包：WPFTemplateLib
Gitee 仓库：https://gitee.com/dlgcy/WPFTemplateLib
博客：https://dlgcy.com/
微信公众号：独立观察员DLGCY博客
ReadMe：创建 - AI（Marvis），校对 - 独立观察员

快速开始

安装

Install-Package WPFTemplateLib

版本兼容性

目标框架	说明
`net472`	.NET Framework 4.7.2
`net6.0-windows`	.NET 6.0（Windows）

XAML 命名空间引入

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"

依赖包

项目依赖 13 个 NuGet 包，包括 CalcBinding（表达式绑定）、MahApps.Metro（Metro 风格控件）、Microsoft.Xaml.Behaviors.Wpf（行为支持）、Extended.Wpf.Toolkit（扩展控件）、Newtonsoft.Json（JSON 序列化）、SharpVectors.Wpf（SVG 支持）等。

资源字典引入

在 App.xaml 中引入核心资源字典：

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>

功能模块详解

1. MVVM 基础支持

库提供完整的 MVVM 基类体系，继承层次如下：

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase

1.1 ObservableObject（命名空间：`WPFTemplateLib.Mvvm`）

实现 INotifyPropertyChanged 和 INotifyPropertyChanging，是所有 MVVM 类的根基类。

成员	说明
`OnPropertyChanged([CallerMemberName] string propertyName = null)`	触发属性变更通知
`OnPropertyChanging([CallerMemberName] string propertyName = null)`	触发属性将要变更通知
`SetProperty<T>(ref T storage, T value, [CallerMemberName] string propertyName = null)`	值不同时设置并通知
`SetPropertyWithoutCompare<T>(ref T storage, T value, [CallerMemberName] string propertyName = null)`	不比较直接设置并通知
`PropertyChangedHandle(string propertyName)`	虚方法，子类重写响应属性变化
`PropertySetIntentionHandle<T>(ref T prevValue, ref T newValue, string propertyName)`	虚方法，无论值是否变化都会调用

public class MyModel : ObservableObject{    private string _name;    public string Name    {        get => _name;        set => SetProperty(ref _name, value);    }}

1.2 SimpleBindableBase

使用 PropertyChanged.Fody 包（[AddINotifyPropertyChangedInterface] 特性）自动编织属性变更通知代码。普通公共自动属性无需手动调用 SetProperty。

注意：使用的项目中仍需安装 PropertyChanged.Fody 包。

public class MyBindable : SimpleBindableBase{    public string Name { get; set; }   // 自动支持属性变更通知    public int Age { get; set; }        // 自动支持属性变更通知}

1.3 NotifyDataErrorObject

实现 INotifyDataErrorInfo，提供数据验证错误通知功能。

成员	说明
`HasErrors`	是否存在任何错误（只读）
`GetErrors(string propertyName)`	获取指定属性的错误列表（参数为空获取所有）
`IsContainErrors(string propertyName)`	判断指定属性是否包含错误
`IsContainErrors(List<string> propertyNameList)`	判断指定属性列表中是否有任意属性包含错误
`ValidateBlank(object value, string errMsg, [CallerMemberName] string propertyName)`	验证是否为空，返回 `true` 表示不为空
`ErrorsChanged`	错误变更事件

public class MyValidatable : NotifyDataErrorObject{    private string _name;    public string Name    {        get => _name;        set        {            SetProperty(ref _name, value);            ValidateBlank(value, "名称不能为空");  // 触发验证        }    }}

<!-- 界面绑定错误提示 --><TextBox Text="{Binding Name, ValidatesOnNotifyDataErrors=True}" />

1.4 ViewModelBase

ViewModel 基类，继承自 NotifyDataErrorObject，提供程序运行消息输出、Toast 气泡弹窗、窗口载入处理等内置功能。

消息输出：

成员	说明
`Info` (string)	信息区绑定内容
`ShowInfo(string info, bool isAddBlankLine = false)`	追加普通信息（带时间戳）
`ShowInfoUc(string info, bool isAddBlankLine = false)`	使用 `UC_InfoRegion` 时的信息输出（Dispatcher 线程安全）
`IsSetConsoleOutput` (bool)	是否将 Console 输出重定向到信息区

Toast 气泡弹窗命令：

成员	说明
`ToastToWindowCmd` (`RelayCommand<List<object>>`)	窗口中间弹窗命令
`ToastToScreenCmd` (`RelayCommand<string>`)	屏幕中间弹窗命令
`ToastToScreen(msg, icon, ms, color)`	屏幕中间弹窗方法
`ToastToScreenWarning(msg, ms)`	屏幕中间警告弹窗（橙色图标）
`ToastToScreenError(msg, ms)`	屏幕中间错误弹窗（红色图标）
`ToastToWindow(msg, win, icon, ms, color)`	窗口中间弹窗方法

窗口载入：

成员	说明
`LoadedCmd` (`ICommand`)	绑定到窗口 `Loaded` 事件
`OnLoaded(bool isFirst)`	虚方法，子类重写处理载入（参数标识是否首次）

public class MainViewModel : ViewModelBase{    protected override void OnLoaded(bool isFirst)    {        if (isFirst)        {            ToastToScreen("系统初始化完成", ToastIcons.Information, 3000);        }    }}

<!-- 绑定 Loaded 事件 --><b:Interaction.Triggers>    <b:EventTrigger EventName="Loaded">        <b:InvokeCommandAction Command="{Binding LoadedCmd}" />    </b:EventTrigger></b:Interaction.Triggers>

1.5 RelayCommand（命名空间：`WPFTemplateLib.WpfHelpers`）

支持同步和异步执行、CanExecute 条件判断、异步防重入（_isExecutingAsync 标志在异步执行期间禁用按钮防止重复点击）、手动触发 CanExecute 重新计算。

构造函数（非泛型版 RelayCommand）：

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"0

构造函数（泛型版 RelayCommand<T>）：

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"1

公共方法：

方法	说明
`RaiseCanExecuteChanged()`	手动触发 CanExecute 重新计算
`CanExecute(object parameter)`	判断命令是否可执行
`Execute(object parameter)`	执行命令

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"2

2. 样式（Style）

2.1 命名规范

前缀	说明
`LibSty`	库自定义样式
`SysSty`	系统内置简单样式
`LibTpl`	库自定义控件模板
`SysTpl`	系统内置控件模板

2.2 关键默认样式 Key

样式 Key	目标类型	基础样式
`LibSty.Button.Default`	Button	`LibSty.WpfUi.Button.Ele.Primary`
`LibSty.CheckBox.Default`	CheckBox	`LibSty.WpfUi.CheckBox.Basic`
`LibSty.ComboBox.Default`	ComboBox	`LibSty.WpfUi.ComboBox.Primary`
`LibSty.Expander.Default`	Expander	`MahApps.Styles.Expander`
`LibSty.GroupBox.Default`	GroupBox	`MahApps.Styles.GroupBox.Fix`
`LibSty.RadioButton.Default`	RadioButton	`LibSty.WpfUi.RadioButton.Basic`
`LibSty.ScrollBar.Default`	ScrollBar	`LibSty.ScrollBar`
`LibSty.ScrollViewer.Default`	ScrollViewer	`LibSty.ScrollViewer`
`LibSty.ToggleButton.Default`	ToggleButton	`MahApps.Styles.ToggleButton.Flat`
`LibSty.TreeView.Default`	TreeView	`MahApps.Styles.TreeView`
`LibSty.TreeViewItem.Default`	TreeViewItem	`MahApps.Styles.TreeViewItem.Fix`
`LibSty.TextBlock.Default`	TextBlock	`SysSty.TextBlock`

2.3 StyleDictionary.xaml 合并的子字典（22 个）

StyleDictionary.xaml 合并了以下子字典文件：

DictionaryCommon、DictionaryBorder、DictionaryButton、DictionaryCalendar、DictionaryCheckBox、DictionaryComboBox、DictionaryContentControl、DictionaryDataGrid、DictionaryLabel、DictionaryListBox、DictionaryListView、DictionaryPath、DictionaryProgressBar、DictionaryRadioButton、DictionaryScroll、DictionarySeparator、DictionaryTabControl、DictionaryTextBlock、DictionaryTextBox、DictionaryToggleButton、DictionaryUserControls、DictionaryCustomControl、DictionaryMahApps

3. 主题（Theme）

库的 Generic.xaml 提供了完整的默认控件样式，同时支持颜色主题切换。颜色主题文件位于 Themes/ 目录：

主题文件	说明
`Light.xaml`	浅色主题（默认）
`Light.Blue.xaml`	浅色蓝色主题
`Light.Green.xaml`	浅色绿色主题
`FruitVent/`	FruitVent 设计风格主题目录

主题切换通过 DefaultThemeDictionary.xaml 控制，将 13 种控件类型设置到对应的默认样式。在 App.xaml 中引入 DefaultThemeDictionary.xaml 即可应用主题：

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"3

4. 转换器（Converter）

库提供了 70+ 个开箱即用的转换器，定义在 ConverterDictionary.xaml 中。在 App.xaml 中引入即可全局使用：

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"4

4.1 布尔/可见性类

Key	说明
`VisibleConverter`	bool 为 true 显示
`CollapsedConverter`	bool 为 true 隐藏
`BoolToVisibilityConverter`	布尔值转 Visibility
`TrueToVisibleConverter`	true → Visible
`TrueToCollapsedConverter`	true → Collapsed
`TrueToHiddenConverter`	true → Hidden
`VisibleCollapsedSwitchConverter`	Visible ↔ Collapsed 切换
`BoolReverseConverter`	反转布尔值
`BoolToNullableBoolConverter`	bool 转 bool?（支持回转）

4.2 条件判断类

Key	说明
`ObjectConverter`	单值通用转换器（参数规则：`比较值1\|比较值2:true返回值:false返回值`）
`MultiObjectConverter`	多值通用转换器
`IsEqualToParaConverter`	Equals 方法比较
`IsToStringEqualToParaConverter`	ToString 字符串相等比较
`StringContainsConverter`	字符串包含判断
`ObjectIsNullConverter`	判断对象是否为 null
`ObjectIsNotNullConverter`	判断对象是否不为 null
`IsNullOrWhitespaceConverter`	字符串为空判断
`IsNotNullOrWhitespaceConverter`	字符串非空判断
`IsNullOrEmptyObjectConverter`	对象为空判断

4.3 可见性联动类

Key	说明
`ValueToVisibleConverter`	值匹配参数时显示
`ValueToCollapsedConverter`	值匹配参数时隐藏
`StringNotEmptyToVisibleConverter`	字符串非空显示
`ObjectNotNullToVisibleConverter`	对象不为 null 显示
`CollectionNotEmptyToVisibleConverter`	集合不为空显示

4.4 数值运算类

Key	说明
`DivideConverter`	等分转换器
`ReduceDoubleConverter`	减少转换器（值 - 参数）
`AddDoubleConverter`	增加转换器（值 + 参数）
`MultiplyDoubleConverter`	相乘转换器（值 × 参数）
`DivideDoubleConverter`	相除转换器（值 ÷ 参数）
`ParaDivideValueDoubleConverter`	参数作被除数的相除
`ModuloDoubleConverter`	取模转换器
`ValueToAbsConverter`	取绝对值
`DoubleToGridLengthConverter`	double 转 GridLength

4.5 数值比较类

Key	CompareAction	说明
`GreaterThanParaNumberConverter`	`GreaterThan`	大于参数
`GreaterThanOrEqualParaNumberConverter`	`GreaterThanOrEqual`	大于等于参数
`EqualParaNumberConverter`	`Equal`	等于参数
`LessThanOrEqualParaNumberConverter`	`LessThanOrEqual`	小于等于参数
`LessThanParaNumberConverter`	`LessThan`	小于参数

4.6 列表/集合类

Key	说明
`GetCollectionLengthConverter`	获取集合长度
`ListContainsElementMultiConverter`	判断列表是否包含元素（多值）
`MultiToListObjectConverter`	多重绑定转为 `List<object>`

4.7 多值逻辑判断类

Key	说明
`IsAllTrueConverter`	是否全为真
`IsAllFalseConverter`	是否全为假
`IsContainsTrueConverter`	是否包含真
`IsAllStrEqualMultiConverter`	字符串形式是否全部相等
`IsHeadOfListMultiConverter`	是否在列表头部
`IsTailOfListMultiConverter`	是否在列表尾部

4.8 多值结果类

Key	JudgeType	说明
`JudgeListReturnParaValueMultiConverter`	AllTrue	判断并返回指定值
`AllTrueReturnParaValueMultiConverter`	AllTrue	全真返回指定值
`AllFalseReturnParaValueMultiConverter`	AllFalse	全假返回指定值
`ContainsTrueReturnParaValueMultiConverter`	ContainTrue	包含真返回指定值
`JoinStringsConverter`	—	连接字符串
`ReferenceValueToRealValueMultiConverter`	—	参考值转实际值

4.9 数字范围判断类

Key	说明
`IsNumberInRangeMultiConverter`	判断数字是否在指定范围内（多值绑定版）
`IsHeadOfListConverter` / `IsTailOfListConverter`	判断是否在列表头/尾

4.10 图片/资源类

Key	说明
`ObjectToImageSourceConverter`	object 转图片资源
`AllTypeToImageSourceConverter`	多类型转图片资源（string/Stream/Uri/byte[]）
`BitmapToImageSourceConverter`	Bitmap 转 ImageSource
`StringToImageSourceConverter`	字符串（文件名）转图片（参数为格式化字符串）
`StringToUriConverter`	字符串转 Uri

4.11 颜色/画刷类

Key	说明
`StringColorToBrushConverter`	字符串颜色转 SolidColorBrush
`MediaColorToBrushConverter`	Media.Color → SolidColorBrush
`BrushToMediaColorConverter`	SolidColorBrush → Media.Color

4.12 字符串处理类

Key	说明
`ToStringConverter`	转字符串
`StringFormatConverter`	字符串格式化（支持 `IsEmptyNotApplyFormat`）
`TrueFalseConverter`	"True"/"False" 字符串 → bool
`EmptyToParaConverter`	空值显示为参数指定值
`ObjectToJsonConverter`	对象转 JSON（支持 `IsIndented` 格式化）
`ParaToUpperOrLowerByValueConverter`	参数大小写转换
`ParaToUpperWhileValueIsTrueConverter`	value 为 true 时参数转大写
`ParaToLowerWhileValueIsTrueConverter`	value 为 true 时参数转小写

4.13 枚举/键值映射类

Key	说明
`GetEnumDescriptionConverter`	获取枚举 Description
`ShowEnumInfoConverter`	显示枚举信息
`EnumToStrInParaConverter`	枚举转参数字符串
`BindAsKeyFindValueInParaConverter`	绑定值作 Key 在参数中找 Value
`BindAsKeyFindValueInPropertyConverter`	绑定值作 Key 在属性中找 Value

4.14 Grid 布局类

Key	说明
`BoolToGridLengthConverter`	bool 转 GridLength
`BoolInvertedToGridLengthConverter`	反相 bool 转 GridLength
`BoolToGridLengthConverterV2`	bool 转 GridLength（属性版，`TrueValue`/`FalseValue`）

4.15 其他

Key	说明
`ObjectToIntConverter`	object 转 int（失败返回 0）
`DataGridRowToNoConverter`	DataGridRow 转行号
`PercentValueToCircleValueConverter`	百分比值转圆周值（0-100 → 0-360）
`FloatToScienceConverter`	浮点数转科学计数法
`InputScopeNameValueConverter`	InputScopeNameValue → InputScope
`StringToCornerRadiusConverter`	字符串转 CornerRadius
`StringToPathGeometry`	XAML 字符串转 Geometry
`GetFileNameConverter`	获取文件名
`GetFileNameWithoutExtensionConverter`	获取文件名（无扩展名）
`TimeSpanToHourMinuteSecondConverter`	TimeSpan → HH:mm:ss
`TimeSpanToMinuteSecondConverter`	TimeSpan → mm:ss
`NullableToActualConverter`	可空类型 → 实际类型值
`ObjectToNullableConverter`	对象 → 可空值类型

4.16 典型使用示例

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"5

5. 附加属性（Attached Properties）

库提供 15 个附加属性帮助类，位于 Attached/ 目录：

5.1 ButtonAttached（针对 Button）

附加属性	类型	默认值	说明
`KeyboardWindowType`	`Type`	`typeof(NumberKeyboard)`	自定义键盘窗口类型
`IsUseCustomKeyboard`	`bool`	`false`	是否使用自定义键盘输入（点击弹出数字键盘）

5.2 LabelAttached（针对 Label）

附加属性	类型	默认值	说明
`KeyboardWindowType`	`Type`	`typeof(NumberKeyboard)`	自定义键盘窗口类型
`IsUseCustomKeyboard`	`bool`	`false`	是否使用自定义键盘输入

5.3 RadioButtonAttached（550+ 行，最丰富的附加属性类）

行为类：

附加属性	类型	默认值	说明
`IsCanUncheck`	`bool`	`false`	是否允许取消选中（再次点击取消勾选）
`RadioValue`	`object`	—	选中时的值
`RadioBinding`	`object`	—	选中值绑定（`BindsTwoWayByDefault`）

RadioBinding 使用方式：将多个 RadioButton 绑定到同一 ViewModel 属性，每个 RadioButton 设置不同的 RadioValue，替代传统 GroupName 方式。

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"6

样式类（20+ 个附加属性，用于自定义 RadioButton 外观）：

附加属性	类型	默认值	说明
`CornerRadius`	`CornerRadius`	`0`	边框圆角
`FixPartMargin`	`Thickness`	`(5,0,0,0)`	固定部分（圆圈）边距
`FixPartHorizontalAlignment`	`HorizontalAlignment`	`Center`	固定部分水平对齐
`FixPartVerticalAlignment`	`VerticalAlignment`	`Center`	固定部分垂直对齐
`ContentPartMargin`	`Thickness`	`(5,0,5,0)`	内容部分边距
`ContentPartHorizontalAlignment`	`HorizontalAlignment`	`Center`	内容部分水平对齐
`ContentPartVerticalAlignment`	`VerticalAlignment`	`Center`	内容部分垂直对齐
`OuterCircleDiameter`	`double`	`20`	外部圆圈直径
`InnerCircleDiameter`	`double`	`14`	内部圆圈直径
`OuterCircleBorderBrush`	`Brush`	`DimGray`	外部圆圈边框颜色
`OuterCircleCheckedBorderBrush`	`Brush`	`DodgerBlue`	勾选时外部圆圈边框颜色
`OuterCircleBorderThickness`	`Thickness`	`1`	外部圆圈边框粗细
`OuterCircleFillBrush`	`Brush`	`Transparent`	外部圆圈填充颜色
`InnerCircleFillBrush`	`Brush`	`DodgerBlue`	内部圆圈填充颜色
`CheckedForeground`	`Brush`	`DodgerBlue`	选中时前景色
`CheckedBackground`	`Brush`	`White`	选中时背景色
`CheckedBorderBrush`	`Brush`	—	选中时边框画刷
`CheckedBorderThickness`	`Thickness`	`1`	选中时边框粗细
`MouseOverForeground`	`Brush`	`DodgerBlue`	鼠标悬停前景色
`MouseOverBackground`	`Brush`	`LightBlue`	鼠标悬停背景色
`MouseOverBorderBrush`	`Brush`	—	鼠标悬停边框画刷
`MouseOverBorderThickness`	`Thickness`	`1`	鼠标悬停边框粗细

5.4 ContextMenuAttached

附加属性	类型	默认值	说明
`IsLeftClickEnabled`	`bool`	`false`	是否允许左键触发右键菜单

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"7

5.5 其他附加属性类

类名	说明
`DataGridAttached`	DataGrid 附加属性
`ExportPicAttached`	导出图片附加功能
`FocusAttached`	焦点控制附加属性
`LocationTargetRenderOriginAttached`	元素定位附加属性（`TargetElement`、`IsAlignWithCenter`、`IsFlipOrigin`）
`RotateToTranslateAttached` / `RotateToTranslateAttachedV2`	旋转平移附加属性
`ScrollViewerAttached`	ScrollViewer 附加属性
`TabControlAttached`	TabControl 附加属性
`TextBoxAttached`	TextBox 附加属性
`WpfTouchAttached`	触摸支持附加属性

6. 行为（Behavior）

6.1 SelectedItemsBehavior（命名空间：`WPFTemplateLib.Behaviors`）

继承 Behavior<MultiSelector>，允许对 MultiSelector（如 ListBox、DataGrid）实现可绑定的多选功能。

依赖属性	类型	模式	说明
`BindableSelectedItems`	`IList`	OneWayToSource	绑定选中的项集合
`SelectedItemsChangedCommand`	`RelayCommand<IList>`	—	选中项变更时执行的命令

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"8

6.2 DragInCanvasBehavior

继承 Behavior<UIElement>，实现 Canvas 中拖拽移动功能。通过 MouseLeftButtonDown/Move/Up 事件更新 Canvas.Left 和 Canvas.Top。

6.3 SelectedItemBehavior

继承 Behavior<FrameworkElement>，让包含 RadioButton 的 Panel 或 ItemsControl 拥有可绑定的 SelectedItem 属性。RadioButton 的值存放在 Tag 中。

依赖属性	类型	说明
`SelectedItem`	`object`	当前选中的项（可通过 Binding 绑定到 ViewModel）

xmlns:lib="https://gitee.com/dlgcy/WPFTemplateLib"9

6.4 AttachAdornerBehavior

继承 Behavior<UIElement>，为 UI 元素附加装饰器（BindableContainerAdorner），可在元素上悬浮显示额外内容。

属性/依赖属性	类型	默认值	说明
`Element`	`FrameworkElement`	—	装饰内容界面元素
`IsShowAdorner`	`bool`	`true`	是否显示装饰器

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>0

6.5 ChangeAttachedPropertyAction

继承 TriggerAction<DependencyObject>，在事件触发时修改指定类的附加属性值。

属性	类型	说明
`ClassType`	`Type`	定义附加属性的类类型
`PropertyName`	`string`	附加属性名称
`Value`	`object`	设置的值

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>1

7. 自定义控件（Custom Controls）

7.1 PanelWithMessage

继承 ContentControl，提供主内容区和信息显示区的布局面板。常用于需要底部信息输出的窗口。

依赖属性	类型	默认值	说明
`ContentRegionLength`	`GridLength`	`3*`	主内容区域高度比例
`MessageRegionLength`	`GridLength`	`1*`	信息区域高度比例
`IsEnglish`	`bool`	`false`	是否为英文界面

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>2

7.2 CircleWithInOutText

继承 Control，内部文字 + 外部文字的圆形控件（带有 17 个依赖属性和 2 个附加属性）。

依赖属性	类型	默认值	说明
`CirclePlacement`	`Dock`	—	圆形放置位置
`CircleDiameter`	`double`	`32`	圆形直径
`CircleStroke`	`Brush`	—	圆形描边色
`CircleStrokeThickness`	`double`	—	圆形描边粗细
`InnerText`	`string`	—	内部文字
`OuterText`	`string`	—	外部文字
`InnerTextColor`	`Brush`	—	内部文字颜色
`OuterTextColor`	`Brush`	—	外部文字颜色
`TextColor`	`Brush`	—	统一文字颜色（通过 PropertyChangedCallback 联动 InnerTextColor/OuterTextColor）
`CircleInnerColor`	`Brush`	—	圆形内部颜色
`DistanceBetweenCircleAndText`	`double`	—	圆与文字间距
`InnerTextFontSize`	`double`	—	内部文字字号
`OuterTextFontSize`	`double`	—	外部文字字号
`TextFontSize`	`double`	—	统一文字字号
`InnerTextFontWeight`	`FontWeight`	—	内部文字粗细
`OuterTextFontWeight`	`FontWeight`	—	外部文字粗细
`TextFontWeight`	`FontWeight`	—	统一文字粗细
`InnerTextBlockStyle`	`Style`	—	内部 TextBlock 样式
`OuterTextBlockStyle`	`Style`	—	外部 TextBlock 样式

附加属性：OuterTextHorizontalAlignment、OuterTextVerticalAlignment

7.3 CheckBoxButton

继承 Button，特殊的多选框控件。主要目的是在指定 Command 后不主动改变 IsChecked，而是由 ViewModel 逻辑决定是否勾选。

路由事件	说明
`Checked`	勾选时触发
`Unchecked`	取消勾选时触发
`IsCheckedChanged`	IsChecked 变化时触发

主要依赖属性（19个）：

依赖属性	类型	默认值	说明
`IsChecked`	`bool?`	—	勾选状态（`BindsTwoWayByDefault`）
`ContentPosition`	`Dock`	`Right`	内容相对勾选框位置
`MarkGeometryData`	`string`	—	勾选标志路径数据
`MarkFillBrush`	`Brush`	—	勾选标志填充色
`MarkStrokeBrush`	`Brush`	—	勾选标志描边色
`MarkStrokeThickness`	`double`	—	勾选标志描边粗细
`MarkMargin`	`Thickness`	—	勾选标志外边距
`MarkRegionMargin`	`Thickness`	—	勾选框外边距
`MarkRegionWidth`	`double`	—	勾选框宽度
`MarkRegionHeight`	`double`	—	勾选框高度
`MarkRegionHorizontalAlignment`	`HorizontalAlignment`	—	勾选框水平对齐
`MarkRegionVerticalAlignment`	`VerticalAlignment`	—	勾选框垂直对齐
`MarkRegionBorderThickness`	`Thickness`	—	勾选框边框粗细
`MarkRegionBorderThicknessWhenChecked`	`Thickness`	—	勾选后边框粗细
`MarkRegionBorderCornerRadius`	`CornerRadius`	—	勾选框圆角
`MarkRegionBorderBrush`	`Brush`	—	勾选框边框色
`MarkRegionBorderBrushWhenChecked`	`Brush`	—	勾选后边框色
`MarkRegionBackgroundWhenChecked`	`Brush`	—	勾选后背景色
`ForegroundWhenChecked`	`Brush`	—	勾选后前景色
`IsLikeRadioButton`	`bool`	—	是否模仿 RadioButton 样式
`ContentRegionMargin`	`Thickness`	—	内容区域边距

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>3

7.4 AutoGrid

继承 Grid，自动排列子元素的网格控件（源于 WpfAutoGrid 项目）。

依赖属性	类型	默认值	说明
`ChildHorizontalAlignment`	`HorizontalAlignment?`	—	子元素水平对齐
`ChildMargin`	`Thickness?`	—	子元素边距
`ChildVerticalAlignment`	`VerticalAlignment?`	—	子元素垂直对齐
`ColumnCount`	`int`	—	列数
`Columns`	`string`	—	列定义（逗号分隔的 GridLength，如 `,2,Auto`）
`ColumnWidth`	`GridLength`	—	默认列宽
`IsAutoIndexing`	`bool`	—	是否自动索引
`Orientation`	`Orientation`	—	排列方向
`RowCount`	`int`	—	行数
`Rows`	`string`	—	行定义
`RowHeight`	`GridLength`	—	默认行高

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>4

7.5 TitleValueUnit

继承 Control，展示"标题-值-单位"的控件。

依赖属性	类型	默认值	说明
`Title`	`string`	—	标题文字
`Value`	`object`	—	值内容
`Unit`	`string`	—	单位文字
`SetValueCommand`	`ICommand`	—	设置值命令
`TitlePosition`	`Dock`	`Top`	标题位置
`TitleMargin`	`Thickness`	—	标题边距
`TitleWidth`	`double`	`NaN`	标题宽度
`TitleTextAlignment`	`TextAlignment`	`Left`	标题文字对齐
`ValueRegionMargin`	`Thickness`	—	值区域边距
`ContentStringFormat`	`string`	—	内容格式化字符串
`TitleFontSize`	`double`	—	标题字号
`ValueFontSize`	`double`	—	值字号
`UnitFontSize`	`double`	—	单位字号

附加属性：TitleForeground、ContentForeground、UnitForeground、TitleFontWeight、ContentFontWeight、UnitFontWeight

7.6 ManualComboBox

继承 ComboBox，下拉选择后只触发 SelectedItemChangedCommand 而不主动改变 SelectedItem。内部通过备份选中项、截获点击事件来恢复原选中项（通过 RestoreBindingValue 方法处理绑定恢复）。

7.7 TitleContentUnit

继承 ContentControl，简化的标题-内容-单位控件。

依赖属性	类型	说明
`Title`	`string`	标题
`Unit`	`string`	单位

7.8 CornerClip / CenterRectClip

CornerClip：圆角裁剪控件，将子内容裁剪为指定 CornerRadius
CenterRectClip：中央矩形裁剪，通过 HorizontalKeepPercent 控制保留比例

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>5

7.9 DateTimePicker

继承控件，日期时间选择器。支持中英文样式切换：

默认样式：中文日期选择器
LibSty.DateTimePicker.English：英文版样式

依赖属性	类型	说明
`SelectedDateTime`	`DateTime?`	选中的日期时间

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>6

7.10 FlipableControl / FlipableContentControl

可翻转面板控件，支持水平/垂直翻转动画。

属性	类型	说明
`IsFlip`	`bool`	是否翻转
`FlipType`	—	翻转类型（Horizontal / Vertical）

7.11 UniformSpacingPanel

自动均匀分布子元素的布局面板。

依赖属性	类型	说明
`Orientation`	`Orientation`	排列方向
`Spacing`	`double`	元素间距
`ChildWrapping`	—	子元素换行模式
`ItemWidth` / `ItemHeight`	`double`	子元素统一宽/高
`ItemVerticalAlignment`	`VerticalAlignment`	子元素垂直对齐

7.12 MetroHeader

继承 MahApps MetroHeader，带标题的分组容器。

7.13 Toast（气泡弹窗）

完整的自定义气泡弹窗实现（638 行代码，位于 Controls/WpfToast/）。

ToastOptions 类（17 个属性）：

属性	说明
`Icon`	图标类型（`ToastIcons` 枚举）
`Location`	显示位置（`ToastLocation` 枚举，17 个位置）
`Time`	显示持续时间（毫秒）
`TextWidth`	文字宽度
`ToastWidth` / `ToastMaxWidth`	弹窗宽度
`IconForeground`	图标前景色

ToastIcons 枚举：None、Information、Error、Warning、Busy

ToastLocation 枚举（17 个位置）：ScreenCenter、OwnerCenter、ScreenTopLeft、ScreenTopRight、ScreenBottomLeft、ScreenBottomRight、OwnerTopLeft 等。

静态使用方法：

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>7

ToastHelper 静态帮助类：

方法	说明
`ToastToScreen(msg, icon, ms)`	屏幕中间弹窗
`ToastToScreenWarning(msg, ms)`	屏幕中间警告弹窗
`ToastToScreenError(msg, ms)`	屏幕中间错误弹窗
`ToastToWindow(win, msg, ms)`	窗口中间弹窗
`ToastToWindowError(win, msg, ms)`	窗口中间错误弹窗

7.14 PasswordInput

密码输入控件（FruitVent 设计风格），支持明文切换和清除按钮。

依赖属性	类型	说明
`AllowClear`	`bool`	是否显示清除按钮
`IsShowOriginText`	`bool`	是否显示明文

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>8

7.15 Row / Col（HandyGrid）

HandyControl 风格的栅格布局控件，位于 Controls/Panels/HandyGrid/。

Row：栅格行容器
Col：栅格列，Span 属性控制占位宽度

7.16 SeparatorStackPanel / RenderedSeparatorStackPanel / AdornerSeparatorStackPanel

三种带分隔线的 StackPanel：

SeparatorStackPanel：通过 Separator 控件实现分隔
RenderedSeparatorStackPanel（推荐）：通过渲染方式绘制分隔线，SeparatorBrush/SeparatorInset/SeparatorThickness 属性控制外观
AdornerSeparatorStackPanel：通过 Adorner 层绘制分隔线

7.17 Form / FormItem（XUI）

位于 Controls/XUI/，加载时带动画效果的 ItemsControl 列表。

Form：继承 ItemsControl，Columns/Rows 属性控制网格布局
FormItem：带图标、标题、内容区的列表项，支持 Icon、Title、HeaderWidth 等属性

<Application.Resources>    <ResourceDictionary>        <ResourceDictionary.MergedDictionaries>            <!-- 转换器 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/WpfConverters/ConverterDictionary.xaml"/>            <!-- 样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Styles/StyleDictionary.xaml"/>            <!-- 默认主题样式 -->            <ResourceDictionary Source="pack://application:,,,/WPFTemplateLib;component/Themes/DefaultThemeDictionary.xaml"/>        </ResourceDictionary.MergedDictionaries>    </ResourceDictionary></Application.Resources>9

8. 标记扩展（Markup Extensions）

位于 MarkupExtensions/ValueMarkupExtensions.cs，提供 14 种基本数据类型的标记扩展。

标记扩展	类型	说明
`ByteValue`	`byte`	提供 byte 值
`ShortValue`	`short`	提供 short 值
`IntValue`	`int`	提供 int 值
`LongValue`	`long`	提供 long 值
`FloatValue`	`float`	提供 float 值
`DoubleValue`	`double`	提供 double 值
`DecimalValue`	`decimal`	提供 decimal 值
`CharValue`	`char`	提供 char 值
`BoolValue`	`bool`	提供 bool 值
`VisibilityValue`	`Visibility`	提供 Visibility 枚举值
`MediaColorValue`	`Color`	颜色字符串（RGB/ARGB）→`System.Windows.Media.Color`
`NullableMediaColorValue`	`Color?`	颜色字符串 → 可空 `Color?`
`SolidColorBrushValue`	`SolidColorBrush`	颜色字符串 →`SolidColorBrush`

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase0

9. 帮助类（Helpers）

库提供丰富的帮助类，按功能分组：

9.1 WpfHelpers 目录

类名	说明
`BitmapHelper`	Bitmap 帮助类
`ExportPicHelper`	导出图片帮助类
`FrameworkElementHelper`	FrameworkElement 扩展帮助
`MathHelper`	数学运算帮助
`MediaColorHelper`	媒体颜色帮助（字符串与 Color/SolidColorBrush 互转）
`MouseHelper`	鼠标操作帮助
`RenderHelper`	渲染帮助
`ScreenHelper`	屏幕信息帮助
`ScrollHelper`	滚动帮助
`UiHelper`	UI 通用帮助
`WpfRealTimeTouchHelper`	实时触摸帮助
`WpfWindowHelper`	窗口操作帮助

9.2 Attached 目录

类名	说明
`AttachAdornerHelper`	附加装饰器帮助类（可替代 Behavior 方式）
`ClickAndTouchHelper` / `ClickAndTouchHelperV2`	点击和触摸帮助
`GridHelper`	Grid 附加帮助
`MultiSelectorHelper`	多选控件帮助
`PasswordBoxHelper`	PasswordBox 附加帮助
`WpfTouchScrollHelper`	触摸滚动帮助

9.3 其他工具类

类名	位置	说明
`CustomKeyboardHelper`	`CustomKeyboard/`	自定义键盘帮助
`TextBoxStyleHelper`	`Styles/`	文本框样式帮助
`TokenizerHelper`	`Utilities/`	分词器帮助
`ValidateHelper`	`Utilities/`	验证帮助
`CompareHelper`	`WpfConverters/Core/`	比较帮助
`ConverterHelper`	`WpfConverters/Core/`	转换器帮助

10. 配置属性系统（ConfigManager）

位于 ConfigUtil/ 目录（命名空间：WPFTemplate），提供 JSON 文件配置持久化能力。

类型	说明
`IConfigItems`	空标记接口，配置类需实现此接口
`ConfigManager`	静态帮助类，提供 `SaveConfig` 和 `LoadConfig<T>` 方法
`ConfigItems`	默认配置类实现

使用方法：

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase1

配置文件自动保存在应用程序根目录下 ConfigItems.json（文件名取自 ConfigItems 类名），保存时自动创建 .bak 备份。

11. 增强集合类

11.1 FixedCountObservableCollection

固定容量的 ObservableCollection<T>。当元素数量超过指定容量时，自动移除最旧（或最新）的元素。

构造参数	类型	默认值	说明
`count`	`int`	`100`	最大容量
`removeOldest`	`bool`	`true`	超容量时移除最旧元素（false 则移除最新）

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase2

11.2 RangeObservableCollection

支持批量操作的 ObservableCollection<T>，添加/移除大量元素时避免逐个触发 CollectionChanged。

方法	说明
`BatchUpdate()`	开始批量更新（暂停通知）
`EndBatchUpdate()`	结束批量更新（恢复通知）
`AddRange(IEnumerable<T>)`	批量添加（发送 Reset 通知）
`RemoveRange(IEnumerable<T>)`	批量移除（发送 Reset 通知）
`ClearBatch()`	批量清空（发送 Reset 通知）

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase3

12. 装饰器（Adorner）

BindableContainerAdorner

可绑定的容器装饰器，配合 AttachAdornerBehavior 使用。

SmartAdorner（命名空间：`WPFTemplateLib.Adorners.SmartAdorner`）

智能装饰器系统，提供可拖拽、可调整大小的装饰器层：

SmartAdorner.Visible（附加属性）：控制装饰器是否显示
SmartAdorner.Template（附加属性）：装饰器内容模板
DragThumb：可拖拽的拖拽点控件（X/Y 绑定坐标）
ResizingAdorner：可调整大小的装饰器（Width/Height/MinWidth/MaxWidth/MinHeight/MaxHeight）

XamlAdorner（命名空间：`WPFTemplateLib.Adorners.XamlAdorner`）

AdornedControl：带装饰器的控件容器，支持 AdornerContent、IsAdornerVisible、HorizontalAdornerPlacement、VerticalAdornerPlacement、AdornerOffsetX 等属性

使用示例（来自 WPFPractice 项目）

以下示例摘自 WPFPractice 示例项目中的实际代码。

示例 1：PanelWithMessage + TabControl 整合

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase4

示例 2：CheckBoxButton 多样化样式

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase5

示例 3：SmartAdorner 拖拽系统

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase6

示例 4：RadioButton 绑定值

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase7

示例 5：转换器组合使用（BoolResultConverterToOtherResultConverter）

ObservableObject  →  SimpleBindableBase  →  NotifyDataErrorObject  →  ViewModelBase8

版本历史

版本号	更新日期	重要更新
7.3.1.0	2025-10	当前版本，完善自定义控件和转换器
7.3.0.0	2025-06	Toast 控件重构，增加 ViewModelBase 基类
7.2.0.0	2025-03	增加 PasswordInput、SeparatorStackPanel 系列控件
7.1.0.0	2024-12	增加 FruitVent 设计风格控件，主题系统优化
7.0.0.0	2024-09	重构为 net6.0-windows + net472 双目标框架
6.30.0.0	2024-06	增加 SmartAdorner 智能装饰器系统
6.29.0.0	2024-03	CheckBoxButton 重构，增加多项外观定制属性
6.28.0.0	2023-12	AutoGrid 控件引入，WpfAutoGrid 项目合并
6.27.0.0	2023-09	转换器大幅扩充，增加比较转换器系列
6.26.02.0101	2023-06	FlipableControl 控件引入
6.24.0.0	2022-12	引入 PropertyChanged.Fody 支持，SimpleBindableBase
6.21.0.0	2022-05	ViewModelBase 加入 Toast 命令支持

声明

WPFTemplateLib 由 独立观察员（DLGCY） 开发和维护，供免费使用。本库中包含的部分第三方代码（如 AutoGrid、SelectedItemBehavior 等）已在源码中标注原始出处及许可信息。使用本库时，请尊重各模块的原始许可条款。

WPF

第三方库和框架

推荐站内搜索：最好用的开发软件、免费开源系统、渗透测试工具云盘下载、最新渗透测试资料、最新黑客工具下载……

ZhouSa.com-周飒博客