Files
ctbjrj/cadbt/.agents/skills/sd-enhanced-components/SKILL.md
T

167 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: sd-enhanced-components
description: SharpDevelop 5.x WinForms 设计器**全部工具箱**(5 分类 81 条目)的属性手册与 Designer.cs 代码生成规则:增强组件(Smart.CustomComponents 13 个:停靠面板/停靠窗口、圆角按钮、图片按钮、侧边菜单、功能区 RibbonStrip、增强数据表格、多选下拉框、可调高文本框/下拉框、OK/NG 状态灯、变量绑定控件、日志组件)+ 标准控件(Button/TextBox/ListView/TreeView/TabControl/菜单工具栏/对话框等 45 个)+ 数据/组件/打印(BindingSource、Timer、SerialPort、PrintDocument 等 23 个)。每个控件含全部属性(类型/默认值/序列化规则)、事件与运行时 API。当用户要在 WinForms 项目里使用、询问属性、手写或生成任何 *.Designer.cs 代码、生成停靠窗口类、排查"?"载入错误或"valid theme"运行错误时,必须使用本技能。提到"增强组件""Smart.CustomComponents""停靠窗口""功能区""RibbonStrip""工具箱""某个控件有哪些属性""生成设计器代码"即触发。新建解决方案时用 copy-to-solution.cmd 把本技能复制到项目里。
---
# SharpDevelop 增强组件(Smart.CustomComponents)手册
库源码:`F:\Visual Studio\1\33\SharpDevelop-master\src\Libraries\CustomComponents\`(本技能内容即从该源码与编译产物反射逐项提取,属性名/类型/默认值以源码为准)。
工具箱类别名:**增强组件**(SharpDevelopControlLibrary.sdcl 注册,13 个控件)。
## 使用本技能的典型任务
1. 在用户项目里手工使用/推荐这些控件的属性("这个控件有哪些属性")
2. 生成或校对 `*.Designer.cs`(SharpDevelop CodeDom 序列化风格)
3. 从停靠窗口集合配置生成窗口类三件套(等价于"生成停靠窗口代码"命令)
4. 排错:设计器载入 `?`、运行时 "DockPanel.Theme must be set to a valid theme"
## 工具箱全量清单(5 分类 81 条目,权威来源 data\options\SharpDevelopControlLibrary.sdcl)
| 分类 | 条目数 | 属性手册 |
|---|---|---|
| 增强组件(Smart.CustomComponents) | 13 | `references/components.md` |
| Windows Forms(标准控件+菜单+对话框) | 45 | `references/winforms-controls.md` |
| Data(绑定/表格/数据集) | 7 | `references/winforms-components.md` |
| Components(后台/IO/系统组件) | 11 | `references/winforms-components.md` |
| Printing(打印全家桶) | 5 | `references/winforms-components.md` |
(Timer/ErrorProvider/HelpProvider/ImageList 在 Windows Forms 与 Components 两个分类重复出现,规则一致;Data 分类里的 DataNavigator 在 .NET 4.8 不存在,是死条目,用 BindingNavigator。)
**读哪个文件**:增强组件 → `references/components.md`;标准控件/菜单/对话框 → `references/winforms-controls.md`;组件/数据/打印 → `references/winforms-components.md`;**写任何 Designer.cs 代码前再读 `references/codegen.md`**(骨架模板、Content 集合、菜单嵌套、ListView/TreeView、RibbonStrip 三层集合、非可视组件、停靠窗口三文件流程)。
## 复制到新解决方案(三种方式,已自动化)
本技能的分发链(源→编译产物→新方案):
```
用户级正本 C:\Users\099978\.agents\skills\sd-enhanced-components\ ←源(改这里)
① 编译 Smart.CustomComponents 时同步到 SharpDevelop 仓库根副本 + bin\sd-enhanced-components\
(bin = 设计器编译输出/测试运行目录)
② SharpDevelop 新建解决方案时自动复制到 <新方案>\.agents\skills\sd-enhanced-components\
```
1. **全自动**:本定制版 SharpDevelop 在"文件→新建→解决方案"落盘后自动复制(`ProjectTemplate.CreateAndOpenSolution` 里调 `SkillFolderSync`,日志在 `bin\SkillSync.Log.txt`)。源找不到时自动回退:先 bin,再应用根目录。
2. **手动脚本**:`copy-to-solution.cmd <解决方案目录>`(同样复制到 `<目录>\.agents\skills\sd-enhanced-components\`)。
3. **全局生效**:用户级技能目录本就全局生效——复制是留档与给其他 AI 工具。
改手册后同步三处:用户级正本 → 重编 Smart.CustomComponents(自动进仓库根副本 + bin)→ 新方案由 SharpDevelop 自动带。
## 零、项目组织铁律(用户强制,最高优先级)
1. **UI 只写主窗口**:新建解决方案自带的主窗口 MainForm(MainForm.cs / MainForm.Designer.cs)是唯一 UI 承载体,所有控件/布局/Designer.cs 生成一律写进 MainForm;Program.cs 保持 `Application.Run(new MainForm())`。
2. **绝不另开窗口写 UI**:不要为了放界面新建 TestForm/Form2 之类第二个窗体;多窗口只在用户明确要求时才做。
3. **AI 生成 Designer.cs 前必须先写引用(否则死锁)**:手写/生成 Designer.cs 用了增强控件而项目尚无程序集引用时,设计器加载第一步(类型解析)就失败(一片 CS0246),而"自动补引用"恰恰跑在设计器加载流程内部——类型解析不过它就没机会执行,形成死循环:**引用缺失 → 设计器加载失败 → 自动补引用不触发 → 引用依然缺失**。所以**写 Designer.cs 的同一次改动里必须先把 9 个引用写进 csproj**(完整清单见第一章)。HintPath **默认指向 SharpDevelop 安装目录** `C:\Program Files (x86)\SharpDevelop\5.2\bin`——装完即存在、机器间一致;**装在非默认位置时先用第一章"定位实际安装目录"找到真实 bin 再写**;开发机要立刻用仓库最新控件时可临时换仓库 bin `F:\Visual Studio\1\33\SharpDevelop-master\bin`(仅本机存在,**交付/通用模板别用**)。前提:安装目录必须是最新构建(jk55 案例:08-27 旧安装包缺 RibbonStrip/Logger,13 控件只认 11——须重打 MSI 重装或用仓库 bin 最新 DLL 覆盖安装目录)。"切设计标签自动补引用"只在**工具箱拖放**场景有效(那时设计器本来就能加载)。`<Private>True</Private>` 编译时会把 DLL 复制进项目 bin\Debug,之后运行/分发不再依赖 HintPath 原位置。案例:jk55 项目(2026-09-01)。
4. 历史测试项目里 AI 写的 TestForm(如 ww123)是测试产物,**不是范本**;交付写法以本节为准。
5. **属性白名单 + 报错后完全重启(s23 案例 2026-09-01)**:Designer.cs 每个属性必须能在 components.md 该控件条目下查到——跨控件抄属性会抛 `CodeDomSerializerException`("没有名为 X 的属性")并**中止整个设计器加载**(已知易错:VariableEditTextBox 无 PlaceholderText、VariableDisplayLabel 无 BorderStyle)。改完报错的 Designer.cs 后**必须完全退出 SharpDevelop.exe 重开**(关标签页没用)——设计器 CodeDom 反序列化的 AppDomain 在进程内缓存旧异常,不重启会一直回放。
6. **Designer.cs 内绝不调用自定义辅助方法(H1 案例 2026-09-01,适用于所有项目)**:`InitializeComponent()` 里只写标准 CodeDom 语句(new/属性赋值/集合 Add/AddRange/事件挂接/Controls.Add)。自定义方法调用(如 `ConfigurePage(...)`)会被反序列化错误解析成基类 Form 方法,抛 `MissingMethodException` 并中止加载。处置:只改该项目自己的 Designer.cs(删调用+删方法定义,展开成属性赋值),**不动 SharpDevelop 本身、不动设计器配置**;重新编译项目后完全退出 SharpDevelop 再重开(清进程内异常缓存)。
7. **控件库修 bug 后,用户项目必须重编一次才吃到**(成套报价软件案例 2026-09-01):项目引用是 `<Private>True</Private>`——编译时把控件 DLL **拷贝**进项目 `bin\Debug`,之后运行/设计器用的都是这份拷贝。所以控件库更新后:改控件 → 重编 Smart.CustomComponents → **用户项目也要重编**(拷贝才会刷新);排查"控件还有老 bug"先看项目 `bin\Debug\Smart.CustomComponents.dll` 时间戳,不是看仓库 bin。
## 一、项目前提(缺一不可)
用这些控件的用户项目必须是:
```xml
<TargetFrameworkVersion>v4.8</TargetFrameworkVersion>
<PlatformTarget>x86</PlatformTarget> <!-- SharpDevelop 调试器仅 32 位;SQLite 为 x86 混合模式 -->
<Prefer32Bit>true</Prefer32Bit>
<ApplicationManifest>app.manifest</ApplicationManifest> <!-- dpiAware,否则运行时缩放 2/3 -->
```
引用清单(老式 csproj 引用不传递,**9 个全要**,HintPath 默认指向 **SharpDevelop 安装目录** `C:\Program Files (x86)\SharpDevelop\5.2\bin`(稳定、装完即有);开发机临时用仓库 bin 见零章第 3 条):
| 程序集 | 备注 |
|---|---|
| Smart.CustomComponents, Version=1.0.0.0, Culture=neutral, PublicKeyToken=ba044a4aa43e0dc4 | 主库,强命名 |
| WeifenLuo.WinFormsUI.Docking | DockSurface 基类 DockPanel |
| WeifenLuo.WinFormsUI.Docking.ThemeVS2015 | VS2015 主题(含关闭按钮补丁) |
| System.Data.SQLite | x86 混合模式 1.0.119(增强表格用,无需 Interop.dll) |
| log4net | **Logger 日志组件后端**(漏了 Logger 报类型解析失败) |
| System.Resources.Extensions / System.Memory / System.Runtime.CompilerServices.Unsafe / System.Numerics.Vectors | **二级依赖链**(主题资源加载必需,漏了运行时报 valid theme) |
HintPath 模板:`C:\Program Files (x86)\SharpDevelop\5.2\bin\<dll 名>`,并加 `<Private>True</Private>`(可复制 csproj 片段见 codegen.md §0.1)。
工具箱拖放会自动补齐引用(此时设计器能加载,自动补才跑得起来);AI 手写 Designer.cs 必须按零章第 3 条先写引用。
### 定位实际安装目录(装在非默认位置时,AI 按顺序执行)
注册表卸载键的 `InstallLocation` 是**空的**(WiX 安装包不写该值),别指望它。按可靠性依次试:
```powershell
# ① IDE 正在运行:进程路径(exe 所在目录即 bin,最直接)
Get-Process SharpDevelop -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Path
# ② 开始菜单快捷方式解析(已实测可用)
$s = New-Object -ComObject WScript.Shell
Get-ChildItem "$env:ProgramData\Microsoft\Windows\Start Menu\Programs", "$env:AppData\Microsoft\Windows\Start Menu\Programs" -Recurse -Filter '*SharpDevelop*.lnk' -ErrorAction SilentlyContinue | ForEach-Object { $s.CreateShortcut($_.FullName).TargetPath }
# ③ 已有项目的 HintPath(能跑通的项目里记的就是真实安装位置)
Get-ChildItem "$env:USERPROFILE\Documents\SharpDevelop Projects" -Recurse -Filter *.csproj -ErrorAction SilentlyContinue | Select-String 'Smart\.CustomComponents\.dll.*HintPath'
# ④ 常见默认位置探测
Test-Path 'C:\Program Files (x86)\SharpDevelop\5.2\bin\SharpDevelop.exe'
Test-Path 'C:\Program Files\SharpDevelop\5.2\bin\SharpDevelop.exe'
```
找到的 `SharpDevelop.exe` 所在目录就是 HintPath 前缀(安装布局固定为 `...\SharpDevelop\<版本>\bin\`)。仍找不到时问用户装在哪,不要瞎猜路径写进 csproj。
## 二、控件速查(详见 references/components.md;标准控件见 winforms-controls.md)
| 控件 | 类型全名(命名空间 Smart.CustomComponents) | 核心属性 | 生成代码注意 |
|---|---|---|---|
| 停靠面板 DockSurface | DockSurface : DockPanel | DockTheme、DockWindows 集合、LayoutFileName | Content 集合 + 三文件生成(见 codegen.md) |
| 圆角按钮 RoundedButton | RoundedButton : Control | Style(8 种配色)、Radius、三态色、Border | 枚举序列化用英文名 |
| 图片按钮 ImageButton | ImageButton : Control | **属性名就是中文**:图片路径/图片缩放/图文布局… | 生成代码直接写中文标识符 |
| 侧边菜单 SideMenuPanel | SideMenuPanel : UserControl | MenuItems、Pages、菜单宽度/行高/配色 10 项 | 两个 Content 集合,页面走 sideMenuPageN 字段 |
| 功能区 RibbonStrip | RibbonStrip : UserControl | Tabs→Groups→Buttons 三层集合、AccentColor 等 4 色、ActiveTabIndex | 图标走 `RibbonButton.FromFile("路径")`;点击统一 ButtonClick(e.Tab/e.Group/e.Button) |
| 增强数据表格 EnhancedDataGridView | EnhancedDataGridView : DataGridView | EnableExcelStyleSelection、Sqlite 三件套、EnableCellPaste | 列走标准 DataGridView Columns 序列化 |
| 多选下拉框 MultiSelectComboBox | MultiSelectComboBox : Control | Items、MultiSelect、Searchable、AllowCustomInput、Token 配色 | Items 是 Content 字符串集合 |
| 可调高下拉框 ResizableComboBox | ResizableComboBox : Control | Items、SelectedIndex、Flat、箭头/边框配色 | SelectedText 不序列化 |
| 可调高文本框 ResizableTextBox | ResizableTextBox : Control | PlaceholderText、Flat、三态边框色、密码字符 | 高度自由(这是它的存在意义) |
| OK/NG 状态灯 OKNGStatusControl | OKNGStatusControl : Control | IsOK、BindVariable | **绝不写 Text**(自绘覆盖) |
| 变量显示标签 VariableDisplayLabel | VariableDisplayLabel : Control | BindVariable、DisplayValue、TextAlign | 只读,事件 ValueChanged |
| 变量编辑框 VariableEditTextBox | VariableEditTextBox : TextBox | BindVariable(Value=Text) | 即 TextBox,仅多绑定属性 |
| 日志记录器 Logger(非可视) | Logger : Component | 日志文件名/日志级别/按天滚动/最多保留份数 | log4net 后端;代码调 写信息/写警告/写错误/写异常;详见 components.md 第 12 节 |
标准控件最常用的"总是写/绝不写"清单(完整规则在 winforms-controls.md):Label 的 `AutoSize = true`、CheckBox 与 TabPage 的 `UseVisualStyleBackColor = true` 总是写;DateTimePicker 的 Value、Timer 的 Enabled、各对话框的运行时结果绝不写。
## 三、代码生成五条铁律
1. **只序列化非默认值**。属性表里给了每个属性的默认值——与默认相同就不写进 Designer.cs(SharpDevelop 序列化器行为,手写也要遵守,否则设计器重载后会"多出"赋值行)。
2. **枚举一律用英文标识符**(属性网格显示的中文来自 TypeConverter,`ChineseEnumConverter.ConvertTo` 只管显示;`EnumCodeDomSerializer` 序列化走原始名)。例:`this.roundedButton1.Style = Smart.CustomComponents.RoundedButtonStyle.Success;` 唯一例外是 ImageButton——它的属性/枚举**本身就是中文标识符**(`图文布局.图左文右`)。
3. **Content 集合**(MenuItems/Pages/Items/DockWindows)逐条目生成:`new` 条目 → 赋非默认属性 → `父.集合.Add(条目临时变量)`。标了 `Hidden/Browsable(false)` 的属性(PersistString、ContentXml、ColumnsXml、SourceFile、Selected* 等)**绝不写**。
4. **事件**在属性赋值之后、`Controls.Add` 之前挂:`this.roundedButton1.Click += new System.EventHandler(this.roundedButton1_Click);`
5. **颜色属性带 ShouldSerialize 默认值**(见属性表"序列化条件"列),与出厂色相同则省略。
## 四、排错速查
| 症状 | 根因 | 处置 |
|---|---|---|
| **RibbonStrip 分组名只显示半个字**(下半截被裁,成套报价软件案例 2026-09-01) | 旧版控件布局是固定像素(分组名带 18px/选项卡条 26px/大按钮文字带 20px,按 96dpi 宋体 12px 调的);项目给功能区设了高字体(如微软雅黑 9F,字高~17px)装不下,TextRenderer 裁掉下半截 | **控件已根治**(09-01 21:54 起自适应字体高度)。老症状=项目在用旧 DLL:把项目 Smart.CustomComponents.dll 升到 21:56+(HintPath 指仓库 bin 或新 MSI 安装目录),**项目重编一次**拉新拷贝 |
| **RibbonStrip 大按钮文字显示不全**(截成省略号,同案例 2026-09-01) | 旧版大按钮宽度写死 58px,4+ 汉字按钮被 EndEllipsis 截断(小按钮一直是动态宽,大按钮漏了) | **控件已根治**(09-01 21:56 起按文字实测宽度 `max(58, 文字宽+12)`)。处置同上:升级 DLL + 项目重编 |
| 设计器抛 `MissingMethodException`:未找到方法 `System.Windows.Forms.Form.ConfigurePage`,窗体全不显示(通用规则,H1 为案例) | **当前用户项目自己的** `MainForm.Designer.cs` 在 `InitializeComponent()` 中调用了设计器无法处理的自定义辅助方法;这不是修改 SharpDevelop 本身,也不是修改设计器配置。SharpDevelop CodeDom 反序列化把它错误当成基类 Form 方法解析 | 对任何项目都只改该项目自己的 Designer.cs:删除 `ConfigurePage(...)` 调用和方法定义,展开为标准 `page.BackColor`/`Dock`/`MenuKey`/`Name` 属性赋值;Designer.cs 只保留标准 CodeDom 语句,辅助方法只能放该项目 MainForm.cs 的运行时代码。重新编译项目后**完全退出 SharpDevelop 再重新打开项目**,清除旧异常缓存 |
| 设计器抛 `CodeDomSerializerException`:"XX 没有名为 YY 的属性",窗体全不显示(s23 案例) | Designer.cs 写了该控件没有的属性(跨控件抄属性);反序列化遇未知属性即中止整个加载 | 对照 components.md 该控件的白名单删掉错行;删完**完全退出重启 IDE**(设计器 AppDomain 缓存旧异常,不重启继续报) |
| 构建报 MSB3644"找不到 v4.8 参考程序集"+ 一串 MSB3247 版本冲突;设计器偶发无输出(s23 案例) | 系统只装了 4.8.1 Developer Pack,`Reference Assemblies\...\.NETFramework\v4.8` 目录为空,MSBuild 只能从 GAC 捞到 v2.0/v4.0 混解析 | 装 .NET 4.8 Developer Pack 离线包(NDP48-DevPack-ENU.exe 约 140MB,静默装);装完 v4.8 目录 133 个参考 DLL,MSB3644/MSB3247 一起消失 |
| **AI 生成项目后设计区空白/一片 CS0246**(jk55 案例) | Designer.cs 用了增强控件但 csproj 无程序集引用;设计器加载第一步类型解析就失败,"自动补引用"跑在加载流程内部永远不触发——死锁:引用缺失→加载失败→自动补不触发→引用仍缺失 | **同一次改动里手动把 9 个引用写进 csproj**(清单见第一章),HintPath 指向安装目录;写完再开设计视图即正常。自动补引用只在工具箱拖放场景可用 |
| 自动补引用兜底后仍剩个别 CS0246(RibbonStrip/Logger 认不出) | 安装目录 `C:\Program Files (x86)\SharpDevelop\5.2\bin` 的 DLL 是旧构建(08-27 包缺这两个类型,13 控件只认 11) | **重打 MSI 重装**(或把仓库 bin 最新 DLL 覆盖安装目录),让稳定路径带全 13 控件;开发机可临时把 HintPath 指仓库 bin 过渡 |
| 设计器载入 "Could not find type '?'" | 项目引用解析不到(裸引用无 HintPath) | 08-25 13:53 及以后的 MSI 已在引用解析层中心兜底(自动回退到安装 bin);旧包则补 HintPath |
| 运行时 "DockPanel.Theme must be set to a valid theme" | 缺二级依赖链(Resources.Extensions 等 4 个) | 13:53+ 的库带 AssemblyResolve 运行时兜底;或按第一节补全 8 个引用。诊断看 `bin\Debug\DockWindows.Log.txt` |
| 运行时菜单重复/集合翻倍 | 设计期默认内容放进了构造函数 | 默认集合内容只能在 Designer.Initialize 且 `!host.Loading` 时注入(SideMenuPanel 已修,新控件照此办理) |
| 自定义集合编辑器改了不保存 | 原地改集合没发 IComponentChangeService 通知 | 编辑器写回前后发 OnComponentChanging/Changed |
| CellStyle Builder/列编辑器等框架对话框全英文 | .NET Framework 中文语言包未装(GAC 无 System.Design.resources zh-Hans) | 装 .NET 4.8 简体中文语言包(fwlink 2053984,`/q /norestart`),一次修复所有控件的框架编辑器**外壳**(标题/按钮) |
| 对话框外壳已中文但**内部属性行**仍英文 | 内部 PropertyGrid 的属性行走翻译层词典;`DataGridViewCellStyle` 不是 Component,单独注册 | DesignerTranslation.Install() 已为 DataGridViewCellStyle 补挂类型级提供器;缺行名就往词典加一条(如 SortMode→排序模式) |
| 改 CoreProperties.UILanguage 为 zh-CN 后整个 IDE 变英文 | SD 自家资源只有中性 zh 命名,具体文化不被识别回落 en | 保持 UILanguage=zh;用 ResourceService 里 IsNeutralCulture→CreateSpecificCulture 升格线程文化的代码补丁(勿动配置) |
| 属性面板改列标题高度模式后不生效/被顶回 | Designer.cs 残留显式模式行 + 引用指向旧版库 DLL | 删掉 Designer.cs 中该行;确认项目 HintPath 指向当前编译产物;EDG.Ctor.Log.txt 有"谁改的模式+调用栈" |
诊断优先级(用户要求):**读日志文件**(DockWindows.Log.txt / EDG.Ctor.Log.txt / DesignerTranslation.log),截图识别是最后手段。
## 五、Smart.CustomComponents 控件库修复历史速查(判断"项目是不是在用旧 DLL 复现旧 bug")
| 日期 | 修复 | 载体与判定 |
|---|---|---|
| 09-01 21:54 | RibbonStrip 带区高度自适应字体(分组名带 max(18,字高+4)、选项卡条、大按钮文字带;OnFontChanged 重画)——修"分组名只显示半个字" | 仓库 bin 与 21:54+ 编译的 DLL 均含;安装 MSI 13:14 版**不含** |
| 09-01 21:56 | RibbonStrip 大按钮宽度按文字实测 max(58, 文字宽+12)——修"按钮文字截成省略号" | 同上;判定项目是否吃到:看项目 `bin\Debug\Smart.CustomComponents.dll` 时间戳 ≥ 21:56 |
| 09-01 00:01 | SkillFolderSync(新建解决方案自动复制技能手册) | ICSharpCode.SharpDevelop.dll;13:14 MSI 已含 |
| 08-31 | 翻译词典收录 RibbonStrip→"增强选项卡"等全部工具箱中文名 | FormsDesigner.dll;13:14 MSI 已含 |
| 08-25 13:53 | 裸引用解析兜底、主题链 AssemblyResolve 运行时兜底 | 详见各排错行 |
控件库再修 bug 时:往这张表加一行,并提醒用户项目重编(零章第 7 条)。