基线:全量源码首提(D1 版本控制落地,含第一轮优化 B1-B4/A1/A4/缩放修复)

2026-10-01 22:15:22 +08:00
commit 1e65792b09
499 changed files with 204579 additions and 0 deletions
@@ -0,0 +1,166 @@
+---
+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 条）。
@@ -0,0 +1,20 @@
+@echo off
+rem Copy the sd-enhanced-components skill into a solution folder.
+rem Usage: copy-to-solution.cmd <solution-dir>
+setlocal
+set "SKILL_DIR=%~dp0"
+if "%~1"=="" (
+    echo Usage: %~nx0 ^<solution-dir^>
+    echo Example: %~nx0 "F:\pycode\wpf\src\WinFormsDesigner.Fx48\Samples\COOO\scr\MyApp"
+    exit /b 1
+)
+if not exist "%~1" (
+    echo ERROR: directory not found: %~1
+    exit /b 1
+)
+set "DEST=%~1\.agents\skills\sd-enhanced-components"
+xcopy "%SKILL_DIR%SKILL.md" "%DEST%\" /Y /I >nul
+xcopy "%SKILL_DIR%references" "%DEST%\references\" /Y /E /I >nul
+echo Copied skill to: %DEST%
+echo Files: SKILL.md + references ^(components / winforms-controls / winforms-components / codegen^)
+endlocal
@@ -0,0 +1,394 @@
+# Designer.cs 代码生成规则（SharpDevelop CodeDom 序列化风格）
+
+对应实现：SharpDevelop NRefactoryDesignerLoader 序列化 + `Commands/GenerateDockWindows.cs` 生成器。缩进用 **Tab**，语句带 `this.`，非 System 类型用全名。
+
+## 0. 目标窗体约定（用户强制）
+
+- 生成/手写 Designer.cs 的目标永远是解决方案**自带主窗口 MainForm**（MainForm.Designer.cs），事件运行时代码放 MainForm.cs；**绝不新建第二个窗体承载 UI**（TestForm/Form2 之类只在该项目本身就是测试工具时才允许）。
+- **写 Designer.cs 前先补引用，否则设计器死锁**（jk55 案例）：设计器加载第一步是类型解析，项目没引用增强控件程序集就直接一片 CS0246；而"切设计标签自动补引用"的代码跑在设计器加载流程**内部**，类型解析不过它永远不执行——引用缺失→加载失败→自动补不触发→引用仍缺失。**AI 生成 Designer.cs 的同一次改动必须先写 §0.1 的 9 个引用。** 工具箱拖放场景不受影响（那时设计器本来就能加载）。
+
+### 0.1 增强控件引用九件套（写 Designer.cs 时同步写进 csproj）
+
+HintPath **默认指向 SharpDevelop 安装目录** `C:\Program Files (x86)\SharpDevelop\5.2\bin`：装完即存在、机器间一致（工具箱自动补引用与引用解析兜底用的同一规范位置）。三条变通：
+
+- **装在非默认位置**：先用下面的命令找到真实安装 bin，把 9 个 HintPath 整体替换成实际路径（注册表卸载键 InstallLocation 为空，别用它）：
+  ```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'
+  ```
+  都找不到就问用户，不要瞎猜路径。完整说明见 SKILL.md 第一章"定位实际安装目录"。
+- **开发机临时追新**：仓库 bin `F:\Visual Studio\1\33\SharpDevelop-master\bin` 有最新控件时可把 HintPath 临时换成它，但该路径仅本机存在，**交付/给用户机的模板一律用安装目录**。
+- **前提：安装目录必须是最新构建**。jk55 案例发现 08-27 旧安装包缺 RibbonStrip/Logger（13 控件只认 11）——先重打 MSI 重装，或把仓库 bin 最新 DLL 覆盖到安装目录。
+
+```xml
+<ItemGroup>
+  <Reference Include="Smart.CustomComponents, Version=1.0.0.0, Culture=neutral, PublicKeyToken=ba044a4aa43e0dc4">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\Smart.CustomComponents.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="WeifenLuo.WinFormsUI.Docking">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\WeifenLuo.WinFormsUI.Docking.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="WeifenLuo.WinFormsUI.Docking.ThemeVS2015">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\WeifenLuo.WinFormsUI.Docking.ThemeVS2015.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="System.Data.SQLite">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\System.Data.SQLite.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="log4net">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\log4net.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="System.Resources.Extensions">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\System.Resources.Extensions.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="System.Memory">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\System.Memory.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="System.Runtime.CompilerServices.Unsafe">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\System.Runtime.CompilerServices.Unsafe.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+  <Reference Include="System.Numerics.Vectors">
+    <HintPath>C:\Program Files (x86)\SharpDevelop\5.2\bin\System.Numerics.Vectors.dll</HintPath>
+    <Private>True</Private>
+  </Reference>
+</ItemGroup>
+```
+
+`<Private>True</Private>` 会在编译时把 DLL 复制进项目 `bin\Debug`，之后项目运行/分发不再依赖 HintPath 原位置（换机器、重装 SharpDevelop 都不受影响）。
+
+## 1. 标准骨架（单控件）
+
+```csharp
+namespace DemoApp
+{
+	partial class MainForm
+	{
+		private System.ComponentModel.IContainer components = null;
+		private Smart.CustomComponents.RoundedButton roundedButton1;
+
+		protected override void Dispose(bool disposing)
+		{
+			if (disposing && (components != null)) components.Dispose();
+			base.Dispose(disposing);
+		}
+
+		private void InitializeComponent()
+		{
+			this.roundedButton1 = new Smart.CustomComponents.RoundedButton();
+			this.SuspendLayout();
+			//
+			// roundedButton1
+			//
+			this.roundedButton1.Location = new System.Drawing.Point(40, 60);
+			this.roundedButton1.Name = "roundedButton1";
+			this.roundedButton1.Radius = 20;
+			this.roundedButton1.Size = new System.Drawing.Size(140, 44);
+			this.roundedButton1.Style = Smart.CustomComponents.RoundedButtonStyle.Success;
+			this.roundedButton1.TabIndex = 0;
+			this.roundedButton1.Text = "保存";
+			this.roundedButton1.Click += new System.EventHandler(this.roundedButton1_Click);
+			//
+			// MainForm
+			//
+			this.AutoScaleDimensions = new System.Drawing.SizeF(6F, 12F);
+			this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
+			this.ClientSize = new System.Drawing.Size(784, 561);
+			this.Controls.Add(this.roundedButton1);
+			this.Name = "MainForm";
+			this.Text = "DemoApp";
+			this.ResumeLayout(false);
+		}
+	}
+}
+```
+
+规则：每个控件一段注释头；Location/Name/Size/TabIndex 总是写；其余属性只写**非默认值**（对照 components.md 表）；事件在属性后、Controls.Add 前；容器结尾 `ResumeLayout(false)`，有子布局的控件加 `PerformLayout()` 对。
+
+## 2. Content 集合生成
+
+### 2.1 字符串项集合（MultiSelectComboBox.Items / ResizableComboBox.Items）
+
+```csharp
+this.multiSelectComboBox1.Items.Add("选项A");
+this.multiSelectComboBox1.Items.Add("选项B");
+```
+
+### 2.2 递归对象集合（SideMenuPanel.MenuItems，条目有 Children）
+
+```csharp
+Smart.CustomComponents.SideMenuItem sideMenuItem1 = new Smart.CustomComponents.SideMenuItem();
+sideMenuItem1.Text = "首页";
+Smart.CustomComponents.SideMenuItem sideMenuItem2 = new Smart.CustomComponents.SideMenuItem();
+sideMenuItem2.Text = "数据管理";
+Smart.CustomComponents.SideMenuItem sideMenuItem3 = new Smart.CustomComponents.SideMenuItem();
+sideMenuItem3.Text = "导出记录";
+sideMenuItem2.Children.Add(sideMenuItem3);
+this.sideMenuPanel1.MenuItems.Add(sideMenuItem1);
+this.sideMenuPanel1.MenuItems.Add(sideMenuItem2);
+```
+
+### 2.3 页面集合（SideMenuPanel.Pages）
+
+页面是 Panel 派生 → 走**字段**路径（设计器把页面注册进 IDesignerHost.Container，命名为 sideMenuPageN）：
+
+```csharp
+private Smart.CustomComponents.SideMenuPage sideMenuPage1;
+
+this.sideMenuPage1 = new Smart.CustomComponents.SideMenuPage();
+this.sideMenuPage1.BackColor = System.Drawing.Color.White;
+this.sideMenuPage1.Dock = System.Windows.Forms.DockStyle.Fill;
+this.sideMenuPage1.Location = ...;
+this.sideMenuPage1.MenuKey = "首页";
+this.sideMenuPage1.Name = "sidePage_首页";   // 用户可改
+this.sideMenuPanel1.Pages.Add(this.sideMenuPage1);
+```
+
+注意：页面一般由菜单自动同步生成（MenuKey=菜单文字）；手写时 MenuKey 必须与某菜单项 Text 匹配才会被点击切换。**页面内子控件用 EnableDesignMode 暴露，不要生成 `父.页面` 形式的点号字段名**（历史崩溃点：`sideMenuPanel1.Page_0_首页` 是非法 C# 字段名）。
+
+### 2.4 停靠窗口集合（DockSurface.DockWindows，DockWindowItem 条目）
+
+```csharp
+Smart.CustomComponents.DockWindows.DockWindowItem dockWindowItem1 = new Smart.CustomComponents.DockWindows.DockWindowItem();
+dockWindowItem1.ClassName = "ToolWindow";
+dockWindowItem1.Title = "工具箱";
+dockWindowItem1.DockState = WeifenLuo.WinFormsUI.Docking.DockState.DockLeft;
+dockWindowItem1.DefaultWidth = 240;
+dockWindowItem1.ShowCloseButton = false;
+this.dockSurface1.DockWindows.Add(dockWindowItem1);
+```
+
+只写非默认属性（DefaultHeight=180、FixedPosition=false、ShowCloseButton=true 是默认，省略）。
+
+### 2.5 功能区三层集合（RibbonStrip.Tabs → RibbonTab.Groups → RibbonGroup.Buttons → RibbonButton）
+
+```csharp
+Smart.CustomComponents.RibbonTab ribbonTab1 = new Smart.CustomComponents.RibbonTab();
+ribbonTab1.Text = "开始";
+Smart.CustomComponents.RibbonGroup ribbonGroup1 = new Smart.CustomComponents.RibbonGroup();
+ribbonGroup1.Text = "文件";
+Smart.CustomComponents.RibbonButton ribbonButton1 = new Smart.CustomComponents.RibbonButton();
+ribbonButton1.Text = "打开";
+ribbonButton1.Image = Smart.CustomComponents.RibbonButton.FromFile("C:\\icons\\open.png");  // 有图标时
+ribbonButton1.Enabled = false;   // 非默认才写
+ribbonGroup1.Buttons.Add(ribbonButton1);
+ribbonTab1.Groups.Add(ribbonGroup1);
+this.ribbonStrip1.Tabs.Add(ribbonTab1);
+```
+
+规则：
+- 逐层 `new` → 赋非默认属性 → `Add` 进上一级集合；只写非默认（Text 无默认标记通常总写，SizeStyle=Small、Enabled=true 是默认省略）。
+- **图标**：`按钮.Image = RibbonButton.FromFile("路径")`（RibbonImageConverter 序列化形态；ImageFile 本身隐藏不写）。无图标则不写 Image 行。
+- 事件统一走一个 `this.ribbonStrip1.ButtonClick += new System.EventHandler<Smart.CustomComponents.RibbonButtonEventArgs>(this.ribbonStrip1_ButtonClick);`，处理器里按 `e.Button.Text` 分发（参数带 e.Tab/e.Group/e.Button）。
+- `this.ribbonStrip1.ActiveTabIndex = 0;` 是默认，省略。
+
+## 3. 停靠窗口三文件生成（等价"生成停靠窗口代码"命令）
+
+集合配置好后生成 3 类文件（幂等：窗口类已存在不覆盖，仅同步 Designer.cs 的 this.Text 行；partial 与构造函数接线按当前配置刷新）：
+
+### 3.1 窗口类 `DockWindows\<类名>\<类名>.cs`
+
+```csharp
+using System;
+using WeifenLuo.WinFormsUI.Docking;
+
+namespace DemoApp
+{
+	/// <summary>停靠窗口：工具箱。内容在本类的设计器视图中编辑。</summary>
+	public partial class ToolWindow : DockContent
+	{
+		public ToolWindow()
+		{
+			InitializeComponent();
+			Text = "工具箱";
+			TabText = "工具箱";
+		}
+	}
+}
+```
+
+### 3.2 窗口类设计器骨架 `DockWindows\<类名>\<类名>.Designer.cs`
+
+```csharp
+namespace DemoApp
+{
+	partial class ToolWindow
+	{
+		private System.ComponentModel.IContainer components = null;
+
+		protected override void Dispose(bool disposing)
+		{
+			if (disposing && (components != null)) components.Dispose();
+			base.Dispose(disposing);
+		}
+
+		#region Designer generated code
+
+		private void InitializeComponent()
+		{
+			this.SuspendLayout();
+			this.Name = "ToolWindow";
+			this.Text = "工具箱";
+			this.ResumeLayout(false);
+		}
+
+		#endregion
+	}
+}
+```
+
+（双击 .cs 可继续用 SharpDevelop 设计器往里拖控件，序列化规则同第 1、2 节。）
+
+### 3.3 创建/停靠 partial `DockWindows\<Form>.<surface>.DockWindows.cs`
+
+```csharp
+// 本文件由『生成停靠窗口代码』自动生成，集合变更后会自动刷新，请勿手工编辑。
+using System;
+using WeifenLuo.WinFormsUI.Docking;
+
+namespace DemoApp
+{
+	public partial class MainForm
+	{
+		void CreateDockWindows_dockSurface1()
+		{
+			var dockSurface1 = this.dockSurface1 as Smart.CustomComponents.DockSurface;
+			if (dockSurface1 == null) return;
+			dockSurface1.EnsureDefaultTheme();     // 必须：Show 前保证有效主题
+			var w1 = new ToolWindow();
+			w1.CloseButtonVisible = false;          // 仅 ShowCloseButton=false 时生成
+			w1.DockAreas = WeifenLuo.WinFormsUI.Docking.DockAreas.DockLeft; // 仅 FixedPosition=true 时
+			w1.TabText = "工具箱";                  // Title 非空时生成
+			w1.Text = "工具箱";
+			w1.Show(dockSurface1, DockState.DockLeft);
+			var w2 = new FloatWindow2();
+			w2.Size = new System.Drawing.Size(320, 240);   // 仅 DockState.Float 时
+			w2.Show(dockSurface1, DockState.Float);
+		}
+	}
+}
+```
+
+属性设置**必须在 Show 之前**。FixedPosition 的 DockAreas 映射：
+
+| DockState | DockAreas |
+|---|---|
+| DockLeft / DockLeftAutoHide | DockLeft |
+| DockRight / DockRightAutoHide | DockRight |
+| DockTop / DockTopAutoHide | DockTop |
+| DockBottom / DockBottomAutoHide | DockBottom |
+| Document | Document |
+| Float | Float |
+| Hidden / Unknown | 不锁定（不生成 DockAreas 行） |
+
+### 3.4 构造函数接线（MainForm.cs）
+
+`InitializeComponent();` 之后插入（已存在则跳过）：
+
+```csharp
+InitializeComponent();
+CreateDockWindows_dockSurface1();
+```
+
+自动触发链：集合编辑器"确定" → IComponentChangeService.OnComponentChanged → 400ms 防抖静默生成。多面板时每个 DockSurface 各一个 `CreateDockWindows_<面板名>` 方法。
+
+## 4. 特殊控件生成注意
+
+- **Designer.cs 只能写标准 Designer 语句（适用于所有项目；H1 是已验证案例）**：`InitializeComponent()` 内只允许 `new`、属性赋值、集合 `Add/AddRange`、事件挂接和 `Controls.Add` 等标准 CodeDom 语句。**不要调用自定义辅助方法**（例如 `ConfigurePage(this.overviewPage, "概览", "sidePage_Overview")`）：SharpDevelop 反序列化时可能把它错误解析成 `System.Windows.Forms.Form.ConfigurePage(...)`，继而抛 `MissingMethodException`（未找到方法 `System.Windows.Forms.Form.ConfigurePage`），整个设计器加载中止。页面配置必须展开成标准属性赋值：`page.BackColor`、`page.Dock`、`page.MenuKey`、`page.Name` 等；辅助方法放到 MainForm.cs 的运行时代码中，或不要使用。
+  **边界说明（适用于所有项目）**：此修复只修改**用户项目自己的** `MainForm.Designer.cs`：删除 `ConfigurePage(...)` 调用和 Designer 文件末尾的方法定义，重新编译项目（如生成 `<项目>\bin\Debug\<项目>.exe`）；没有修改 SharpDevelop 本身，也没有修改任何设计器配置。若当前 SharpDevelop 进程已经缓存旧的加载异常，修复后自动完全退出 SharpDevelop、重新打开项目再进设计器（这是清缓存，不是因为修改了 SharpDevelop）。
+- **属性白名单铁律（s23 案例 2026-09-01）**：Designer.cs 里写的每个属性必须能在 components.md 该控件条目下查到（自有属性表或继承属性行）。**跨控件抄属性是头号翻车点**——写一个该控件没有的属性，CodeDom 反序列化直接抛 `CodeDomSerializerException`（"XX 没有名为 YY 的属性"），**整个设计器加载中止**、窗体全黑。已知最易抄错的两对：
+  - `VariableEditTextBox` **没有 PlaceholderText**（那是 ResizableTextBox 的；它继承 TextBox，自有属性只有 BindVariable/Value，要占位提示就用 ResizableTextBox）；
+  - `VariableDisplayLabel` **没有 BorderStyle**（它继承 Control 不是 Label，自有属性只有 BindVariable/DisplayValue/TextAlign）。
+- **ImageButton**：属性名/枚举是中文标识符，直接写：`this.imageButton1.图文布局 = Smart.CustomComponents.图文布局枚举.图左文右;`
+- **OKNGStatusControl**：不写 Text（自绘 OK/NG）；IsOK=true 默认省略。
+- **EnhancedDataGridView**：列与普通 DataGridView 相同（`this.enhancedDataGridView1.Columns.AddRange(new System.Windows.Forms.DataGridViewColumn[] {...})` + 每列独立字段段）；Sqlite 三属性按字符串直写。
+- **事件处理器签名**：`private void roundedButton1_Click(object sender, EventArgs e)`，写在主 .cs 文件（不放 Designer.cs）。
+- **图片属性**（SideMenuItem.Icon、Image 类型）：走 .resx 资源（`System.ComponentModel.ComponentResourceManager resources = new ...typeof(MainForm));` + `resources.GetObject("$this.sideMenuItem1.Icon")`），SharpDevelop 风格同 WinForms。
+
+## 5. 生成的运行时诊断（生成器自带，勿删）
+
+partial 里附带了写 `bin\Debug\DockWindows.Log.txt` 的日志：主题类型/页签条/补丁重载数 + 每窗口 Show 前后的 CloseButtonVisible/DockAreas/DockState/TabText。排错时**先读这个文件**（用户要求：日志优先，截图最后）。
+
+## 6. 非可视组件模板
+
+属性表见 `winforms-components.md`。要点：无 Location/Size/TabIndex；构造带 IContainer 的（Timer/ImageList/ErrorProvider/ToolTip/BindingSource/NotifyIcon/HelpProvider/BackgroundWorker/SerialPort）写 `new ...(this.components)` 且不再 Add；不带的（PrintDocument/Process/EventLog/FileSystemWatcher/PerformanceCounter）用 `this.components.Add(this.xxx);`；DataSet/BindingSource 用 ISupportInitialize 的 BeginInit/EndInit 包裹。扩展提供器（ToolTip/ErrorProvider/HelpProvider）对其他控件逐行 `SetXxx(目标控件, 值)`。
+
+## 7. 菜单/工具栏嵌套模板（每个菜单项/工具栏项都是字段）
+
+```csharp
+private System.Windows.Forms.MenuStrip menuStrip1;
+private System.Windows.Forms.ToolStripMenuItem 文件ToolStripMenuItem;
+private System.Windows.Forms.ToolStripMenuItem 退出ToolStripMenuItem;
+
+this.menuStrip1 = new System.Windows.Forms.MenuStrip();
+this.文件ToolStripMenuItem = new System.Windows.Forms.ToolStripMenuItem();
+this.退出ToolStripMenuItem = new System.Windows.Forms.ToolStripMenuItem();
+//
+// 退出ToolStripMenuItem
+//
+this.退出ToolStripMenuItem.Name = "退出ToolStripMenuItem";
+this.退出ToolStripMenuItem.Size = new System.Drawing.Size(180, 22);   // 布局值，设计器会写
+this.退出ToolStripMenuItem.Text = "退出";
+this.退出ToolStripMenuItem.Click += new System.EventHandler(this.退出ToolStripMenuItem_Click);
+//
+// 文件ToolStripMenuItem
+//
+this.文件ToolStripMenuItem.DropDownItems.AddRange(new System.Windows.Forms.ToolStripItem[] {
+	this.退出ToolStripMenuItem});
+this.文件ToolStripMenuItem.Text = "文件";
+//
+// menuStrip1
+//
+this.menuStrip1.Items.AddRange(new System.Windows.Forms.ToolStripItem[] {
+	this.文件ToolStripMenuItem});
+this.menuStrip1.Location = new System.Drawing.Point(0, 0);
+this.menuStrip1.Name = "menuStrip1";
+this.menuStrip1.Size = ...; this.menuStrip1.TabIndex = ...;
+this.menuStrip1.Text = "menuStrip1";
+// 窗体段：
+this.MainMenuStrip = this.menuStrip1;
+this.Controls.Add(this.menuStrip1);
+```
+
+ContextMenuStrip 同构（无 Dock、无 MainMenuStrip 行）；StatusStrip 用 ToolStripStatusLabel（Spring=true 占满 + BorderSide 等）；ToolStrip 混用 ToolStripButton/ToolStripSeparator/ToolStripTextBox…，均独立字段。MenuStrip/ToolStrip 的 Items 段**不写每项 Name 之外的 Text 之外的默认值**；`DropDownItems.AddRange` 表示层级。
+
+## 8. ListView / TreeView 集合模板
+
+```csharp
+// ListView：列为字段，行可 ctor 一行带上
+this.columnHeader1 = new System.Windows.Forms.ColumnHeader();
+this.columnHeader1.Text = "姓名"; this.columnHeader1.Width = 120;
+this.columnHeader2 = new System.Windows.Forms.ColumnHeader();
+this.columnHeader2.Text = "分数";
+this.listView1.Columns.AddRange(new System.Windows.Forms.ColumnHeader[] {
+	this.columnHeader1, this.columnHeader2});
+this.listView1.FullRowSelect = true;      // View=Details 时常用组合
+this.listView1.View = System.Windows.Forms.View.Details;
+this.listView1.Items.AddRange(new System.Windows.Forms.ListViewItem[] {
+	new System.Windows.Forms.ListViewItem(new string[] {"张三", "95"}),
+	new System.Windows.Forms.ListViewItem(new string[] {"李四", "88"})});
+// 分组（可选）
+this.listViewGroup1 = new System.Windows.Forms.ListViewGroup("一组");
+this.listView1.Groups.AddRange(new System.Windows.Forms.ListViewGroup[] {this.listViewGroup1});
+
+// TreeView：节点递归，ctor 带文本
+System.Windows.Forms.TreeNode treeNode1 = new System.Windows.Forms.TreeNode("根节点");
+System.Windows.Forms.TreeNode treeNode2 = new System.Windows.Forms.TreeNode("子节点1");
+System.Windows.Forms.TreeNode treeNode3 = new System.Windows.Forms.TreeNode(new string[] {
+	"子节点1", "子节点2"});   // 兄弟数组写法（Name1,Name2 平铺）
+treeNode1.Nodes.AddRange(new System.Windows.Forms.TreeNode[] {treeNode3});
+this.treeView1.Nodes.AddRange(new System.Windows.Forms.TreeNode[] {treeNode1});
+```
+
+TreeView 的 designer 实际写法是临时变量 treeNodeN 逐级挂 Nodes.AddRange；ImageKey/SelectedImageKey 在绑定 ImageList 后写。
@@ -0,0 +1,593 @@
+# 增强组件属性手册（Smart.CustomComponents 全部 13 控件 + 条目类型 + 枚举，穷尽版）
+
+> 生成来源：反射 `Smart.CustomComponents.dll`（bin\Debug 编译产物）+ 源码逐文件核对（src\Libraries\CustomComponents\Controls）。属性名/类型/默认值以 DLL 与源码为准。
+> 工具箱类别：**增强组件**（13 个控件）。Designer.cs 代码生成规则另见 `codegen.md`。
+> 序列化列约定：**Content 集合**=逐条目生成；不序列化=设计器/手写都不写；非默认才写=与默认值相同则省略；ShouldSerialize=与出厂值比较不同才写。
+
+## 目录
+- 停靠面板 DockSurface（WeifenLuo.WinFormsUI.Docking.DockPanel）
+- 圆角按钮 RoundedButton（System.Windows.Forms.Control）
+- 图片按钮 ImageButton（System.Windows.Forms.Control）
+- 增强数据表格 EnhancedDataGridView（System.Windows.Forms.DataGridView）
+- 多选下拉框 MultiSelectComboBox（System.Windows.Forms.Control）
+- 可调高下拉框 ResizableComboBox（System.Windows.Forms.Control）
+- 可调高文本框 ResizableTextBox（System.Windows.Forms.Control）
+- OK/NG 状态灯 OKNGStatusControl（System.Windows.Forms.Control）
+- 侧边菜单 SideMenuPanel（System.Windows.Forms.UserControl）
+- 功能区 RibbonStrip（System.Windows.Forms.UserControl）
+- 变量显示标签 VariableDisplayLabel（System.Windows.Forms.Control）
+- 变量编辑框 VariableEditTextBox（System.Windows.Forms.TextBox）
+- 日志记录器 Logger（非可视组件）（System.ComponentModel.Component）
+
+---
+
+## 停靠面板 DockSurface
+
+**继承**：`Smart.CustomComponents.DockSurface` ← `WeifenLuo.WinFormsUI.Docking.DockPanel`
+
+停靠窗口宿主容器。设计器拖入窗体后通过 DockWindows 集合声明若干停靠窗口，用"生成停靠窗口代码"（等价手写三文件）生成窗口类。主题=VS2015Light 起步。
+
+### 属性（全部 4 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| DockTheme | SurfaceTheme | VS2015Light | 非默认才写 | 停靠主题；Designer.cs 生成配套 Theme 对象（VS2015Light→ThemeVS2015Light），改主题须同步改引用的 Theme 程序集 |
+| TabDirection | TabTipDirection | Left | 非默认才写 | 选项卡提示方向（左/右），少量布局场景才改 |
+| DockWindows | DockWindowItemCollection |  | **Content 集合** | 停靠窗口声明集合，条目类型 DockWindowItem；生成走"三文件流程"（codegen.md §3） |
+| LayoutFileName | String | dock_layout.xml | 非默认才写 | 运行时布局持久化 XML 文件名，相对 exe 目录 |
+
+### 继承属性（名称全列）
+
+- 继承 DockPanel（33 个）：DockBackColor, ActiveAutoHideContent, AllowEndUserDocking, AllowEndUserNestedDocking, Contents(RO), RightToLeftLayout, ShowDocumentIcon, DocumentTabStripLocation, Extender(RO), DockPaneFactory(RO), FloatWindowFactory(RO), DockWindowFactory(RO), Panes(RO), DockArea(RO), DockBottomPortion, DockLeftPortion, DockRightPortion, DockTopPortion, DockWindows(RO), DocumentsCount(RO), Documents(RO), FloatWindows(RO), DefaultFloatWindowSize, DocumentStyle, SupportDeeplyNestedContent, ShowAutoHideContentOnHover, DocumentWindowBounds(RO), ActiveContent(RO), ActivePane(RO), ActiveDocument(RO), ActiveDocumentPane(RO), Skin(RO), Theme
+- 继承 Panel（5 个）：AutoSize, AutoSizeMode, BorderStyle, TabStop, Text
+- 继承 ScrollableControl（8 个）：AutoScroll, AutoScrollMargin, AutoScrollPosition, AutoScrollMinSize, DisplayRectangle(RO), HorizontalScroll(RO), VerticalScroll(RO), DockPadding(RO)
+- 继承 Control（70 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+自有事件：无（仅基类事件）。
+- 运行时错误 "DockPanel.Theme must be set to a valid theme" = 二级依赖链（System.Resources.Extensions 等 4 个）没引用全。
+- 诊断日志：bin\Debug\DockWindows.Log.txt。
+- API：EnsureDefaultTheme()（代码兜底挂主题）。
+- 不可当作普通 Control 用（没有 Size/Location 语义），占满窗体或容器使用。
+
+---
+
+## 圆角按钮 RoundedButton
+
+**继承**：`Smart.CustomComponents.RoundedButton` ← `System.Windows.Forms.Control`
+
+Element-UI 配色的圆角按钮，8 种风格预设 + 三态（常态/悬停/按下）颜色可覆写。点击用基类 Click 事件。
+
+### 属性（全部 9 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Style | RoundedButtonStyle | Primary | 非默认才写 | 风格预设 Primary/Success/Warning/Danger/Info/Dark/Light/Outline，Designer.cs 写英文名（如 RoundedButtonStyle.Success） |
+| Radius | Int32 | 10 | 非默认才写 | 圆角半径 px，0=直角 |
+| NormalColor | Color |  | — | 常态底色；出厂 24,144,255（随 Style 预设，ShouldSerialize 按出厂色比较） |
+| HoverColor | Color |  | — | 悬停底色；出厂 64,169,255 |
+| PressColor | Color |  | — | 按下底色；出厂 9,109,217 |
+| BorderWidth | Int32 | 0 | 非默认才写 | 边框宽 px，0=无边框（Outline 风格通常设 1~2） |
+| BorderColor | Color |  | — | 边框色；出厂 217,217,217 |
+| TextAlign | ContentAlignment | MiddleCenter | 非默认才写 | 文字对齐（ContentAlignment），默认 MiddleCenter |
+| BackColor | Color |  | 不序列化 | 被隐藏（自绘不用），绝不写 |
+
+### 继承属性（名称全列）
+
+- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Text, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+自有事件：无（仅基类事件）。
+- 三色只在改变出厂预设时序列化（ShouldSerialize 与出厂色比较）。
+- 改色想完整自定义时三态色都要写，避免悬停跳回蓝色。
+
+---
+
+## 图片按钮 ImageButton
+
+**继承**：`Smart.CustomComponents.ImageButton` ← `System.Windows.Forms.Control`
+
+图片+文字的按钮。**属性名与枚举值本身就是中文标识符**，Designer.cs 直接写中文（全项目唯一例外）。
+
+### 属性（全部 12 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| BackgroundImage | Image |  | 不序列化 |  |
+| BackgroundImageLayout | ImageLayout |  | 不序列化 |  |
+| BackColor | Color |  | 不序列化 |  |
+| 图片路径 | String |  | — | 图片文件绝对/相对路径；非空才序列化（ShouldSerialize图片路径） |
+| 图片缩放 | 图片缩放模式 | Fit | 非默认才写 | Original/Fit/Stretch/Tile，默认 Fit |
+| 图片锚点 | 图片锚点位置 | Center | 非默认才写 | Center/N/S/E/W，默认 Center |
+| 图片透明度 | Double | 1 | 非默认才写 | 0.0~1.0，默认 1 |
+| 图文布局 | 图文布局枚举 | 文字居中 | 非默认才写 | 文字居中/图下文上/图上文下/图右文左/图左文右/纯图片；枚举成员是中文 |
+| 文字间距 | Int32 | 1 | 非默认才写 | 图与文字间距 px，默认 1 |
+| Text | String |  | — | 按钮文字（类目 外观） |
+| Font | Font |  | — | 文字字体 |
+| ForeColor | Color |  | — | 文字颜色 |
+
+### 继承属性（名称全列）
+
+- 继承 Control（68 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+自有事件：无（仅基类事件）。
+- Designer.cs 示例：this.imageButton1.图文布局 = Smart.CustomComponents.图文布局枚举.图左文右;
+- 点击用基类 Click。
+
+---
+
+## 增强数据表格 EnhancedDataGridView
+
+**继承**：`Smart.CustomComponents.EnhancedDataGridView` ← `System.Windows.Forms.DataGridView`
+
+在标准 DataGridView 上增加：Excel 风格选择高亮、剪贴板多单元格粘贴、SQLite 三键绑定（x86 混合模式 System.Data.SQLite 1.0.119，无需 Interop.dll）。列仍用标准 Columns 序列化。
+
+### 属性（全部 9 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| EnableExcelStyleSelection | Boolean | True | 非默认才写 | 列头/行头点击整列整行高亮 + 框选区域高亮，默认开 |
+| EnableCellPaste | Boolean | False | 非默认才写 | 允许从 Excel 复制后粘贴多单元格，默认关 |
+| SqliteDatabasePath | String |  | — | SQLite 数据库文件路径（.db）；相对路径相对 exe |
+| SqliteQuery | String |  | — | 绑定用的 SELECT 查询语句 |
+| AutoBindSqliteOnLoad | Boolean | False | 非默认才写 | 窗体载入时自动执行 BindSqliteData() |
+| CreateTableButton | String |  | — | 设计时动作：属性面板点"…"按当前列生成建表 SQL/执行（值恒空，不序列化，绝不手写） |
+| BindDataButton | String |  | — | 设计时动作：点"…"立即按三件套绑定一次（值恒空，不序列化） |
+| ClearBindButton | String |  | — | 设计时动作：点"…"解除数据绑定（值恒空，不序列化） |
+| ColumnHeadersHeightSizeMode | DataGridViewColumnHeadersHeightSizeMode | EnableResizing | 非默认才写 | 遮蔽基类同名属性；默认 EnableResizing（表头可拖拽调高），与基类一致不用写 |
+
+### 继承属性（名称全列）
+
+- 继承 DataGridView（79 个）：AdjustedTopLeftHeaderBorderStyle(RO), AdvancedCellBorderStyle(RO), AdvancedColumnHeadersBorderStyle(RO), AdvancedRowHeadersBorderStyle(RO), AllowUserToAddRows, AllowUserToDeleteRows, AllowUserToOrderColumns, AllowUserToResizeColumns, AllowUserToResizeRows, AlternatingRowsDefaultCellStyle, AutoGenerateColumns, AutoSize, AutoSizeColumnsMode, AutoSizeRowsMode, BackColor, BackgroundColor, BackgroundImage, BackgroundImageLayout, BorderStyle, CellBorderStyle, ClipboardCopyMode, ColumnCount, ColumnHeadersBorderStyle, ColumnHeadersDefaultCellStyle, ColumnHeadersHeight, ColumnHeadersVisible, Columns(RO), CurrentCell, CurrentCellAddress(RO), CurrentRow(RO), DataMember, DataSource, DefaultCellStyle, DisplayRectangle(RO), EditMode, EditingControl(RO), EditingPanel(RO), EnableHeadersVisualStyles, FirstDisplayedCell, FirstDisplayedScrollingColumnHiddenWidth(RO), FirstDisplayedScrollingColumnIndex, FirstDisplayedScrollingRowIndex, ForeColor, Font, GridColor, HorizontalScrollingOffset, IsCurrentCellDirty(RO), IsCurrentCellInEditMode(RO), IsCurrentRowDirty(RO), MultiSelect, NewRowIndex(RO), Padding, ReadOnly, RowCount, RowHeadersBorderStyle, RowHeadersDefaultCellStyle, RowHeadersVisible, RowHeadersWidth, RowHeadersWidthSizeMode, Rows(RO), RowsDefaultCellStyle, RowTemplate, ScrollBars, SelectedCells(RO), SelectedColumns(RO), SelectedRows(RO), SelectionMode, ShowCellErrors, ShowCellToolTips, ShowEditingIcon, ShowRowErrors, SortedColumn(RO), SortOrder(RO), StandardTab, Text, TopLeftHeaderCell, UserSetCursor(RO), VerticalScrollingOffset(RO), VirtualMode
+- 继承 Control（65 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+自有事件：无（仅基类事件）。
+- API：BindSqliteData()（按三件套绑定）；CreateSqliteTableFromColumns(dbPath, tableName, dropIfExists)（按列建表，返回 SQL）；PreviewCreateTableSql(tableName, dropIfExists)。
+- Designer.cs 列走 DataGridViewColumn 序列化（DataGridViewTextBoxColumn 等），与本库无关。
+- 排错：EDG.Ctor.Log.txt 记录"谁改了列高模式+调用栈"；属性面板改了不生效 → 查 Designer.cs 残留显式模式行 + HintPath 是否指向旧版 DLL。
+
+---
+
+## 多选下拉框 MultiSelectComboBox
+
+**继承**：`Smart.CustomComponents.MultiSelectComboBox` ← `System.Windows.Forms.Control`
+
+带勾选、可搜索、可自定义输入的多选下拉框，选中项渲染成 Token（标签）。
+
+### 属性（全部 19 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Items | ComboBoxItemCollection |  | **Content 集合** | 下拉项字符串集合（Content 集合，逐条生成） |
+| Text | String |  | — | 显示文本；运行时取已选用 SelectedItems/SelectedValues |
+| MultiSelect | Boolean | True | 非默认才写 | 允许多选（Token 叠加）；false 时单选 |
+| AllowCustomInput | Boolean | False | 非默认才写 | 允许输入集合外自定义项 |
+| Searchable | Boolean | True | 非默认才写 | 下拉内搜索框开关 |
+| SelectedIndices | List<Int32> |  | 不序列化 |  |
+| SelectedValues | List<String> |  | 不序列化 |  |
+| SelectedItems | List<Object> |  | 不序列化 |  |
+| SelectedText | String |  | 不序列化 | 隐藏，不序列化 |
+| MaxDropDownItems | Int32 | 8 | 非默认才写 | 下拉最大可见行数，默认 8 |
+| DropDownWidth | Int32 | 0 | 非默认才写 |  |
+| DropDownHeight | Int32 | 0 | 非默认才写 |  |
+| DroppedDown | Boolean |  | 不序列化 |  |
+| TokenBackColor | Color |  | — | Token 底色，出厂 64,158,255 |
+| TokenForeColor | Color |  | — | Token 文字色，出厂 White |
+| BorderColor | Color |  | — | 边框色，出厂 173,178,184 |
+| HoverBorderColor | Color |  | — | 悬停边框色，出厂 64,158,255 |
+| ArrowColor | Color |  | — | 箭头色，出厂 96,98,102 |
+| ArrowHoverColor | Color |  | — | 箭头悬停色，出厂 64,158,255 |
+
+### 继承属性（名称全列）
+
+- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+| 事件 | 签名 |
+|---|---|
+| SelectedItemsChanged | EventHandler |
+| DropDown | EventHandler |
+| DropDownClosed | EventHandler |
+| TextChangedEx | EventHandler |
+- API：SelectIndex(i)/UnselectIndex(i)/ToggleIndex(i)/ClearSelection()/SelectAll()；ToggleDropDown()/OpenDropDown()/CloseDropDown()。
+- 事件：SelectedItemsChanged、DropDown、DropDownClosed、TextChangedEx。
+- 取值：selectedValues 属性（List<string>）或 SelectedIndices。
+
+---
+
+## 可调高下拉框 ResizableComboBox
+
+**继承**：`Smart.CustomComponents.ResizableComboBox` ← `System.Windows.Forms.Control`
+
+高度可自由调整的下拉框（标准 ComboBox 高度锁死，这是它存在的意义）。下拉面板自绘，支持排序/整合高度。
+
+### 属性（全部 17 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Items | ComboBoxItemCollection |  | **Content 集合** | 下拉项字符串集合（Content 集合） |
+| Text | String |  | — | 当前显示文本 |
+| SelectedIndex | Int32 | -1 | 非默认才写 | 选中索引，默认 -1 |
+| SelectedItem | Object |  | 不序列化 | 选中项（隐藏，运行时用） |
+| SelectedText | String |  | 不序列化 | 隐藏，不序列化 |
+| DropDownStyle | ComboBoxStyle | DropDownList | 非默认才写 | DropDownList（只可选）/DropDown（可输入），默认 DropDownList |
+| MaxDropDownItems | Int32 | 8 | 非默认才写 | 默认 8 |
+| DropDownWidth | Int32 | 0 | 非默认才写 |  |
+| DropDownHeight | Int32 | 0 | 非默认才写 |  |
+| IntegralHeight | Boolean | True | 非默认才写 | 行高取整，默认 true |
+| Sorted | Boolean | False | 非默认才写 | 自动排序，默认 false |
+| Flat | Boolean | False | 非默认才写 | 扁平外观开关 |
+| BorderColor | Color |  | — | 出厂 173,178,184 |
+| HoverBorderColor | Color |  | — | 出厂 64,158,255 |
+| ArrowColor | Color |  | — | 出厂 96,98,102 |
+| ArrowHoverColor | Color |  | — | 出厂 64,158,255 |
+| DroppedDown | Boolean |  | 不序列化 | 只读状态 |
+
+### 继承属性（名称全列）
+
+- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+| 事件 | 签名 |
+|---|---|
+| SelectedIndexChanged | EventHandler |
+| SelectedValueChanged | EventHandler |
+| DropDown | EventHandler |
+| DropDownClosed | EventHandler |
+| TextChangedEx | EventHandler |
+- API：ToggleDropDown()/OpenDropDown()/CloseDropDown()。
+- 事件：SelectedIndexChanged、SelectedValueChanged、DropDown、DropDownClosed、TextChangedEx。
+- Designer.cs 里 SelectedText 绝不写。
+
+---
+
+## 可调高文本框 ResizableTextBox
+
+**继承**：`Smart.CustomComponents.ResizableTextBox` ← `System.Windows.Forms.Control`
+
+高度可自由调整的单行文本框，带占位提示与三态边框色（常态/悬停/聚焦）。
+
+### 属性（全部 15 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Text | String |  | — | 文本内容 |
+| MaxLength | Int32 | 32767 | 非默认才写 | 最大长度，默认 32767 |
+| ReadOnly | Boolean | False | 非默认才写 | 只读 |
+| CharacterCasing | CharacterCasing | Normal | 非默认才写 | 大小写转换，默认 Normal |
+| PasswordChar | Char | \0（不掩码，写法 \0） | 非默认才写 | 密码掩码字符，默认 \0（不掩码） |
+| TextAlign | HorizontalAlignment | Left | 非默认才写 | Left/Center/Right，默认 Left |
+| PlaceholderText | String |  | — | 占位提示文字 |
+| Flat | Boolean | False | 非默认才写 | 扁平外观（去圆角） |
+| BorderColor | Color |  | — | 常态边框色，出厂 173,178,184 |
+| HoverBorderColor | Color |  | — | 悬停边框色，出厂 64,158,255 |
+| FocusBorderColor | Color |  | — | 聚焦边框色，出厂 64,158,255 |
+| PlaceholderColor | Color |  | — | 占位文字色，出厂 192,196,206 |
+| SelectionStart | Int32 |  | 不序列化 |  |
+| SelectionLength | Int32 |  | 不序列化 |  |
+| SelectedText | String |  | 不序列化 |  |
+
+### 继承属性（名称全列）
+
+- 继承 Control（73 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+| 事件 | 签名 |
+|---|---|
+| TextChanged | EventHandler |
+- 事件：TextChanged（基类）。
+- API：SelectAll()、Select(start, length)。
+
+---
+
+## OK/NG 状态灯 OKNGStatusControl
+
+**继承**：`Smart.CustomComponents.OKNGStatusControl` ← `System.Windows.Forms.Control`
+
+圆形 OK(绿)/NG(红) 状态灯，可绑定变量名由变量系统驱动。
+
+### 属性（全部 2 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| BindVariable | String |  | — | 绑定的变量名（变量绑定编辑器选择） |
+| IsOK | Boolean |  | — | true=OK(绿)，false=NG(红)；源码初始值 true |
+
+### 继承属性（名称全列）
+
+- 继承 Control（74 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Text, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+自有事件：无（仅基类事件）。
+- **绝不写 Text**（自绘覆盖文字）。
+- 运行时 this.okngStatusControl1.IsOK = false; 切红灯。
+
+---
+
+## 侧边菜单 SideMenuPanel
+
+**继承**：`Smart.CustomComponents.SideMenuPanel` ← `System.Windows.Forms.UserControl`
+
+折叠式侧边菜单 + 内容页面：MenuItems 声明菜单树（可递归子项），Pages 声明页面（MenuKey 关联菜单项），点击菜单自动切页。
+
+### 属性（全部 19 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| MenuItems | BindingList<SideMenuItem> |  | **Content 集合** | 菜单项集合（Content，条目 SideMenuItem 可递归 Children） |
+| Pages | BindingList<SideMenuPage> |  | **Content 集合** | 页面集合（Content，条目 SideMenuPage : Panel，设计器里页面字段名 sideMenuPageN） |
+| ActivePage | SideMenuPage |  | 不序列化 | 当前页（只读，隐藏） |
+| MenuWidth | Int32 | 160 | 非默认才写 | 菜单宽 px，默认 160 |
+| MenuCollapsed | Boolean | False | 非默认才写 | 折叠菜单，默认 false |
+| ItemHeight | Int32 | 34 | 非默认才写 | 菜单行高 px，默认 34 |
+| Indent | Int32 | 18 | 非默认才写 | 子级缩进 px，默认 18 |
+| IconSize | Int32 | 18 | 非默认才写 | 图标尺寸 px，默认 18 |
+| ShowIcons | Boolean | True | 非默认才写 | 显示图标，默认 true |
+| MenuBackColor | Color |  | — | 出厂 White |
+| MenuForeColor | Color |  | — | 出厂 80,80,80 |
+| SelectedColor | Color |  | — | 选中底色，出厂 230,247,255 |
+| SelectedForeColor | Color |  | — | 选中文字色，出厂 24,144,255 |
+| HoverColor | Color |  | — | 悬停底色，出厂 245,245,245 |
+| ArrowColor | Color |  | — | 展开箭头色，出厂 150,150,150 |
+| SplitterColor | Color |  | — | 菜单/内容分隔线色，出厂 235,235,235 |
+| ContentPanel | SideMenuContentPanel |  | 不序列化 | 内容容器（只读，隐藏；运行时向它加控件） |
+| SelectedNode | SideMenuItem |  | 不序列化 | 当前选中菜单项（隐藏） |
+| ForeColor | Color |  | 不序列化 | 隐藏（用 MenuForeColor 系列代替） |
+
+### 继承属性（名称全列）
+
+- 继承 UserControl（5 个）：AutoSize, AutoSizeMode, AutoValidate, BorderStyle, Text
+- 继承 ContainerControl（6 个）：AutoScaleDimensions, AutoScaleMode, BindingContext, ActiveControl, CurrentAutoScaleDimensions(RO), ParentForm(RO)
+- 继承 ScrollableControl（8 个）：AutoScroll, AutoScrollMargin, AutoScrollPosition, AutoScrollMinSize, DisplayRectangle(RO), HorizontalScroll(RO), VerticalScroll(RO), DockPadding(RO)
+- 继承 Control（69 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+| 事件 | 签名 |
+|---|---|
+| SelectedNodeChanged | EventHandler< |
+- API：SelectNode(SideMenuItem)、ShowPage(string key)、CanDropAt(Point)、GetActiveDropTarget()。
+- 事件：SelectedNodeChanged（参数 SelectedNodeChangedEventArgs.Node）。
+- 设计期默认集合内容只能在 Designer.Initialize 且 !host.Loading 时注入——绝不写进构造函数（会运行时翻倍）。
+
+---
+
+## 功能区 RibbonStrip
+
+**继承**：`Smart.CustomComponents.RibbonStrip` ← `System.Windows.Forms.UserControl`
+
+Excel 风格功能区：Tabs（选项卡）→ Groups（分组）→ Buttons（按钮）三层集合。设计器支持拖拽重排按钮、双击选项卡改名；点击按钮在运行时统一走 ButtonClick 事件。
+
+### 属性（全部 10 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Tabs | BindingList<RibbonTab> |  | **Content 集合** | 选项卡集合（Content，条目 RibbonTab.Groups→RibbonGroup.Buttons→RibbonButton） |
+| ActiveTabIndex | Int32 | 0 | 非默认才写 | 当前选项卡索引，默认 0 |
+| ActiveTab | RibbonTab |  | 不序列化 | 当前选项卡（只读，隐藏） |
+| AccentColor | Color | A=255, R=33, G=115, B=70 | 非默认才写 | 主题强调色（选中选项卡下划线等），出厂 33,115,70（Excel 绿） |
+| TabBarColor | Color | A=255, R=243, G=242, B=241 | 非默认才写 | 选项卡条底色，出厂 243,242,241 |
+| ContentColor | Color | White | 非默认才写 | 内容区底色，出厂 White |
+| SeparatorColor | Color | A=255, R=180, G=180, B=180 | 非默认才写 | 组分隔线色，出厂 180,180,180 |
+| ForeColor | Color |  | 不序列化 | 隐藏（组名/文字色内部固定） |
+| BackgroundImage | Image |  | 不序列化 |  |
+| BackgroundImageLayout | ImageLayout |  | 不序列化 |  |
+
+### 继承属性（名称全列）
+
+- 继承 UserControl（5 个）：AutoSize, AutoSizeMode, AutoValidate, BorderStyle, Text
+- 继承 ContainerControl（6 个）：AutoScaleDimensions, AutoScaleMode, BindingContext, ActiveControl, CurrentAutoScaleDimensions(RO), ParentForm(RO)
+- 继承 ScrollableControl（8 个）：AutoScroll, AutoScrollMargin, AutoScrollPosition, AutoScrollMinSize, DisplayRectangle(RO), HorizontalScroll(RO), VerticalScroll(RO), DockPadding(RO)
+- 继承 Control（67 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BackColor, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+| 事件 | 签名 |
+|---|---|
+| ButtonClick | EventHandler< |
+- 事件：ButtonClick(object sender, RibbonButtonEventArgs e)；e.Tab/e.Group/e.Button 分别为所在选项卡/分组/按钮（用 e.Button.Text 分发）。
+- 图标：RibbonButton.Image 序列化为 `buttonN.Image = RibbonButton.FromFile("路径")`（有来源路径时；ImageFile 属性本身隐藏）。
+- Designer.cs 生成规则（三层 Content 集合）见 codegen.md §2.5。
+
+---
+
+## 变量显示标签 VariableDisplayLabel
+
+**继承**：`Smart.CustomComponents.VariableDisplayLabel` ← `System.Windows.Forms.Control`
+
+只读展示绑定变量当前值的标签，值变化触发 ValueChanged。
+
+### 属性（全部 3 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| BindVariable | String |  | — | 绑定的变量名（变量绑定编辑器选择） |
+| DisplayValue | String |  | — | 当前显示值，默认 "——"（运行时由变量系统刷新） |
+| TextAlign | ContentAlignment | MiddleLeft | 非默认才写 | ContentAlignment，默认 MiddleLeft |
+
+### 继承属性（名称全列）
+
+- 继承 Control（74 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoSize, AutoScrollOffset, LayoutEngine(RO), BackColor, BackgroundImage, BackgroundImageLayout, BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, ForeColor, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Text, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), Padding, ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+| 事件 | 签名 |
+|---|---|
+| ValueChanged | EventHandler |
+- 只读控件：不接受输入（PreProcessMessage 恒 false）。
+- **⚠ 没有 BorderStyle**（继承 Control 不是 Label，s23 案例抄错即设计器中止加载）；要边框容器就用 Panel/GroupBox 包一层。
+- 事件：ValueChanged。
+
+---
+
+## 变量编辑框 VariableEditTextBox
+
+**继承**：`Smart.CustomComponents.VariableEditTextBox` ← `System.Windows.Forms.TextBox`
+
+标准 TextBox + 变量绑定：BindVariable 指向变量，Value 与 Text 同步。
+
+### 属性（全部 2 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| BindVariable | String |  | — | 绑定的变量名（变量绑定编辑器选择） |
+| Value | String |  | 不序列化 | 与 Text 同步的镜像值（隐藏，不序列化） |
+
+### 继承属性（名称全列）
+
+- 继承 TextBox（11 个）：AcceptsReturn, AutoCompleteMode, AutoCompleteSource, AutoCompleteCustomSource, CharacterCasing, Multiline, PasswordChar, ScrollBars, Text, TextAlign, UseSystemPasswordChar
+- 继承 TextBoxBase（21 个）：AcceptsTab, ShortcutsEnabled, AutoSize, BackColor, BackgroundImage, BackgroundImageLayout, BorderStyle, CanUndo(RO), ForeColor, HideSelection, Lines, MaxLength, Modified, Padding, PreferredHeight(RO), ReadOnly, SelectedText, SelectionLength, SelectionStart, TextLength(RO), WordWrap
+- 继承 Control（67 个）：AccessibilityObject(RO), AccessibleDefaultActionDescription, AccessibleDescription, AccessibleName, AccessibleRole, AllowDrop, Anchor, AutoScrollOffset, LayoutEngine(RO), BindingContext, Bottom(RO), Bounds, CanFocus(RO), CanSelect(RO), Capture, CausesValidation, ClientRectangle(RO), ClientSize, CompanyName(RO), ContainsFocus(RO), ContextMenu, ContextMenuStrip, Controls(RO), Created(RO), Cursor, DataBindings(RO), DeviceDpi(RO), DisplayRectangle(RO), IsDisposed(RO), Disposing(RO), Dock, Enabled, Focused(RO), Font, Handle(RO), HasChildren(RO), Height, IsHandleCreated(RO), InvokeRequired(RO), IsAccessible, IsMirrored(RO), Left, Location, Margin, MaximumSize, MinimumSize, Name, Parent, ProductName(RO), ProductVersion(RO), RecreatingHandle(RO), Region, Right(RO), RightToLeft, Site, Size, TabIndex, TabStop, Tag, Top, TopLevelControl(RO), UseWaitCursor, Visible, Width, WindowTarget, PreferredSize(RO), ImeMode
+- 继承 Component（1 个）：Container(RO)
+
+### 事件
+
+自有事件：无（仅基类事件）。
+- 其余全部属性/事件与标准 TextBox 一致（Text/Multiline/PasswordChar/TextChanged…见 winforms-controls.md#TextBox）。
+- Designer.cs 只需写 BindVariable 与常用 TextBox 属性。
+- **⚠ 没有 PlaceholderText**（那是 ResizableTextBox 的自有属性，s23 案例抄错即设计器中止加载）；要占位提示就用 ResizableTextBox。
+
+---
+
+## 日志记录器 Logger（非可视组件）
+
+**继承**：`Smart.CustomComponents.Logger` ← `System.ComponentModel.Component`
+
+拖到窗体托盘的日志组件，代码里直接调中文方法写日志。
+
+### 属性（全部 4 个自有属性）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| 日志文件名 | String | logs\app.log | 非默认才写 | 日志文件路径，默认 logs\app.log |
+| 日志级别 | 日志级别枚举 | 信息 | 非默认才写 | 调试/信息/警告/错误/致命，默认 信息 |
+| 按天滚动 | Boolean | True | 非默认才写 | 按日期滚动文件，默认 true |
+| 最多保留份数 | Int32 | 30 | 非默认才写 | 滚动保留份数，默认 30 |
+
+### 继承属性（名称全列）
+
+- 继承 Component（2 个）：Site, Container(RO)
+
+### 事件
+
+自有事件：无（仅基类事件）。
+- API：写调试(msg)/写信息(msg)/写警告(msg)/写错误(msg)/写异常(msg, ex)；设计模式下调用是空操作。
+- 事件：无（仅 Disposed）。
+
+---
+
+## Content 集合条目类型（全部属性）
+
+### DockWindowItem（DockSurface.DockWindows 的条目）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| ClassName | String | DockWindow | 非默认才写 |  |
+| Title | String | 停靠窗口 | 非默认才写 |  |
+| PersistString | String |  | 不序列化 |  |
+| DockState | DockState | DockLeft | 非默认才写 |  |
+| DefaultWidth | Int32 | 220 | 非默认才写 |  |
+| DefaultHeight | Int32 | 180 | 非默认才写 |  |
+| FixedPosition | Boolean | False | 非默认才写 |  |
+| ShowCloseButton | Boolean | True | 非默认才写 |  |
+| ContentXml | String |  | 不序列化 |  |
+| ColumnsXml | String |  | 不序列化 |  |
+| SourceFile | String |  | 不序列化 |  |
+| HasContent | Boolean |  | 不序列化 |  |
+- Hidden 属性（PersistString/ContentXml/ColumnsXml/SourceFile）由三文件生成器消费，绝不手写。
+- HasContent 只读，指示是否已挂窗口内容。
+
+### SideMenuItem（SideMenuPanel.MenuItems 的条目）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Text | String |  | — |  |
+| Icon | Image |  | — |  |
+| IsExpanded | Boolean | False | 非默认才写 |  |
+| Children | BindingList<SideMenuItem> |  | **Content 集合** |  |
+- Children 可递归嵌套子菜单（Content 集合）。
+
+### SideMenuPage（SideMenuPanel.Pages 的条目）: Panel
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| MenuKey | String |  | — |  |
+- MenuKey 与某个菜单项对应（点击该菜单项显示本页）；其余属性同 Panel。
+
+### RibbonTab（RibbonStrip.Tabs 的条目）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Text | String |  | — |  |
+| Groups | BindingList<RibbonGroup> |  | **Content 集合** |  |
+- Groups 为分组集合（Content）。
+
+### RibbonGroup（RibbonTab.Groups 的条目）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Text | String |  | — |  |
+| Buttons | BindingList<RibbonButton> |  | **Content 集合** |  |
+- Buttons 为按钮集合（Content）。
+
+### RibbonButton（RibbonGroup.Buttons 的条目）
+
+| 属性 | 类型 | 默认值 | 序列化 | 说明 |
+|---|---|---|---|---|
+| Name | String |  | — |  |
+| ImageFile | String |  | 不序列化 |  |
+| Image | Image |  | — |  |
+| Text | String |  | — |  |
+| SizeStyle | RibbonButtonSize | Small | 非默认才写 |  |
+| Enabled | Boolean | True | 非默认才写 |  |
+- Image 有路径时序列化为 `= RibbonButton.FromFile("路径")`；ImageFile 本身隐藏。
+- Name 用于设计器标识；运行时分发用 Text。
+
+---
+
+## 枚举全值表（Designer.cs 一律写英文标识符，ImageButton 枚举例外——本身就是中文）
+
+### RoundedButtonStyle：Primary=0、Success=1、Warning=2、Danger=3、Info=4、Dark=5、Light=6、Outline=7
+
+### Smart.CustomComponents.DockSurface+SurfaceTheme：VS2015Light=0、VS2015Blue=1、VS2015Dark=2、VS2013Light=3、VS2013Blue=4、VS2013Dark=5、VS2012Light=6、VS2005=7、VS2003=8、Default=9
+
+### Smart.CustomComponents.DockSurface+TabTipDirection：Left=0、Right=1
+
+### RibbonButtonSize：Large=0、Small=1
+
+### 日志级别枚举：调试=0、信息=1、警告=2、错误=3、致命=4
+
+### 图片锚点位置：Center=0、N=1、S=2、E=3、W=4
+
+### 图片缩放模式：Original=0、Fit=1、Stretch=2、Tile=3
+
+### 图文布局枚举：文字居中=0、图下文上=1、图上文下=2、图右文左=3、图左文右=4、纯图片=5
+
+## DockState 枚举（DockWindowItem.DockState 用，WeifenLuo）
+
+值：Unknown、Float、DockTop、DockBottom、DockLeft、DockRight、Document、Hidden（常用：DockLeft/DockRight/DockBottom/Document/Float）。
+
+## 共享基类属性速览
+
+大多数增强控件继承 System.Windows.Forms.Control；Control 基类全部 73 个属性（含默认值）的完整表格见 `winforms-controls.md` 第 0 节"Control 基类属性总表"，此处不重复。