PropertyGridLib 1.0.5

PropertyGridLib

WPF PropertyGrid 控件库 — 仿 WinForms PropertyGrid，基于 HandyControls UI 库。

版本 1.0.5 | .NET Framework 4.8+ | HandyControls 3.6.0+

---

目录

• 安装
• 快速开始
• 命名空间
• 标准 .NET 特性
• 自定义特性
  • FilePathAttribute — 文件路径选择
  • DirectoryPathAttribute — 目录路径选择
  • CollectionEditorAttribute — 集合编辑器
  • NumberSliderAttribute — 数值滑块
  • FormulaEditorAttribute — 公式绑定
  • MultiSelectAttribute — 多选列表
• 编辑器类型总览
• FormulaBound<T> — 公式绑定泛型类型
• TypeConverter 下拉列表
• 多语言 / 本地化系统
• API 参考
• 依赖项
• 更新日志

---

安装

NuGet 包管理器

Install-Package PropertyGridLib -Version 1.0.5

.NET CLI

dotnet add package PropertyGridLib --version 1.0.5

包引用 (PackageReference)

<PackageReference Include="PropertyGridLib" Version="1.0.5" />

安装后，NuGet 会自动拉取依赖项 HandyControls 3.6.0。

---

快速开始

1. 添加命名空间

xmlns:pg="clr-namespace:PropertyGridLib;assembly=PropertyGridLib"

2. 在 XAML 中使用

<pg:PropertyGrid x:Name="propertyGrid"
                 Width="400"
                 Height="600"
                 ShowSearchBar="True"
                 ShowDescription="True"/>

3. 绑定对象

propertyGrid.SelectedObject = new MyConfig();

4. 重置与刷新

propertyGrid.ResetSelectedToDefault();  // 重置当前选中属性
propertyGrid.ResetAllToDefault();       // 重置所有属性
propertyGrid.RefreshProperties();        // 刷新属性列表

---

命名空间

命名空间	内容
PropertyGridLib	PropertyGrid 控件、IPropertyLocalization 接口
PropertyGridLib.Controls	PropertyItem、IPropertyItem、PropertyCategory、EditorTemplateSelector、FormulaBound<T>、FormulaTreeNode、IFormulaTreeProvider、IMultiSelectProvider、MultiSelectControl、FormulaBindingControl、CustomEditorType 枚举
PropertyGridLib.Attributes	FilePathAttribute、DirectoryPathAttribute、CollectionEditorAttribute、NumberSliderAttribute、FormulaEditorAttribute、MultiSelectAttribute
PropertyGridLib.Localization	LocalizationManager、LocalizationProxy、LocalizedExtension、Language 枚举
PropertyGridLib.Converters	BoolToVisibilityConverter、InverseBoolConverter 等值转换器

---

标准 .NET 特性

PropertyGrid 自动识别以下标准 .NET 特性：

特性	说明	示例
[Category("分类名")]	属性分组显示	[Category("外观")]
[DisplayName("显示名")]	自定义属性显示名称	[DisplayName("字体大小")]
[Description("描述")]	底部描述栏显示	[Description("文字的字体大小")]
[DefaultValue(value)]	默认值，控制重置按钮显示	[DefaultValue(14)]
[ReadOnly(true)]	只读属性，不可编辑	[ReadOnly(true)]
[Browsable(false)]	隐藏属性，不在列表中显示	[Browsable(false)]

---

自定义特性

FilePathAttribute — 文件路径选择

标记属性为文件路径，显示浏览按钮，点击弹出文件选择对话框。支持多后缀筛选。

using PropertyGridLib.Attributes;

// 单后缀
[FilePath("*.log")]
public string LogFilePath { get; set; } = "";

// 多后缀
[FilePath("*.json", "*.xml", "*.txt")]
public string ConfigFilePath { get; set; } = "";

可选属性：

属性	类型	说明
Filters	string[]	文件后缀列表（构造函数参数）
Filter	string	完整过滤器字符串（如 "*.json;*.xml"）
InitialDirectory	string	初始目录
Title	string	对话框标题
Multiselect	bool	是否允许多选

---

DirectoryPathAttribute — 目录路径选择

标记属性为目录路径，显示浏览按钮，点击弹出文件夹选择对话框。

[DirectoryPath]
public string DataDirectory { get; set; } = "";

可选属性：

属性	类型	说明
InitialDirectory	string	初始目录
Title	string	对话框标题

---

CollectionEditorAttribute — 集合编辑器

