---
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. **新窗口开发前必须全面规划，确保 SD 设计器可打开可编辑（用户强制 2026-10-01）**：每个新窗口的开发需求，动手写代码前必须先产出规划，规划内容详细到能直接指导后续设计与开发。规划至少包含四块：
   - **控件规划**：窗口内所有控件的类型选择（增强组件/标准控件，对照本手册属性白名单）、命名、布局设计（Location/Size/Dock/Anchor/分组）、属性配置（只写非默认值）；
   - **交互逻辑**：各控件之间的联动关系、事件挂接、状态流转；
   - **依赖清单**：所需引用的资源文件（图标/图片/resx）、组件库与依赖程序集（Designer.cs 用到增强控件时，同一次改动先写 csproj 引用，见第 3 条）；
   - **数据接口**：窗口与其他系统模块（主窗口/数据库/停靠布局/外部进程）的数据交互方式与调用入口。
   窗口一律采用双文件结构：`窗口名.Designer.cs`（纯布局与属性，SD 设计器能正确打开并继续编辑微调）+ `窗口名.cs`（交互逻辑与业务代码），Designer.cs 里绝不写业务代码；窗口文件记得同步注册进 csproj（Compile Include + Designer.cs 加 `<DependentUpon>`）。
7. **版本号铁律（用户强制 2026-10-01）：每次发版必须递增版本号**。每次打安装包/发 Gitea Release 前，必须先跑 `tools\递增版本号.ps1`（默认修订号 +1，如 1.0.3→1.0.4；大改动可传参指定如 1.1.0）。规则：
   - **唯一事实源** = `成套报价软件\Properties\AssemblyInfo.cs` 的 `AssemblyVersion`（固定三段式 `主.次.修订.0`，**禁用 `1.0.*` 自动号**——每次编译都变，无法对应发布的安装包）；
   - 「关于软件」窗口运行时自动读程序集版本显示（不在 Designer 写死）；
   - `release\成套报价软件\setup.iss` 的 `AppVersion` 与 `OutputBaseFilename=成套报价软件_Setup_版本` 由脚本同步；
   - Gitea Release 的 tag 与版本号一致（如 `v1.0.4`）；
   - 发版链固定为：递增版本号 → 编译 → make_package → ISCC → 更新包 → git 提交推送 → Release。跳过递增 = 两个不同功能的安装包同版本号，用户分不清、回滚排障全乱。

## 一、项目前提（缺一不可）

用这些控件的用户项目必须是：

```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 默认值**（见属性表"序列化条件"列），与出厂色相同则省略。

## 四、排错速查

| 症状 | 根因 | 处置 |
|---|---|---|
| 设计器抛 `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），截图识别是最后手段。