u

code/g3soft-libs/docs/table-design.md

@@ -16,7 +16,7 @@
 
 | 类别 | 内容 | 是否值得搬 |
 |---|---|---|
-| **A. 性能门控启发式** | `MIN_VIRTUAL_ROW_COUNT = 100`（行数少时**关**虚拟滚动）、`MIN_VIRTUAL_X_COLUMN_COUNT = 20`、`editingActive` 抑制编辑态下的逐格 `customCell` 注入 | ✅ 这是真正的核心价值，必须搬 |
+| **A. 性能门控启发式** | `MIN_VIRTUAL_ROW_COUNT = 100`（行数少时**关**虚拟滚动）、`MIN_VIRTUAL_X_COLUMN_COUNT = 20`、`customCell` 恒定注入（列引用与编辑态解耦，见 §4.3） | ✅ 这是真正的核心价值，必须搬 |
 | **B. 防抖 / 节流** | resize 150ms trailing 防抖、键盘编辑激活 100ms 合并、rAF 合并同一帧多次通知 | ✅ 直接搬 |
 | **C. 针对 v1.1.0 的 workaround** | `effectiveVirtualX`（库在 virtualX 下会把列宽钉死，破坏原生自适应）、`--bg-border-right` 局部清除、`border-left: none`、`td:has(...)` 补高等 | ⚠️ **不抄注释，按我们自己的验证结论重写** |
 | **D. 业务耦合** | `useAppStore` 取暗色模式、`@/components/ui/*` 直接 import 内部组件 | ❌ 必须替换成 `@g3soft/*` 对应物 |
@@ -181,17 +181,29 @@ const effectiveVirtual = computed(
 （`cellStyleMap` 的 `--cw` + `width/min-width/max-width` 三重锁），未设 `width` 的列
 会失去「按比例铺满容器」的原生自适应。列数少、总宽不超容器时用不上横向虚拟。
 
-### 4.3 `editingActive`：无编辑行时**不注入** `customCell`
+### 4.3 `customCell` 恒定注入（原 `editingActive` 门控已废除）
 
 ```ts
-// 有行在编辑时列才带 customCell；无编辑行时全部走库原生 td
+// 编辑列恒定注入 customCell；列引用与「有没有行在编辑」完全解耦
 const displayColumns = computed(() => {
-  const cols = props.columns.map((c) => resolveCustomCell(c, editingCtx, editingActive.value))
+  const cols = props.columns.map((c) => resolveCustomCell(c, editingCtx))
   // ...
 })
 ```
-**这是整个方案里单点收益最大的优化**：纯展示 / 非编辑态的可编辑列不再包裹函数式组件，
-滚动时每格省掉一个组件实例。行与行之间切换编辑**不翻转** `editingActive`，避免整表列重建。
+
+> **2026-10 性能排查后的设计反转**：原方案「无编辑行时不注入 `customCell`」的代价在
+> **首次点击**——点击使门控翻转 → 整个列数组重建（新列对象 + 新 customCell 闭包）→
+> 底座表头 / 几何 / 样式缓存全部失效 → 全表重排重绘，实测阻塞主线程 298~394ms
+> （966~1008 次 DOM 变更），是「点击卡顿」的主因。
+>
+> 现在编辑列**恒定注入**：列引用在编辑态翻转时完全不变，点击不再触碰这条链路。
+> 整列禁用的列例外（不注入，走 td 类名，零开销）——它们永远不会出现编辑器，
+> 渲染不随编辑态变化。见 `utils/column.ts` 的 `resolveCustomCell` 与
+> `utils/editable.ts` 的 `createEditableCell`（编辑器按行分发）。
+>
+> 代价：非编辑态的编辑列每格多一个函数式组件实例（滚动每帧成本的一个增量项）；
+> 与点击省下的 300ms+ 相比是划算的交换。滚动卡顿的真正大头是虚拟滚动的每帧
+> 全表重渲染（底座侧问题），不在这一个包装层。
 
 ### 4.4 尺寸与键盘防抖
 
@@ -303,7 +315,7 @@ dependencies:
 1. **底座打通**：装依赖 → 样式合流进 `dist/style.css` → 最小可渲染表格 → 验证 ESM / 类型 / 主题变量不冲突
 2. **核心只读**：列定义 + 类型 + 虚拟门控（§4.1/4.2）+ 序号列 + 排序 + 固定列 + 空态 + 单测
 3. **交互层**：多选列（§4.6）+ resize/键盘防抖（§4.4）+ 列宽/列序拖拽 + E2E 几何
-4. **编辑与操作**：`editingActive`（§4.3）+ 行内编辑 + 操作列 + 行拖拽 + 表尾合计 + 文档/示例
+4. **编辑与操作**：`customCell` 恒定注入（§4.3）+ 行内编辑 + 操作列 + 行拖拽 + 表尾合计 + 文档/示例
 
 ---