标记集合类型属性使用编辑器对话框。简单类型（string、int 等）使用简易编辑器，复杂对象使用完整编辑器（含属性面板）。

// 简单类型集合 — 弹出简易编辑器（输入框 + 列表 + 增删排序）
[CollectionEditor]
public List<string> Tags { get; set; } = new List<string> { "A", "B" };

// 复杂对象集合 — 弹出完整编辑器（列表 + 属性面板 + 增删复制排序）
[CollectionEditor]
public List<RobotConfig> Robots { get; set; } = new List<RobotConfig>();

可选属性：

属性	类型	默认值	说明
CanAdd	bool	true	是否允许添加新项
CanRemove	bool	true	是否允许删除项
CanCopy	bool	true	是否允许复制项
CanSort	bool	true	是否允许上移/下移排序

集合编辑器自动区分简单类型和复杂对象。无需手动指定，控件会根据 List<T> 的 T 类型自动选择合适的编辑器。

---

NumberSliderAttribute — 数值滑块

将数值属性显示为滑块编辑器，支持 int、double、float、decimal 等数值类型。

// 整数滑块
[NumberSlider(0, 100, 5)]  // min, max, step
public int Volume { get; set; } = 50;

// 小数滑块 + 显示数值标签
[NumberSlider(0.0, 1.0, 0.1, ShowValueLabel = true)]
public double Brightness { get; set; } = 0.8;

参数说明：

参数	类型	说明
minimum	double	最小值
maximum	double	最大值
step	double	步长（默认 1）
ShowValueLabel	bool	是否显示数值标签（默认 true）

---

FormulaEditorAttribute — 公式绑定

标记属性支持公式绑定编辑器。标记后，属性编辑器下方会额外显示一行公式绑定区（链接图标 + 公式文本框 + Popup 树选择器）。

// 需要实现 IFormulaTreeProvider 接口
[FormulaEditor(typeof(MyFormulaTreeProvider))]
public FormulaBound<string> NameFormula { get; set; } = new FormulaBound<string> { Value = "默认值" };

IFormulaTreeProvider 接口：

using PropertyGridLib.Controls;

public class MyFormulaTreeProvider : IFormulaTreeProvider
{
    public List<FormulaTreeNode> GetFormulaTree(PropertyItem propertyItem)
    {
        return new List<FormulaTreeNode>
        {
            new FormulaTreeNode
            {
                Header = "流程A",
                Children = new List<FormulaTreeNode>
                {
                    new FormulaTreeNode
                    {
                        Header = "任务1",
                        Children = new List<FormulaTreeNode>
                        {
                            new FormulaTreeNode { Header = "属性X", Formula = "&{流程A.任务1.属性X}" }
                        }
                    }
                }
            }
        };
    }
}

FormulaTreeNode 属性：

属性	类型	说明
Header	string	节点显示文本
Formula	string	选中后填入的公式字符串（仅叶子节点需要设置）
Children	List<FormulaTreeNode>	子节点列表

---

MultiSelectAttribute — 多选列表

标记属性为多选列表编辑器，弹出 CheckBox 列表供用户多选。属性类型应为 List<string>，Provider 动态返回可选项。

// 需要实现 IMultiSelectProvider 接口
[MultiSelect(typeof(MyMultiSelectProvider))]
public List<string> SelectedOptions { get; set; } = new List<string>();

IMultiSelectProvider 接口：

using PropertyGridLib.Controls;

public class MyMultiSelectProvider : IMultiSelectProvider
{
    public List<string> GetAvailableItems(PropertyItem propertyItem)
    {
        return new List<string> { "选项A", "选项B", "选项C", "选项D" };
    }
}

---

编辑器类型总览

控件根据属性类型和特性自动选择编辑器模板：

编辑器	触发条件	显示效果
TextBox	string 类型	文本输入框
CheckBox	bool / bool?	复选框开关
NumericUpDown	int, double, float, decimal, long, short, byte	数字输入框（带增减按钮）
ComboBox	enum	枚举下拉选择
DateTimePicker	DateTime / DateTime?	日期时间选择器
Slider	[NumberSlider] 特性	滑块 + 数值标签
FilePath	[FilePath] 特性	文本框 + 浏览按钮
DirectoryPath	[DirectoryPath] 特性	文本框 + 浏览按钮
Collection	[CollectionEditor] 特性或 IList 类型	文本框 + 编辑按钮（弹出对话框）
DropDown	TypeConverter 标准值	下拉列表（支持排他/可编辑模式）
MultiSelect	[MultiSelect] 特性	摘要文本 + 弹出 CheckBox 列表
Expandable	复杂对象（非简单类型、非集合）	可展开子属性
Formula	[FormulaEditor] 特性或 FormulaBound<T>	值编辑器 + 公式绑定区

