基线:全量源码首提(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,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 基类属性总表"，此处不重复。