PropertyGrid 属性编辑契约
ColorVision 的通用属性面板由属性元数据、PropertyEditorHelper 和 IPropertyEditor 组成。回答“新增编辑器”“编辑器不命中”“保存为何没生效”时,从本页定位契约,再核对被编辑对象和实际宿主;不要为每个配置对象新建独立编辑框架。
任务路由
| 问题 | 核对入口 |
|---|---|
| 给一个属性指定编辑器 | PropertyEditorTypeAttribute 和 IPropertyEditor.GenProperties |
| 同一类型统一使用编辑器 | PropertyEditorHelper.RegisterEditor<TEditor>(Type) |
| 一组类型按条件匹配 | RegisterEditor<TEditor>(Func<Type, bool>),注意注册顺序 |
| 面板没有显示属性 | 属性可读写、非索引属性、Browsable、元数据 Provider 和嵌套对象规则 |
| 编辑后原对象没变化 | PropertyEditSession.Mode、工作副本、Commit() 与宿主保存动作 |
| 关闭或取消后参数仍然变化 | PropertyEditorWindow 默认 Immediate,关闭不执行回滚 |
| Flow 模板选择器退化成文本 | 属性上的 PropertyEditorType、具体模板编辑器与生成异常日志 |
命令属性页自动生成
PropertyEditorHelper.GenCommand(object, UniformGrid, bool compact = false) 是设备属性页共用的命令入口。光谱仪、相机、PG、源表、校正、算法、滤光轮、传感器、照明控制器和第三方算法页都将设备对象交给该入口;页面只提供容器,不维护各自的按钮列表、分类卡片或特殊角标。设备子页面统一使用零额外边距的滚动容器和命令网格,垂直滚动条按需显示,底色使用 RegionBrush;内容外边距由配置窗口管理,避免切换设备时标题和卡片错位。
生成器读取公开可读、非索引属性上的 CommandDisplay,包含基类命令,跳过 Browsable(false)、空命令和未标注属性。分类使用 Category,分类顺序使用 CommandDisplay.CategoryOrder,组内顺序使用 Order;名称和说明分别使用 CommandDisplay.DisplayName 与 Description,由对象资源管理器本地化。未分类命令独立归组,只有一个无分类组时省略分类标题。
[CommandDisplay("RefreshDeviceList", Order = 1, CategoryOrder = 0)]
[Category("DeviceConnection")]
[Description("CommandRefreshDevicesHint")]
public RelayCommand RefreshDeviceIdCommand { get; set; }DeviceConnection 等字符串是资源键,资源缺失时回退到原文。设备通用分类为 设备与连接、校准与校正、采集与显示、数据与日志、服务与维护,只显示实际有命令的分类。运行日志归入数据与日志;许可证和删除归入服务与维护。设备的服务重启命令标记为 Browsable(false),属性页不显示,右键菜单仍绑定原命令。新增按钮应维护命令元数据及资源,不为某种设备增加一份手写界面。
普通模式由 PropertyEditorCommands.cs 和 CommandPanelStyles.xaml 统一生成纵向分类及自适应按钮网格。分类标题使用 15 DIP 半粗体,操作名称使用 12 DIP 常规字重,操作项最小高度为 40 DIP;分类通过标题与统一间距分组,不叠加外层卡片和分隔线。分类可用宽度低于 460 DIP 时为单列,其余为双列,末行单项跨满整行,隐藏操作不占布局位置。底色、边框、正文和交互强调色直接复用更新窗口的主题色值,浅色和深色主题保持一致。
名称显示在按钮中;说明不占用页面空间,只写入无障碍帮助文本并与名称一起用于工具提示。按钮绑定原始命令并保留 CanExecute 禁用行为,标为 Highlighted 的操作使用警示色;PropertyVisibility 继续控制显示条件。生成界面不会执行命令。
生成器拥有传入容器的内容,重新生成会替换旧按钮,宿主不要在容器中预置业务按钮。保留原有公开方法签名,现有调用端自动使用统一样式;Flow 节点检查器的 compact: true 保持平铺的小按钮工具栏,不加入分类卡片。
相机、光谱仪和校正模块的“编辑显示配置”统一归入“设备与连接”,分组顺序为 0,与修改配置等设备设置入口放在一起。
设置行呈现
属性编辑器生成控件时按需读取当前应用主题资源。启动时缺少样式的字段,可在资源加载后重新打开面板恢复。新生成的控件使用最新的样式。
SettingsPropertyPresenter.Create 为设置页面复用现有 PropertyEditor,保留原编辑器绑定、验证和 PropertyVisibility,将名称/说明放在左侧、控件放在右侧。支持属性白名单及 Display 本地化元数据,后者优先于旧 DisplayName / Description;本地化 Display.GroupName(没有时回退 Category)生成组标题。单控件的外边距和最小宽度由行容器统一处理,避免下拉框边框被固定列裁剪。
SliderPropertiesEditor 面向具有 RangeAttribute 的数值设置:同一行同时生成滑块和精确文本框,二者通过原属性的双向绑定保持同步。是否使用滑块仍由属性上的 PropertyEditorTypeAttribute 显式声明,未提供有效范围时回退普通属性编辑器,避免把任意数值字段误设为相同区间。
该呈现器只负责布局,不负责配置保存或作用范围。当前用于图像设置;Desktop 设置仍使用自己的呈现逻辑。
IPAddressBox 位于共享 ColorVision.Themes.Controls 层,可直接用于 XAML;PropertyGrid 在 ColorVision.UI 层用 [PropertyEditorType(typeof(IPAddressPropertiesEditor))] 选择 IPv4 编辑器。四段分别输入 0~255,输入点号或三位数字可进入下一段,左右箭头/退格支持跨段移动,支持粘贴完整 IPv4 或单段数字。无效输入不截断、不钳位;清空某段会将不完整草稿传入双向绑定,由宿主负责提交校验。IsReadOnly 禁止输入与粘贴,元数据编辑器也遵守 ReadOnly。
接受主机名、IPv6 或串口混合地址的字段选择 NetworkAddressPropertiesEditor(直接控件使用 AllowTextMode=true),已有非 IPv4 值自动显示文本输入;右侧“⋯”可切换 IPv4 与文本模式。已有字段及序列化格式保持原样,不增加 DHCP、DNS 或操作系统网卡配置。当前接入源表、传感器、MQTT/MySQL 连接、Socket 协议、视频连接、Windows 服务插件及 ProjectKB 的相关地址项;网卡地址列表仍使用原有选择控件,独立 .NET Framework 示例保持自身输入方式。通用属性面板中的 PG Addr / Port 使用 PGConnectionPropertiesEditor,按 IsNet 和 CH431.I2C 类型切换网络、串口和设备索引的编辑器与标签,不改写存储值;独立 PG 配置窗口按类型显示单套字段,草稿隔离与保存规则见设备服务链。
接口与注册
UI/ColorVision.UI/PropertyEditor/PropertyEditors.cs 在 System.ComponentModel 命名空间定义唯一入口:
public interface IPropertyEditor
{
DockPanel GenProperties(PropertyInfo property, object obj);
}属性级选择使用 [PropertyEditorType(typeof(MyEditor))];MyEditor 在此只是占位类型名,实际实现应从现有编辑器复制必要模式。可参考 Editor/TextSelectFilePropertiesEditor.cs:每次调用创建新面板,使用 CreateLabel、CreateTwoWayBinding(obj, property) 和共享小控件样式。
集合元素的编辑方式在集合属性上用 CollectionEditorTypeAttribute 声明。字符串列表在“编辑列表”窗口中直接逐行编辑,普通文本默认使用文本框;目录列表标注 [CollectionEditorType(typeof(TextSelectFolderPropertiesEditor))],文件列表标注 TextSelectFilePropertiesEditor,行内复用相应的选择和打开位置按钮,使用者无需再选择编辑器类型。缓存大小预处理的 FolderPaths 使用目录标记。添加后自动选中新行并聚焦文本框;修改、增删和排序只作用于工作列表,确定后才写回原集合,取消或关闭丢弃本次修改。非字符串元素继续使用项编辑窗口,对象项和嵌套列表在列表窗口与项窗口分别使用配置工作副本,并保留对象中 Browsable(false) 的可写配置属性;项窗口确定只更新外层工作列表,外层列表确定才提交原属性,因此内层取消或内层确定后再取消外层都不修改原配置。普通列表不显示索引列,字典仍按 Key/Value 编辑。
算法、相机、校正、源表、光谱、POI、传感器模板和旧模板管理的列显示偏好,以及 Spectrum 插件的同类配置,使用 Browsable(false) 从属性面板隐藏。已有表格的列显示右键菜单和表头排序入口保持原样,集合继续序列化保存;隐藏不清空已有偏好。算法和光谱视图的“显示列表”与“显示侧边栏”统一放在 View 分类。“编辑列表”的列表与内容容器使用动态主题文字色,普通值及对象摘要在深浅色主题下保持可读。
路径语义由属性所属业务声明,不根据字符串内容或属性名猜测:文件融合与四图合成的输入文件集合使用文件项编辑器;图片投影列表项、光谱插件校准组的文件字段以及 POI 的 CAD/二次修正文件使用文件属性编辑器;文件服务根目录、自动快照目录使用目录属性编辑器。Everything 可执行文件也是文件。输出文件名、扩展名、URL、普通标定分组名称保持文本;解决方案项目引用同时接受文件、目录和相对路径,保留其原有项目管理入口与文本语义,不能直接替换成仅选择本机文件或目录的控件。
Engine 模板和量程编辑器可直接构造,不需要代理注册。公共 Flow 基类的 FlowDeviceNameEditor 由 Engine 注册到设备选择器;FlowEditorCanvas 会自动注册,其他宿主直接使用这个设备代理时需先调用 FlowNodePropertyEditorRegistration.EnsureRegistered()。未注册设备代理会退回普通文本框。
类型级注册通过 PropertyEditorHelper.RegisterEditor<TEditor>(typeof(TargetType)) 或匹配谓词完成。注册不是给每个对象存一份编辑器实例;通用注册表按编辑器类型缓存实例,编辑器必须可构造并实现 IPropertyEditor。
选择顺序与失败行为
PropertyEditorHelper 的生成链按下列顺序尝试:
| 顺序 | 入口 | 未选出可用面板时 |
|---|---|---|
| 1 | 当前 IPropertyEditorMetadataProvider.GetEditorType(property) | 返回空或选中编辑器生成失败时继续属性标注;回调自身抛异常则终止该行 |
| 2 | 属性上的 PropertyEditorTypeAttribute.EditorType | 继续尝试属性类型注册 |
| 3 | PropertyEditorRegistry.Find(property.PropertyType) | 无类型注册时尝试嵌套对象 |
| 4 | 可生成的嵌套对象属性面板 | 无有效控件则不生成该行 |
未指定编辑器类型时按属性类型匹配已注册的编辑器,包括只写了无参 [PropertyEditorType] 的属性。布尔值使用开关,枚举使用下拉框,文本和数值使用带类型绑定的文本框。无参标注仍可指定绑定更新时机。TextboxPropertiesEditor 将可空数值的空文本映射为 null,并支持通过 DisplayFormat.DataFormatString 指定显示格式。
类型注册内部先找精确类型,再按注册顺序寻找第一个命中的谓词。谓词抛异常会记录警告并跳过该谓词。TryGenerateEditor 在构造或 GenProperties 失败时记录错误并返回空,让外层按上述路径继续;不保证任意未知类型或所有编辑器失败后都会出现文本框。
异常边界不能混为一谈:元数据 Provider 的 GetEditorType 回调在 TryGenerateEditor 之外。该回调自身抛异常时,外层 TryCreatePropertyDockPanel 记录错误并返回 false,不会继续尝试属性标注;可见性绑定等外层步骤抛异常也会终止该行。新增 Provider 时需单独验证这些异常路径。
实例、绑定与可见性
通用属性面板和属性编辑窗口在未指定旧 DisplayName、Description、Category 时,分别读取 DisplayAttribute 的名称、说明和分组,并支持其 ResourceType 本地化;显式名称覆盖与元数据 Provider 仍优先。窗口标题也支持类级 Display.Name。旧标注优先级保持不变,资源声明无效时记录警告并退回原有字段名/类型名,避免整个属性页无法打开。这与 SettingsPropertyPresenter 优先使用 Display 的既有规则不同。
PropertyEditorRegistry.GetOrCreate复用编辑器实例。不要把某个窗口、属性对象或生成的DockPanel保存到编辑器实例字段;本次调用的状态应放在新建控件、局部变量或适当释放的订阅中。CreateTwoWayBinding(obj, property)默认逐属性变化回写,启用异常与数据错误验证;属性标注可以指定UpdateSourceTrigger。只读属性或[ReadOnly(true)]使用单向绑定,生成控件也按只读元数据禁用。- 标题、类别、描述优先用
DisplayName、Category、Description和现有资源解析;显示条件用PropertyVisibility,永久隐藏用Browsable(false)。 窗口将条件显隐与搜索筛选叠加,搜索、清空和排序不覆盖条件绑定;条件变化时同步隐藏没有可见字段的分类及导航项。条件属性需发送PropertyChanged通知;隐藏只改变展示,不重置已填写的值。 - 通用属性面板按组内属性行的可见性隐藏空分类,包括标题、外框和间距;分类仍有高级选项切换入口时保留入口。需要随条件变化更新时发送
PropertyChanged;只需显示时判断的外部状态可通过当前对象的只读条件属性提供,重新生成面板时读取。 - 用于打开当前对象属性窗口的
EditCommand应标记Browsable(false),避免在窗口内部再次生成“执行”按钮;JsonIgnore只控制序列化,不控制界面可见性。不要全局按名称或ICommand类型屏蔽命令,设备上标有CommandDisplay的“修改配置”和配置内的“清除缓存”等业务操作仍应保留。 - 布尔、枚举、数值、日期、集合、字典、Brush/Color 等内置映射以
PropertyEditorBuiltIns.cs为准。先检查能否复用,不把“新业务字段”自动等同于“需要新编辑器”。
枚举下拉框的显示文本由共享 EnumPropertiesEditor 生成。首先以枚举成员名查询当前对象的资源管理器;资源命中时保留该译文,即使译文与成员名相同。对象资源缺失或读取失败时,继续查询枚举类型所在程序集的资源;两者均未命中时,复用 EnumExtensions.ToDescription():优先取枚举字段的 DisplayAttribute(支持 ResourceType 指向的显示资源),其次取 Description,最后回退成员名;得到的文本依次经过对象和枚举所属资源解析。这样节点跨程序集移动时,枚举仍能使用原所属模块的译文;对象已有的译文优先,包括译文与键相同的情况。例如 CVCIE 的 Source 可用 Description("原图(CVRAW)") 显示中文,无需专用编辑器。
显示文本与选项值分开保存:ComboBox 展示 KeyValuePair.Value,SelectedValue 仍绑定枚举对象 Key,因此选择中文标签不会把属性或序列化值改成中文字符串。可空枚举保留首项的空白显示和 null 值。其他语言仍取决于资源表或字段显示元数据,不因支持 Description 就自动获得翻译。
PropertyEditorWindow 将当前编辑对象的字段按类别展示,并提供搜索与排序;复杂对象可展开为嵌套面板。字段缺失时先确认宿主传入了哪个对象、当前搜索条件和元数据,再查编辑器匹配,不根据界面控件外观猜属性类型。嵌入式属性面板不一定具有这个窗口的搜索、按钮或编辑会话,需核对实际宿主。
独立窗口标题使用本地化的“编辑”与对象类型的 DisplayName(经对象资源解析;未标注时回退类型名),例如“编辑 ConfigAlgorithm”。只有一个顶层类别且其中所有属性均未显式标注 Category 时,右侧默认根类别不重复绘制标题、背景和边框;其容器、搜索标签和左侧树节点仍保留,嵌套对象如 FileServerCfg 继续显示分组。显式类别或多个顶层类别保持原有标题与边框。是否保留类别取决于实际生成的属性内容,不依赖标题子元素的数量,因此只有一个属性的无标题根也不会丢失。
搜索框常驻左右分栏上方,递归过滤整个对象的分类名、属性代码名、显示名和描述,不搜索属性值,也不因左树选中某分类而缩小范围。窗口内 Ctrl+F 通过 ApplicationCommands.Find 聚焦搜索框并全选已有关键词;只有搜索框内不带修饰键的 Esc 清空筛选并保留窗口,其他控件的按键路由不变。输入框提供清除按钮,边框跟随当前主题。非空查询没有匹配项时,右侧显示“没有匹配的属性”和“清空搜索”按钮,后者清空筛选并将焦点送回搜索框。空状态独立于属性容器,不参加递归过滤;清空、排序或重新生成属性后同步更新,不以“没有树节点”直接跳过处理。这些查找动作不调用提交、重置或宿主持久化。
搜索输入区使用 34 DIP 高度、14 DIP 字号及 14 DIP 图标;局部圆角模板保留标准 TextBox 的 PART_ContentHost,边框随实际高度布局,不沿用小号模板的固定内部高度。仅有文字时显示独立清除按钮。占位文字使用主题的次级文字色,输入后隐藏,且不拦截鼠标点击;输入内容与两侧图标预留独立空间。
搜索区和左右面板使用统一的 8 DIP 外留白及面板间距。左树选中行使用主题中性底色和窄强调色标记,不使用整行高饱和底色;非活动时保留并减弱标记。键盘焦点由当前节点标题行的细边框提示,替代覆盖整个树项的默认虚线框。导航通过节点绑定完成选择、展开及右键操作。
底部按钮使用统一尺寸与间距,仅“确定”强调主色;重置、恢复默认、关闭/取消使用普通按钮样式,不改变各按钮的事件、默认键或编辑模式语义。无标题默认根同时含直接字段和嵌套卡片时,仅在此窗口为直接字段增加左右各 6 DIP 留白,与嵌套卡片的边框和内距对齐;不改变共享编辑器标签宽度或垂直间距。
编辑与持久化不是同一动作
PropertyEditSession 有两种模式:Immediate 直接使用原对象;Transactional 使用配置数据的工作副本,调用 Commit() 才复制回原对象。它不是数据库事务或外部设备操作的回滚机制;WPF DispatcherObject 等运行时引用仍可共享,不能理解成整个运行环境完全隔离。
PropertyEditorWindow(object config) 默认是 Immediate。按钮语义由窗口和会话代码共同决定:
| 动作 | 实际行为与边界 |
|---|---|
| 编辑字段 | 通常按绑定触发条件写入 EditableObject;Immediate 下它就是原对象 |
| 确定 | 先触发可取消的 Submitting,允许后才 Commit()、触发 Submitted 并关闭;是否落盘或保存模板取决于宿主订阅 |
| 取消/关闭 | Cancel_Click 只关闭窗口,未调用恢复;Immediate 下按钮显示“关闭”,已写入原对象的值不会因此撤销 |
| 重置 | Reset() 将打开时的初始快照复制到当前编辑对象;Immediate 下同样会修改原对象 |
| 恢复默认 | ResetToDefaults() 用可构造的默认对象覆盖当前编辑对象;不是从配置备份文件恢复 |
宿主可在 Submitting 中设置 PropertyEditorSubmittingEventArgs.Cancel=true,并通过 ErrorMessage 在窗口内显示拒绝原因。取消时保留窗口和工作副本,不调用 Commit()、Submitted 或宿主保存动作;没有订阅时保留原有提交流程。既有构造函数、Submitted 和兼容别名 Submited 的调用形状不变。该边界可用于提交前重新验证操作授权;Immediate 模式已经直接写入的值仍不因此回滚。
编辑器只负责把控件值写入传入的 obj。判断“配置保存失败”需分别核对字段绑定、会话提交和宿主持久化,不能把界面值变化或确定按钮当成文件/数据库已保存的证据。软件配置与设备资源配置有不同的保存/发布边界。只读诊断不要用改值、重置或恢复默认来探测设备配置;实际验证应使用隔离对象,并经授权检查保存后重开与宿主副作用。
Flow 适配边界
需要 Engine 模板或量程编辑器的兼容节点位于 Engine/ColorVision.Engine/FlowProcessing/Nodes/Compatibility/,属性直接声明 PropertyEditorType。类级属性名映射、Selector 和模板代理不再作为扩展入口。Engine/FlowEngineLib/PropertyEditor/FlowNodePropertyEditors.cs 仅保留公共基类设备字段使用的 FlowDeviceNameEditor、代理基类及注册表;Engine 注册设备选择器,让公共执行层不引用业务 UI。
FlowTemplatePropertiesEditors.cs 提供相机、校准、POI、SMU、传感器和算法模板及量程的无状态编辑器,控件构建共用原有模板选择逻辑。校正模板切换设备时仍刷新;增益联动通过校正属性上的具体编辑器声明识别。普通字符串、数值和枚举字段沿用通用编辑器,不因此迁移节点。
Flow 的单模板、多模板族下拉框及算法补充面板在已保存名称不属于当前模板列表时显示“找不到模板:原模板名”,提示置于名称前,避免窄字段隐藏错误状态;悬停可查看完整提示,真正未配置时仍为空白。提示仅是当前控件的占位选项,不添加到模板集合、不改写节点配置;重新选择或清除才修改该字段。校正模板在用户切换设备后仍按原规则清除新设备不可用的引用。找不到模板时禁用直接打开该模板的按钮,齿轮仍可管理当前可用的模板列表;运行时继续按保存的原名称查找和报错,不忽略失效引用。
只有多模板族或随节点算法类型变化的补充面板才使用 FlowProcessing/Editor/NodeConfiguration/。未注册的 FlowPropertyEditorProxy 有自己的文本编辑器回退;它与上面的通用 PropertyGrid 失败规则不是同一个契约。代理内部不一定复用实例,不能把通用缓存规则直接套给所有宿主。
验证入口与缺口
自定义编辑器仍需在目标宿主检查样式、键盘操作、错误提示、订阅释放和保存重开;新增公开签名还要验证实际插件 DLL 的二进制兼容性。