---

FormulaBound<T> — 公式绑定泛型类型

FormulaBound<T> 是一个包装类型，同时持有值和公式字符串。用于数据绑定场景，让属性既能存储实际值，又能记录绑定公式。

using PropertyGridLib.Controls;

public class MyConfig
{
    // string 类型公式绑定
    [FormulaEditor(typeof(MyProvider))]
    public FormulaBound<string> Name { get; set; } = new FormulaBound<string> { Value = "默认", Formula = "" };

    // int 类型也支持公式绑定
    [FormulaEditor(typeof(MyProvider))]
    public FormulaBound<int> Count { get; set; } = new FormulaBound<int> { Value = 42 };
}

FormulaBound<T> 属性：

属性	类型	说明
Value	T	实际值
Formula	string	绑定公式字符串（如 &{流程.任务.属性}）

PropertyGrid 自动检测 FormulaBound<T> 类型，使用内部类型 T 选择编辑器，同时显示公式绑定区。即使不标记 [FormulaEditor]，FormulaBound<T> 也会自动启用公式绑定输入框。

---

TypeConverter 下拉列表

当属性的 TypeConverter 提供标准值（GetStandardValuesSupported 返回 true），PropertyGrid 自动显示为下拉列表。

using System.ComponentModel;

// 自定义 TypeConverter 提供标准值
public class ComPortListConverter : TypeConverter
{
    public override bool GetStandardValuesSupported(ITypeDescriptorContext context) => true;

    public override bool GetStandardValuesExclusive(ITypeDescriptorContext context) => true;  // true=排他（不可手动输入），false=可输入

    public override StandardValuesCollection GetStandardValues(ITypeDescriptorContext context)
    {
        return new StandardValuesCollection(new[] { "COM1", "COM2", "COM3", "COM4" });
    }
}

// 使用
[TypeConverter(typeof(ComPortListConverter))]
public string ComPort { get; set; } = "COM1";

---

多语言 / 本地化系统

PropertyGridLib 内置中英文双语支持，提供三个层面的本地化能力：

1. 类库内部字符串

通过 LocalizationManager 管理搜索框占位符、对话框标题、按钮文本等 33 个内置字符串。

using PropertyGridLib.Localization;

// 切换语言
LocalizationManager.CurrentLanguage = Language.EnUS;   // 英文
LocalizationManager.CurrentLanguage = Language.ZhCN;   // 中文（默认）

// 获取本地化字符串
var text = LocalizationManager.GetString("SearchPlaceholder");
var count = LocalizationManager.GetString("SelectedCount", 5);

在 XAML 中使用标记扩展绑定：

xmlns:loc="clr-namespace:PropertyGridLib.Localization;assembly=PropertyGridLib"

<TextBlock Text="{loc:Localized SearchPlaceholder}"/>

2. 属性名 / 描述 / 分类动态翻译

实现 IPropertyLocalization 接口，让数据对象提供动态的多语言翻译。语言切换时，PropertyGrid 自动刷新所有属性。

using PropertyGridLib;
using PropertyGridLib.Localization;

public class MyConfig : IPropertyLocalization
{
    [Category("外观")]
    [DisplayName("名称")]
    [Description("对象的显示名称")]
    public string Name { get; set; } = "Test";

    // 返回 null 时回退到 [DisplayName] 特性值
    public string GetDisplayName(string propertyName, Language language)
    {
        if (language == Language.ZhCN) return null;  // 中文用特性值
        return propertyName switch
        {
            "Name" => "Name",
            _ => null
        };
    }

    // 返回 null 时回退到 [Description] 特性值
    public string GetDescription(string propertyName, Language language)
    {
        if (language == Language.ZhCN) return null;
        return propertyName switch
        {
            "Name" => "Display name of the object",
            _ => null
        };
    }

    // 返回 null 时回退到 [Category] 特性值
    public string GetCategory(string propertyName, Language language)
    {
        if (language == Language.ZhCN) return null;
        return propertyName switch
        {
            "Name" => "Appearance",
            _ => null
        };
    }
}

3. 语言切换流程

用户调用 LocalizationManager.CurrentLanguage = Language.EnUS
    ↓
触发 LanguageChanged 事件
    ↓
PropertyGrid.OnLanguageChanged() 遍历所有属性
    ↓
PropertyItem.UpdateLocalization() 递归更新 DisplayName/Description/Category
    ↓
刷新描述栏 + 重新分组过滤

内置本地化 Key 列表（33个）：

Key	中文	English
SearchPlaceholder	搜索属性...	Search properties...
SelectBindingSource	选择绑定源	Select Binding Source
SelectItems	选择项	Select Items
SelectMultiple	选择多项	Select Multiple
ResetToDefault	重置为初始值	Reset to default
FormulaPlaceholder	公式绑定...	Formula binding...
SelectFile	选择文件	Select File
SelectFolder	选择文件夹	Select Folder
AllFiles	所有文件	All Files
Files	文件	Files
ItemsCount	[{0} 项]	[{0} items]
Misc	杂项	Miscellaneous
NotSelected	（未选择）	(None)
SelectedCount	已选 {0} 项	{0} items selected
CollectionEditorTitle	集合编辑器	Collection Editor
CollectionItems	集合项	Collection Items
Properties	属性	Properties
Add	添加	Add
Copy	复制	Copy
Remove	删除	Remove
OK	确定	OK
Cancel	取消	Cancel
EditCollectionTitle	编辑集合	Edit Collection
InputPlaceholder	输入新值...	Enter new value...
MoveUp	上移	Move Up
MoveDown	下移	Move Down
Tip	提示	Tip
Error	错误	Error
AddFailed	添加失败：{0}	Add failed: {0}
CopyFailed	复制失败：{0}	Copy failed: {0}
ConvertFailed	转换失败：{0}	Convert failed: {0}
SelectItemToDelete	请先选择要删除的项	Please select an item to delete first
SelectItemToCopy	请先选择要复制的项	Please select an item to copy first
NoDefaultConstructor	类型 {0} 没有无参构造函数	Type {0} has no parameterless constructor

---

API 参考

PropertyGrid 类

命名空间： PropertyGridLib

依赖属性

属性	类型	默认值	说明
SelectedObject	object	null	要编辑的目标对象
SearchText	string	""	搜索文本（自动过滤）
ShowDescription	bool	true	是否显示底部描述栏
ShowSearchBar	bool	true	是否显示搜索栏
SelectedPropertyItem	IPropertyItem	null	当前选中的属性项
GroupedCategories	IEnumerable	null	分组后的分类列表（供绑定）
IsLoading	bool	false	是否正在加载（切换对象时显示动画）
FormulaTreeProvider	IFormulaTreeProvider	null	全局公式树提供者（可选）

公共方法

方法	说明
RefreshProperties()	刷新属性列表（重新反射对象）
ResetSelectedToDefault()	重置当前选中属性到初始值
ResetAllToDefault()	重置所有属性到初始值

事件

PropertyGrid 在内部监听 LocalizationManager.LanguageChanged 事件，语言切换时自动刷新所有属性的本地化文本。

---

PropertyItem 类

命名空间： PropertyGridLib.Controls

属性	类型	说明
Name	string	属性名（代码中的名称）
DisplayName	string	显示名称
Category	string	分类
Description	string	描述
Value	object	属性值（可读写）
ValueString	string	属性值字符串表示
PropertyType	Type	属性类型
EffectivePropertyType	Type	有效类型（FormulaBound<T> 时返回 T）
IsReadOnly	bool	是否只读
IsBrowsable	bool	是否可浏览
IsExpandable	bool	是否可展开子属性
IsExpanded	bool	是否已展开
HasDefaultValue	bool	是否有默认值
IsDefault	bool	当前值是否等于初始值
IsModified	bool	是否已修改
CustomEditor	CustomEditorType	自定义编辑器类型
FileFilter	string	文件过滤器
EnumValues	Array	枚举值列表
StandardValues	List<object>	下拉列表标准值
IsStandardValuesExclusive	bool	下拉列表是否排他
SliderMinimum/Maximum/Step	double	滑块参数
SliderShowValueLabel	bool	滑块是否显示数值
IsFormulaEnabled	bool	是否启用公式绑定
FormulaString	string	公式字符串
FormulaTreeProvider	IFormulaTreeProvider	公式树提供者
MultiSelectProvider	IMultiSelectProvider	多选列表提供者
ChildProperties	List<PropertyItem>	子属性列表
ResetCommand	ICommand	重置命令
BrowseFileCommand	ICommand	浏览文件命令
BrowseDirectoryCommand	ICommand	浏览目录命令
EditCollectionCommand	ICommand	编辑集合命令

CustomEditorType 枚举

值	说明
None	无自定义编辑器（按类型自动选择）
FilePath	文件路径选择器
DirectoryPath	目录路径选择器
Collection	集合编辑器
Expandable	可展开对象
Slider	数值滑块
DropDown	TypeConverter 下拉列表
Formula	公式绑定
MultiSelect	多选列表

---

LocalizationManager 类

命名空间： PropertyGridLib.Localization

成员	类型	说明
CurrentLanguage	Language	当前语言（默认 ZhCN）
LanguageChanged	event EventHandler	语言切换事件
GetString(key)	string	获取本地化字符串
GetString(key, args)	string	获取本地化字符串（带格式化参数）

---

依赖项

依赖	版本	说明
.NET Framework	4.8+	目标框架
HandyControls	3.6.0	UI 控件库（HandyControl 的 fork）
System.Windows.Forms	—	用于 FolderBrowserDialog（.NET Framework 内置）

---

更新日志

v1.0.5

• 展开/折叠按钮：搜索栏左侧新增"展开""折叠"RadioButton（互斥，默认展开），一键控制所有分类和可展开属性
• IsAllExpanded 依赖属性：支持 XAML 绑定，ExpandAll/CollapseAll 方法批量操作分类与属性展开状态
• _isBulkExpanding 防抖：批量展开/折叠时跳过 ApplyFilter 重建，避免状态被冲掉
• CategoryTemplate 绑定修复：Expander.IsExpanded 从硬编码 True 改为绑定 PropertyCategory.IsExpanded
• NonSerialized 过滤：[field:NonSerialized] 标记的属性现在同时从显示和序列化中过滤（CreateProperties + LoadChildProperties 双重过滤，SaveOriginalValue 跳过，DeepClone try-catch 兜底）
• 默认字体 Consolas：GlobalFontFamily 从 Microsoft YaHei UI 改为 Consolas，Style 同步设置
• 展开/折叠多语言：新增 ExpandAll/CollapseAll 本地化 Key（中文"展开/折叠"，英文"Expand/Collapse"）

v1.0.3

• 正式发布版：修复中文乱码问题，完善开发文档
• 中文乱码修复：修复 8 个源文件中的 UTF-8 编码损坏问题
• 引用类型分组：SampleObject 示例中引用类型属性统一分组展示
• 完整开发文档：编写 README.md 完整开发文档，涵盖所有特性说明与 API 参考
• NuGet 包优化：更新包描述、标签，打包 README.md 到 NuGet 包

v1.0.2

• 多语言系统：内置中英文双语，LocalizationManager 管理 33 个字符串 Key
• IPropertyLocalization 接口：数据对象可实现动态属性名/描述/分类的多语言翻译
• LocalizedExtension：XAML 标记扩展 {loc:Localized Key}，语言切换自动刷新
• Category 本地化：分类名支持语言切换时动态翻译
• Dialogs 本地化：集合编辑器对话框（CollectionEditorDialog / SimpleCollectionEditorDialog）全部字符串支持多语言
• MultiControl 本地化：多选列表摘要文本支持多语言
• 命名空间提升：PropertyGrid 控件从 PropertyGridLib.Controls 提升到 PropertyGridLib，方便引用
• 引用类型示例：SampleObject 将引用类型属性（集合、FormulaBound、嵌套对象）统一分组展示

v1.0.1

• FormulaEditor 特性：[FormulaEditor(typeof(Provider))] 公式绑定编辑器
• FormulaBound<T> 泛型类型：包装值 + 公式的数据绑定类型
• IFormulaTreeProvider 接口：公式树数据提供者
• MultiSelect 多选列表：[MultiSelect(typeof(Provider))] 动态多选编辑器
• IMultiSelectProvider 接口：多选列表数据提供者
• TypeConverter 下拉列表：自动识别 TypeConverter.GetStandardValues 显示为下拉列表
• FilePath 多后缀：[FilePath("*.json", "*.xml", "*.txt")] 支持多后缀筛选
• HandyControl SearchBar：搜索栏集成 HandyControl SearchBar
• MultiSelect 摘要：多选列表显示已选项摘要，支持点击弹出

v1.0.0

• 初始版本
• 属性自动发现与反射
• 分类显示（[Category]）
• 自定义显示名（[DisplayName]）
• 属性描述（[Description]）
• 默认值与重置（[DefaultValue]）
• 只读属性（[ReadOnly]）
• 隐藏属性（[Browsable]）
• 搜索过滤
• 支持编辑器：string、bool、数值、enum、DateTime、可展开对象、集合
• 自定义特性：FilePath、DirectoryPath、CollectionEditor、NumberSlider

---

许可证

MIT License