@taocompany/magic-grid 0.1.5 → 0.2.0

package/README.md

@@ -6,10 +6,12 @@
 
 - [概述](#概述)
 - [快速开始](#快速开始)
+- [默认配置](#默认配置)
 - [Props](#props)
   - [MagicGrid Props](#magicgrid-props)
     - [Grid 级默认与列级覆盖](#grid-级默认与列级覆盖)
   - [ColumnDef 列定义](#columndef-列定义)
+    - [列有效性与显隐](#列有效性与显隐)
 - [Options 类型参考](#options-类型参考)
 - [Events](#events)
 - [Expose](#expose)
@@ -19,7 +21,7 @@
   - [ColumnSettingsPanel](#columnsettingspanel)
   - [ColumnSettingsMenuItem](#columnsettingsmenuitem)
   - [ColumnSettingsMenuIcon](#columnsettingsmenuicon)
-- [相关文档](#相关文档)
+- [校验子路径](#校验子路径)
 
 ---
 
@@ -32,7 +34,7 @@
 | **性能** | 行/列双轴虚拟化、DOM 池复用、RAF 帧预算分片、增量数据管线 |
 | **数据** | 排序、列筛选、Quick Filter、事务增量更新（`applyTransaction`）、行 CRUD |
 | **交互** | 单元格/行编辑、校验、行选择、索引列定位、框选与剪贴板 |
-| **布局** | 固定列、列拖拽/调整宽度、合并单元格、动态行高、主从展开行 |
+| **布局** | 固定列、列拖拽/调整宽度、列有效性与显隐（`available` / `hidden`）、合并单元格、动态行高、主从展开行 |
 | **结构** | 行分组、树形表格（含懒加载）、表尾汇总 |
 | **体验** | 溢出 Tooltip、单元格批注、空态 Overlay、暗色主题、底部状态栏 |
 
@@ -123,15 +125,225 @@ const columns: ColumnDef[] = [
 
 ---
 
+## 默认配置
+
+以下为 `<MagicGrid>` **未显式传入 prop** 时的生效值。部分 prop 在组件层与内核层默认不同（标注 **MG** = MagicGrid 组件层覆盖），使用时以组件行为为准。
+
+### 尺寸 preset（`size`）
+
+`rowHeight` / `headerHeight` / `statusBarHeight`（`statusBarHeight: 'auto'` 时）未显式传入时，由 `size` 推导：
+
+| `size` | 行高 | 表头高 | 状态栏高 | 字号 | 间距 | 圆角（`rounded: true` 时） |
+|--------|------|--------|----------|------|------|---------------------------|
+| `mini` | 20 | 20 | 20 | 12 | 4 | 4 |
+| `small` | 24 | 24 | 24 | 12 | 8 | 8 |
+| `default` | 32 | 32 | 32 | 12 | 8 | 8 |
+| `large` | 40 | 40 | 40 | 14 | 12 | 8 |
+
+### 基础与外观
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `rowKey` | `'id'` | 行主键字段 |
+| `height` / `width` | `'100%'` | 容器尺寸 |
+| `stripe` | `false` | 斑马纹 |
+| `border` | `'border'` | 全网格线 |
+| `theme` | `'light'` | 亮色主题 |
+| `size` | `'default'` | 尺寸 preset |
+| `rounded` | `false` | 无圆角（`0`） |
+| `rowHeight` / `headerHeight` | — | 跟随 `size` preset |
+| `summaryRowHeight` | — | 跟随 `rowHeight` |
+
+### 对齐
+
+| 配置项 | 默认值 |
+|--------|--------|
+| `headerAlign` / `headerValign` | `'center'` |
+| `align` / `valign` | `'center'` |
+| `footerAlign` / `footerValign` | `'center'` |
+
+### 虚拟化与导航
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `rowBuffer` | `10` | 行虚拟化缓冲行数 |
+| `navigateHeader` | `false` | 不允许焦点进入表头 |
+| `navigateFooter` | `false` | 不允许焦点进入表尾 |
+| `enableHeaderHighlight` | `true` | 框选时表头列高亮 |
+| `enableIndexColumnHighlight` | `true` | 框选时索引列高亮 |
+
+### 索引列
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `showIndexColumn` | `false` | 不显示索引列 |
+| `indexColumn.label` | `''` | 表头文案 |
+| `indexColumn.width` | `40` | 列宽 px（最小 40） |
+| `indexColumn.start` | `1` | 起始序号 |
+| `indexColumn.focusMode` | `'multiple'` | 辅助定位模式 |
+| `indexColumn.syncToSelectionColumn` | `true` **(MG)** | 索引定位单向同步行选择 |
+| `indexColumn.showRowDragHandle` | `false` | 不显示行拖拽把柄 |
+| `indexColumn.enableRowResizer` | `false` | 不可拖拽调整行高 |
+
+### 行选择
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `rowSelection` | `'single'` | 单选模式 |
+| `selectionColumn.width` | `40` | 列宽 px |
+| `selectionColumn.selectAllLabel` | `'全选'` | 全选 checkbox aria-label |
+| `reserveSelection` | `false` | 数据刷新后不保留选中 |
+
+`rowSelection` 对象形式时，`groupSelectsChildren` 默认 `true`（tree 模式父节点级联子孙）。
+
+### 表尾汇总
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `showSummary` | `false` | 不展示汇总行 |
+| `summaryScope` | `'displayed'` | 按当前可见行汇总 |
+
+### 排序 / 筛选 / 列操作
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `sortable` | `false` | 全列默认不可排序 |
+| `filterable` | `false` | 全列默认不可筛选 |
+| `resizable` | `true` | 全列默认可调整列宽 |
+| `columnMovable` | `true` | 全列默认可拖拽重排 |
+| `quickFilterText` | `''` | 无 quick filter |
+| `floatingFilter` | `false` | 无 floating filter 行 |
+| `filterSetValueMode` | `'current'` | 值选择勾选投影模式 |
+| `filterSetDateLayoutMode` | `'tree'` | 日期列值选择树形展示 |
+| `colResizeDefault` | — | 未启用 Shift 邻列补偿 |
+| `skipHeaderOnAutoSize` | `false` | auto-size 含表头宽度 |
+| `autoSizePadding` | `16` | auto-size 额外 padding（px） |
+| `suppressMoveWhenColumnDragging` | `false` | drag 过程中 live move |
+| `suppressColumnMoveAnimation` | `false` | 列移动有过渡动画 |
+| `allowCrossLaneColumnMove` | `false` | 不可跨 fixed lane 移动 |
+| `showUnsortedSortHintOnHover` | `false` | 未排序列 hover 无双三角提示 |
+
+### 编辑
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `editMode` | `'cell'` | 单格编辑 |
+| `editType` | `'singleClick'` | 单击进入编辑 |
+| `invalidEditValueMode` | `'block'` | 校验失败保持编辑态 |
+
+### 行拖拽与行高
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `rowDragManaged` | `true` | managed 拖拽实时改序 |
+| `rowDragCommitMode` | `'sync'` | 同步提交 |
+| `rowHeightMin` | — | 跟随 size / rowHeight |
+| `rowHeightMax` | — | 无上限 |
+
+### 合并 / 展开 / 分组 / 树
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enableCellSpan` | `false` | 不启用单元格合并 |
+| `masterDetail` | `false` | 不启用主从展开 |
+| `masterDefaultExpanded` | `0` | 默认不展开（启用 masterDetail 后） |
+| `detailRowHeight` | `200` | 详情行高度 px |
+| `detailRowAutoHeight` | `false` | 详情行固定高度 |
+| `embedFullWidthRows` | `false` | 详情 overlay 不随横滚 |
+| `showExpandColumn` | `false` | 不展示专用展开列 |
+| `rowGrouping` | `false` | 不启用行分组 |
+| `groupDefaultExpanded` | `-1` | 全部分组默认展开 |
+| `showGroupHeader` / `showGroupFooter` | `false` | 不展示分组头/尾行 |
+| `groupDisplayType` | `'singleColumn'` | 单列分组展示 |
+| `showGroupColumn` | `false` | 不展示 auto group 列 |
+| `tree` | `false` | 不启用树形表格 |
+| `showTreeColumn` | `true` | 展示 tree 系统列（启用 tree 后） |
+| `treeDragScope` | `'siblings'` | 树拖拽仅同层兄弟 |
+| `treeDisplayType` | `'singleColumn'` | 单列树展示 |
+| `treeLazyLoad` | `false` | 不启用懒加载 |
+
+### 批注
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `suppressCellComments` | `false` | 不抑制批注 |
+| `cellCommentTrigger` | `'click'` | 点击角标查看 |
+| `cellCommentShowDelay` | `180` | hover 展示延迟 ms |
+| `cellCommentHideDelay` | `220` | 离开隐藏延迟 ms |
+
+### 框选与剪贴板
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `cellSelection` | `true` **(MG)** | 启用框选（Grid API 直连默认 `false`） |
+| `cellSelection.enableColumnSelection` | `true` **(MG)** | 点击表头选中整列（Grid API 默认 `false`） |
+| `cellSelection.suppressMultiRanges` | `true` | 仅允许单个 range |
+| `cellSelection.handleMode` | `'off'` | 无 Fill/Range 拖拽柄 |
+| `cellSelection.direction` | `'xy'` | fill 方向（handleMode 为 fill 时） |
+| `cellSelection.fillStrategy` | `'copy'` | 填充策略 |
+| `cellSelection.fillReverseStrategy` | `'default'` | 反拖缩小行为 |
+| `enableCellCopy` | `true` | Ctrl+C / 复制 API |
+| `enableCellPaste` | `false` | Ctrl+V / 粘贴 API |
+
+### Tooltip
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enableTooltips` | `true` | 启用溢出 tooltip |
+| `tooltipShowMode` | `'whenTruncated'` | 仅溢出时展示 |
+| `tooltipShowDelay` | `500` | 首次 hover 延迟 ms |
+| `tooltipSwitchShowDelay` | `200` | 格间切换延迟 ms |
+| `tooltipHideDelay` | `3000` | 离开后隐藏延迟 ms |
+| `tooltipInteraction` | `false` | tooltip 不可交互 |
+| `tooltipMouseTrack` | `false` | tooltip 不跟随鼠标 |
+
+### 空态 Overlay
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `loading` | `undefined` | 挂载后首次 `setData` 前自动 loading |
+| `overlayInteraction` | `false` | overlay 内容不可交互 |
+
+### 状态栏
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `showStatusBar` | `true` | 显示底部状态栏 |
+| `showDefaultStatusBarPanels` | `true` | 显示默认左侧面板 |
+| `statusBarHeight` | `'auto'` | 跟随 size preset |
+| `showStatusBarRangeAggregation` | `true` | 框选时展示聚合 |
+| `statusBarRangeAggregationPosition` | `'right'` | 聚合 panel 在右栏 |
+| `statusBarRangeAggregationPrecision` | `2` | 平均值/求和各 2 位小数 |
+
+### ColumnDef 列级默认
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `available` | `true` | 列有效；`false` 时不进入列模型（表格中无此列） |
+| `hidden` | `false` | 列可见；`true` 时仍在列模型中但不渲染（可 API/菜单恢复） |
+| `sortable` / `filterable` | 继承 Grid 级（默认 `false`） | 列级显式配置优先 |
+| `resizable` / `movable` | 继承 Grid 级（默认 `true`） | 列级显式配置优先 |
+| `filterType` | `'text'` | 文本筛选 |
+| `cellEditorMode` | `'overlay'` | 编辑 overlay 呈现 |
+| `editType` | 继承 Grid 级 | — |
+| `useParserForClipboard` | `true` | 粘贴走 valueParser |
+| `useFormatterForClipboard` | `true` | 复制走 formatter |
+| `summary` | 有 `summaryAgg` 时为 `true` | 否则 `false` |
+| 对齐字段 | `'center'` | header / body / footer |
+
+---
+
 ## Props
 
+> 各 prop 的默认值汇总见上一节 [默认配置](#默认配置)。下列按功能分组逐项说明类型、默认值与行为。
+
 ### MagicGrid Props
 
 #### 基础
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `columns` | `ColumnDef[]` | — | **必填**。列定义数组 |
+| `columns` | `ColumnDef[]` | — | **必填**。列定义数组；`available: false` 的项仍可在 prop 中保留，但不会进入 Grid 列模型 |
 | `data` | `RowData[]` | — | **必填**。行数据（普通对象，禁止 reactive 深代理） |
 | `rowKey` | `string` | `'id'` | 行主键字段名，用于行池复用与增量更新 |
 | `height` | `string \| number` | `'100%'` | 容器高度 |
@@ -349,10 +561,9 @@ interface RowSelectionConfig {
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `cellSelection` | `boolean \| CellSelectionOptions` | `true` | 单元格框选；MagicGrid 默认开启、`enableColumnSelection` 为 `true`、`handle` 为 off；Grid API 未传时默认关闭 |
+| `cellSelection` | `boolean \| CellSelectionOptions` | `true` | 单元格框选；MagicGrid 默认开启、`enableColumnSelection` 为 `true`、`handleMode` 为 off；Grid API 未传时默认关闭 |
 | `enableCellCopy` | `boolean` | `true` | Ctrl+C / `copySelectedRangeToClipboard` |
 | `enableCellPaste` | `boolean` | `false` | Ctrl+V / `pasteFromClipboard` |
-| `enableCellClipboard` | `boolean` | — | **已废弃**；未单独指定 copy/paste 时二者均继承本值 |
 | `processCellForClipboard` | `ProcessCellForClipboardFn` | — | 复制单格时自定义导出值 |
 | `processCellFromClipboard` | `ProcessCellFromClipboardFn` | — | 粘贴单格时预处理 clipboard 字符串 |
 | `processDataFromClipboard` | `ProcessDataFromClipboardFn` | — | 整表粘贴前处理 TSV 矩阵；return null 取消粘贴 |
@@ -363,21 +574,21 @@ interface RowSelectionConfig {
 |------|------|--------|------|
 | `suppressMultiRanges` | `boolean` | `true` | `true` 时仅允许单个 range |
 | `enableColumnSelection` | `boolean` | MagicGrid `true` / Grid API `false` | 点击表头选中整列 |
-| `handle` | `FillHandleOptions \| RangeHandleOptions` | — | Fill 或 Range 拖拽柄；MagicGrid / Grid API 缺省均为 off |
-
-`FillHandleOptions`（`handle: { mode: 'fill', ... }`）：
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `mode` | `'fill'` | — | **必填** |
-| `direction` | `'x' \| 'y' \| 'xy'` | `'xy'` | 填充方向 |
+| `handleMode` | `'off' \| 'fill' \| 'range'` | `'off'` | Fill / Range 拖拽柄 |
+| `direction` | `'x' \| 'y' \| 'xy'` | `'xy'` | `handleMode: 'fill'` 时填充方向 |
 | `fillStrategy` | `'auto' \| 'copy'` | `'copy'` | `'auto'`：数字递增、非数字复制；`'copy'`：始终复制源边值 |
 | `fillReverseStrategy` | `'default' \| 'clear'` | `'default'` | 反拖缩小时：`'default'` 不处理；`'clear'` 置空缩出初始选区的格 |
 | `setFillValue` | `(params: FillOperationParams) => unknown` | — | 自定义填充值；缺省按 `fillStrategy` |
 
-`RangeHandleOptions`（`handle: { mode: 'range' }`）：仅含 `mode: 'range'`，用于右下角拖拽扩展选区。
+`FillOperationParams`：`{ rowNode, column, baseValue, step, direction }`。
+
+框选行为要点：
 
-> 框选详细行为见 [`docs/35-phase24-cell-range-selection.md`](docs/35-phase24-cell-range-selection.md)。
+- 鼠标拖拽或 Shift+方向键扩展选区；`suppressMultiRanges: true` 时仅保留单个 range。
+- `enableColumnSelection: true` 时点击表头选中整列；MagicGrid 默认开启。
+- `handleMode: 'fill'` 启用填充柄；`'range'` 启用范围扩展柄；`'off'` 无柄（MagicGrid 默认）。
+- Delete 键清空选区内可编辑格，触发 `cell-selection-delete-start` / `cell-selection-delete-end`。
+- Ctrl+C / `copySelectedRangeToClipboard` 复制 TSV；Ctrl+V / `pasteFromClipboard` 粘贴（需 `enableCellPaste: true`）。
 
 #### Tooltip
 
@@ -420,8 +631,10 @@ interface RowSelectionConfig {
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `showStatusBar` | `boolean` | `true` | 是否显示底部状态栏 |
+| `statusBarHeight` | `'auto' \| number` | `'auto'` | 状态栏高度；`auto` 跟随 size preset |
 | `showDefaultStatusBarPanels` | `boolean` | `true` | 显示默认状态栏左侧面板（行数/筛选态/选中数）；`false` 时仍可自定义 `#status-bar-left` |
 | `showStatusBarRangeAggregation` | `boolean` | `true` | 框选时在状态栏展示平均值/计数/求和 |
+| `statusBarRangeAggregationPosition` | `'left' \| 'right'` | `'right'` | 框选聚合 panel 位置（左栏/右栏内侧） |
 | `statusBarRangeAggregationPrecision` | `number \| { average?: number; sum?: number }` | `2` | 平均值/求和展示小数位数 |
 
 #### Grid 级默认与列级覆盖
@@ -465,7 +678,48 @@ interface RowSelectionConfig {
 | `key` | `string` | 列唯一标识（colId），缺省等于 `prop` |
 | `prop` | `string` | 数据字段 |
 | `label` | `string` | 表头文案 |
-| `hidden` | `boolean` | 是否隐藏该列（不渲染、不参与布局）；默认 `false` |
+
+#### 列有效性与显隐
+
+通过 `available` 与 `hidden` 控制列是否参与表格。二者均可在 `columns` prop 中动态修改；Grid 会重解析列模型并刷新布局。
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `available` | `boolean` | `true` | `false` 时该列**不存在于表格**（解析前从列模型裁剪 · 不参与布局/DOM · 无 `setColumnsHidden`） |
+| `hidden` | `boolean` | `false` | `true` 时列**仍在列模型**中，仅不渲染（可通过 `setColumnsHidden` / 列菜单 / 列设置面板恢复） |
+
+**语义对照**：
+
+| | `available: false` | `hidden: true` |
+|---|-------------------|----------------|
+| `getColumns()` | **不含**该列 | **含**该列 |
+| `getDisplayedColumns()` | **不含** | **不含** |
+| DOM / 布局 | 不参与 | 不参与 |
+| `setColumnsHidden` | 不适用（列不在模型中） | 可恢复显示 |
+| sort / filter 模型 | 不应再引用该 colId | 仍可保留 · 表头无 UI |
+| 列设置面板 | 不出现（未注册进模型） | 出现在「隐藏」分组 |
+| 典型用途 | 按权限/场景裁剪列定义 | 用户临时隐藏列 |
+
+```ts
+const columns: ColumnDef[] = [
+  { prop: 'name', label: '名称' },
+  // 表格中完全没有这一列（行数据字段可保留）
+  { prop: 'internalCode', label: '内部编码', available: false },
+  // 列仍在模型中，默认隐藏，API/菜单可恢复
+  { prop: 'note', label: '备注', hidden: true },
+]
+
+// hidden 列：全量 vs 展示
+api.getColumns().map((c) => c.colId)        // 含 note
+api.getDisplayedColumnIds()                 // 不含 note（除非已显示）
+
+// available: false 的列不在 getColumns() 中
+api.getColumns().some((c) => c.colId === 'internalCode') // false
+```
+
+修改 `columns` 中某列的 `available` 或 `hidden` 后，Grid 会走 `setColumns` 重解析。`hidden` 在 `columnDefs` 未改 `hidden` 声明时，会保留运行时 API/菜单设置的值（与 Phase 22 列显隐语义一致）。
+
+Playground 验收：开发环境 `/phase22` · **T14–T15**（`legacyToken` 列可切换 `available`）。
 
 #### 尺寸
 
@@ -634,21 +888,14 @@ interface RowSelectionConfig {
 |------|------|--------|------|
 | `suppressMultiRanges` | `boolean` | `true` | 仅允许单个 range |
 | `enableColumnSelection` | `boolean` | MagicGrid `true` / Grid API `false` | 点击表头选中整列 |
-| `handle` | `FillHandleOptions \| RangeHandleOptions` | — | Fill / Range 拖拽柄；缺省 off |
-
-**FillHandleOptions**（`mode: 'fill'`）：
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `direction` | `'x' \| 'y' \| 'xy'` | `'xy'` | 填充方向 |
+| `handleMode` | `'off' \| 'fill' \| 'range'` | `'off'` | Fill / Range 拖拽柄 |
+| `direction` | `'x' \| 'y' \| 'xy'` | `'xy'` | `handleMode: 'fill'` 时填充方向 |
 | `fillStrategy` | `'auto' \| 'copy'` | `'copy'` | 数字递增策略 |
 | `fillReverseStrategy` | `'default' \| 'clear'` | `'default'` | 反拖缩小行为 |
 | `setFillValue` | `(params: FillOperationParams) => unknown` | — | 自定义填充值 |
 
 `FillOperationParams`：`{ rowNode, column, baseValue, step, direction }`。
 
-**RangeHandleOptions**：`{ mode: 'range' }`，右下角拖拽扩展选区。
-
 **CellRange**（`addCellRange` / `getCellRanges` 返回值）：
 
 ```ts
@@ -900,120 +1147,378 @@ type StatusBarRangeAggregationPrecisionInput =
 
 ## Events
 
-MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 kebab-case。
+MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 **kebab-case**。除 Vue 事件外，也可通过 `gridRef.api.on(...)` 订阅 camelCase 内核事件（见 [Expose](#expose)）。
 
 ### 渲染与滚动
 
-| 事件 |  payload | 说明 |
-|------|----------|------|
-| `scroll` | `GridMetrics` | 滚动后触发（含 scrollTop、可见行范围等） |
-| `data-rendered` | `GridMetrics` | 数据渲染完成后触发 |
+#### `scroll`
+
+滚动后触发，payload 为 `GridMetrics`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowCount` | `number` | 过滤后显示行数 |
+| `sourceRowCount` | `number` | 源数据总行数 |
+| `columnCount` | `number` | 列数 |
+| `activeDomRowCount` | `number` | 行池活跃 DOM 行数 |
+| `domCellCount` | `number` | 表体单元格 DOM 数 |
+| `scrollTop` / `scrollLeft` | `number` | 当前滚动位置（px） |
+| `totalHeight` / `totalWidth` | `number` | 内容区总尺寸（px） |
+| `renderedFirstRow` / `renderedLastRow` | `number` | 渲染窗口行下标范围 |
+| `renderedFirstCol` / `renderedLastCol` | `number` | 渲染窗口列下标范围 |
+| `lastSetDataMs` | `number` | 最近一次 setData 耗时（ms） |
+
+#### `data-rendered`
+
+数据渲染完成后触发，payload 同 `GridMetrics`。
 
 ### 交互
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `cell-clicked` | `CellClickedEvent` | 单元格点击 |
-| `row-click` | `RowClickedEvent` | 行点击 |
-| `row-dblclick` | `RowDoubleClickedEvent` | 行双击 |
-| `selection-changed` | `SelectionChangedEvent` | 行选择变更；含 `selectedRowIds` |
-| `index-focus-changed` | `IndexFocusChangedEvent` | 索引列辅助定位变更 |
+#### `cell-clicked`
+
+payload 为 `CellClickedEvent`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 行 id |
+| `colId` | `string` | 列 id |
+| `rowIndex` | `number` | `rowsToDisplay` 中的行下标 |
+| `rowNode` | `RowNode` | 行节点快照 |
+
+#### `row-click` / `row-dblclick`
+
+payload 为 `RowClickedEvent` / `RowDoubleClickedEvent`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 行 id |
+| `rowIndex` | `number` | 行下标 |
+| `rowNode` | `RowNode` | 行节点快照 |
+| `colId` | `string` | 触发点击/双击的列 id |
+
+> 不含分组头行、详情行、表尾汇总行。
+
+#### `selection-changed`
+
+payload 为 `SelectionChangedEvent`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `selectedRowIds` | `BusinessRowId[]` | 当前 checkbox 选中的行 id 列表 |
+
+#### `index-focus-changed`
+
+payload 为 `IndexFocusChangedEvent`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `focusedRowIds` | `BusinessRowId[]` | 索引列辅助定位的行 id 列表 |
 
 ### 编辑
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `cell-editing-started` | `CellEditingStartedEvent` | 单元格进入编辑态 |
-| `cell-editing-stopped` | `CellEditingStoppedEvent` | 单元格退出编辑态 |
-| `cell-value-changed` | `CellValueChangedEvent` | 单元格值已提交变更 |
-| `cell-commit-started` | `CellCommitStartedEvent` | 单元格异步提交开始 |
-| `cell-commit-finished` | `CellCommitFinishedEvent` | 单元格异步提交完成 |
-| `edit-commit-aborted` | `EditCommitAbortedEvent` | 异步提交被中断 |
-| `row-editing-started` | `RowEditingStartedEvent` | 行进入编辑态 |
-| `row-editing-stopped` | `RowEditingStoppedEvent` | 行退出编辑态 |
-| `row-value-changed` | `RowValueChangedEvent` | 行编辑整行提交 |
-| `row-commit-started` | `RowCommitStartedEvent` | 行异步提交开始 |
-| `row-commit-finished` | `RowCommitFinishedEvent` | 行异步提交完成 |
+#### `cell-editing-started`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 行 id |
+| `colId` | `string` | 列 id |
+| `rowIndex` | `number` | 行下标 |
+| `value` | `unknown` | 进入编辑时的值 |
+
+#### `cell-editing-stopped`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `colId` / `rowIndex` | — | 格位置 |
+| `committed` | `boolean` | 是否成功提交 |
+| `oldValue` / `newValue` | `unknown` | 编辑前后值 |
+
+#### `cell-value-changed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `colId` | — | 格位置 |
+| `oldValue` / `newValue` | `unknown` | 变更前后值 |
+| `rowNode` | `RowNode` | 行节点快照 |
+
+#### `cell-commit-started` / `cell-commit-finished`
+
+异步提交生命周期：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `colId` / `rowIndex` | — | 格位置 |
+| `committed` | `boolean` | （finished）是否成功提交 |
+| `aborted` | `boolean` | （finished）是否被中断 |
+
+#### `edit-commit-aborted`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `colId` / `rowIndex` | 可选 | 被中断的编辑格 |
+
+#### `row-editing-started`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `rowIndex` | — | 行位置 |
+| `editableColIds` | `string[]` | 该行可编辑列 id 列表 |
+
+#### `row-editing-stopped`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `rowIndex` | — | 行位置 |
+| `committed` | `boolean` | 是否成功提交 |
+| `changes` | `RowEditChange[]` | 变更列列表（`colId` / `oldValue` / `newValue`） |
+
+#### `row-value-changed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `rowIndex` | — | 行位置 |
+| `rowNode` | `RowNode` | 行节点快照 |
+| `data` | `RowData` | 提交后的行数据 |
+| `changes` | `RowEditChange[]` | 变更列列表 |
+
+#### `row-commit-started` / `row-commit-finished`
+
+行级异步提交，字段语义同单元格 commit 事件。
 
 ### 校验
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `cell-validation-failed` | `CellValidationFailedEvent` | 单元格校验失败 |
-| `row-validation-failed` | `RowValidationFailedEvent` | 行校验失败 |
+#### `cell-validation-failed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `colId` / `rowIndex` | — | 格位置 |
+| `errors` | `string[]` | 错误消息列表 |
+| `mode` | `'block' \| 'revert' \| 'keep'` | 当前 `invalidEditValueMode` |
+
+#### `row-validation-failed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `rowIndex` | — | 行位置 |
+| `failedColId` | `string` | 首个失败列 id |
+| `cellErrors` | `{ colId, errors }[]` | 各列错误（可选） |
+| `rowErrors` | `string[]` | 行级校验错误（可选） |
+| `mode` | `'block' \| 'revert' \| 'keep'` | 当前 invalid 模式 |
 
 ### 排序与筛选
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `sort-changed` | `SortModelItem[]` | 排序模型变更 |
-| `filter-changed` | `FilterModel` | 筛选模型变更 |
+#### `sort-changed`
+
+payload 为 `SortModelItem[]`（v1 至多 1 项）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `colId` | `string` | 排序列 id |
+| `sort` | `'asc' \| 'desc'` | 排序方向 |
+
+#### `filter-changed`
+
+payload 为 `FilterModel`（`Record<colId, FilterCondition>`）。各列条件结构因 `filterType` 而异（text / number / date / set / custom）。
 
 ### 列
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `column-moved` | `ColumnMovedEvent` | 列拖拽重排完成 |
-| `column-resized` | `ColumnResizedEvent` | 列宽调整 |
-| `column-pinned` | `ColumnPinnedEvent` | 列固定状态变更 |
-| `column-hidden-changed` | `ColumnHiddenChangedEvent` | 列显隐变更 |
+#### `column-moved`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `columnOrder` | `string[]` | 移动后的完整 colId 顺序（含系统列） |
+| `fromColId` | `string` | 被移动列 id |
+| `toIndex` | `number` | 目标全局下标 |
+| `finished` | `boolean` | `false` = drag 中 live move；`true` = mouseup 最终提交 |
+| `toFixed` | `'left' \| 'right' \| null` | 跨 lane 时移动列的新 fixed（lane 内省略） |
+
+#### `column-resized`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `columns` | `{ colId, width }[]` | 本次宽度变化的列 |
+| `column` | `{ colId, width } \| null` | 仅单列变化时的便捷引用 |
+| `finished` | `boolean` | 拖拽过程 / 最终提交 |
+| `flexColumns` | `{ colId, width }[] \| null` | flex 被动调整的列 |
+| `source` | `ColumnResizeSource` | 触发来源（ui / api / autosize 等） |
+
+#### `column-pinned`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `colId` | `string` | 列 id |
+| `pinned` | `'left' \| 'right' \| null` | 新的 fixed 状态 |
+| `source` | `string` | 变更来源 |
+
+#### `column-hidden-changed`
+
+批量列显隐变更（**仅 `hidden` 列** · 不对 `available: false` 列触发）。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `colIds` | `string[]` | 受影响的列 id |
+| `hidden` | `boolean` | 新的 hidden 状态 |
+| `source` | `'api' \| 'columnDefs' \| 'menu'` | 变更来源 |
 
 ### 行 CRUD 与拖拽
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `rows-added` | `RowsAddedEvent` | 行新增 |
-| `rows-removed` | `RowsRemovedEvent` | 行删除 |
-| `row-id-promoted` | `RowIdPromotedEvent` | 临时行 ID 提升为正式主键 |
-| `row-moved` | `RowMovedEvent` | 编程式或 UI 行移动 |
-| `row-drag-end` | `RowDragEndEvent` | 行拖拽结束（`rowDragManaged: false` 时由业务改序） |
-| `row-drag-commit-started` | `RowDragCommitStartedEvent` | deferred 模式 commit 开始 |
-| `row-drag-commit-finished` | `RowDragCommitFinishedEvent` | deferred 模式 commit 完成 |
-| `row-height-changed` | `RowHeightChangedEvent` | 行高变更 |
+#### `rows-added`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rows` | `RowMutationRowSnapshot[]` | 新增行快照（含 `rowId` / `data`） |
+
+#### `rows-removed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rows` | `RowMutationRemovedSnapshot[]` | 删除行快照 |
+
+#### `row-id-promoted`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `oldRowId` | `BusinessRowId` | 临时 id（`__mg_tmp_*`） |
+| `newRowId` | `BusinessRowId` | 正式业务主键 |
+| `data` | `RowData` | 更新后的行数据 |
+
+#### `row-moved`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 被移动行 id |
+| `fromIndex` / `toIndex` | `number` | source 顺序下的起止下标 |
+| `source` | `RowMoveSource` | `'uiRowDrag'` / `'api'` 等 |
+| `finished` | `boolean` | live drag 中间态为 `false` |
+
+#### `row-drag-end`
+
+`rowDragManaged: false` 时由业务自行改序。payload 为 `RowDragEndEvent`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 被拖拽行 id |
+| `rowIds` | `BusinessRowId[]` | 多行 drag 时的全部 id |
+| `displayIndex` | `number` | drop 时 display 插入位；`-1` = 无效 |
+| `finished` | `boolean` | 是否 mouseup 最终提交 |
+| `parentRowId` / `siblingIndex` / `treeLevel` | 可选 | 树形 drop 上下文 |
+
+#### `row-drag-commit-started` / `row-drag-commit-finished`
+
+deferred 模式（`rowDragCommitMode: 'deferred'`）commit 生命周期事件。
+
+#### `row-height-changed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 行 id |
+| `height` | `number` | 新的行高 px |
+| `finished` | `boolean` | resize 过程 / 最终提交 |
+| `source` | `string` | 触发来源 |
 
 ### 展开行
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `row-expanded` | `RowExpansionChangedEvent` | 主行展开 |
-| `row-collapsed` | `RowExpansionChangedEvent` | 主行折叠 |
+#### `row-expanded` / `row-collapsed`
+
+payload 为 `RowExpansionChangedEvent`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 主行 id |
+| `expanded` | `boolean` | 展开 / 折叠 |
 
 ### 行分组
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `row-group-opened` | `RowGroupOpenedEvent` | 分组节点展开/折叠 |
-| `row-group-changed` | `RowGroupChangedEvent` | 分组列配置变更 |
+#### `row-group-opened`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `groupId` | `string` | 分组节点 id |
+| `expanded` | `boolean` | 展开 / 折叠 |
+| `field` | `string` | 分组字段 |
+| `key` | `string` | 分组键值 |
+| `level` | `number` | 分组层级 |
+| `source` | `RowGroupingSource` | 触发来源 |
+
+#### `row-group-changed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `columns` | `string[]` | 当前分组列 id 列表 |
+| `source` | `RowGroupingSource` | 触发来源 |
 
 ### 树形表格
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `tree-node-opened` | `TreeNodeOpenedEvent` | 树节点展开/折叠 |
-| `tree-children-loading` | `TreeChildrenLoadingEvent` | 懒加载子节点开始 |
-| `tree-children-loaded` | `TreeChildrenLoadedEvent` | 懒加载子节点成功 |
-| `tree-children-load-failed` | `TreeChildrenLoadFailedEvent` | 懒加载子节点失败 |
+#### `tree-node-opened`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 节点 id |
+| `expanded` | `boolean` | 展开 / 折叠 |
+| `level` | `number` | 树层级 |
+| `dataPath` | `string[]` | 节点路径 |
+| `source` | `TreeTableSource` | 触发来源 |
+
+#### `tree-children-loading`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `parentRowId` | `BusinessRowId` | 父节点 id |
+| `dataPath` | `string[]` | 父节点路径 |
+| `treeLevel` | `number` | 树层级 |
+| `source` | `TreeTableSource` | 触发来源 |
+
+#### `tree-children-loaded`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `parentRowId` | `BusinessRowId` | 父节点 id |
+| `children` | `RowData[]` | 加载的子行数据 |
+| `childCount` | `number` | 子行数量 |
+| `source` | `TreeTableSource` | 触发来源 |
+
+#### `tree-children-load-failed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `parentRowId` | `BusinessRowId` | 父节点 id |
+| `reason` | `string` | 失败原因（可选） |
+| `aborted` | `boolean` | 是否被中断 |
 
 ### 批注
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `cell-comment-changed` | `CellCommentChangedEvent` | 单元格批注变更 |
+#### `cell-comment-changed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` / `colId` | — | 格位置 |
+| `comment` | `CellComment \| undefined` | 新批注；`undefined` 表示删除 |
 
 ### 框选
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `cell-selection-changed` | `CellSelectionChangedEvent` | 框选范围变更 |
-| `cell-selection-delete-start` | `CellSelectionDeleteStartEvent` | Delete 清空选区开始 |
-| `cell-selection-delete-end` | `CellSelectionDeleteEndEvent` | Delete 清空选区结束 |
+#### `cell-selection-changed`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ranges` | `CellRange[]` | 当前选区列表 |
+| `source` | `CellSelectionSource` | 变更来源（ui / api 等） |
+
+`CellRange`：`{ startRowIndex, endRowIndex, startColId, endColId }`。
+
+#### `cell-selection-delete-start` / `cell-selection-delete-end`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ranges` | `CellRange[]` | 被清空的选区 |
+| `changedCellCount` | `number` | （end）实际变更的格数 |
 
 ### 空态
 
-| 事件 | payload | 说明 |
-|------|---------|------|
-| `overlay-shown` | `OverlayShownEvent` | overlay 显示 |
-| `overlay-hidden` | `OverlayHiddenEvent` | overlay 隐藏 |
+#### `overlay-shown` / `overlay-hidden`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `overlayType` | `'loading' \| 'noRows' \| 'noMatchingRows'` | overlay 类型 |
 
 ### 事件监听示例
 
@@ -1025,41 +1530,44 @@ MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 keba
 />
 ```
 
-除 Vue 事件外，也可通过 `gridRef.api` 订阅内核事件（见 [Expose](#expose)）。
-
 ---
 
 ## Expose
 
 通过组件 `ref` 获取 `MagicGridExpose` 实例，进行命令式操作。
 
+### MagicGridExpose 方法
+
+| 成员 | 类型 | 说明 |
+|------|------|------|
+| `api` | `Ref<GridApi \| undefined>` | GridApi 实例；挂载完成后可用 |
+| `getMetrics()` | `() => GridMetrics \| undefined` | 读取渲染与滚动指标（同 `scroll` / `data-rendered` 事件 payload） |
+| `scrollTo(scrollTop, scrollLeft?)` | `(number, number?) => void` | 编程式滚动；scrollLeft 省略时保持当前值 |
+| `setSortModel(model)` | `(SortModelItem[]) => void` | 设置排序模型并重算 display 行 |
+| `getSortModel()` | `() => SortModelItem[]` | 读取当前排序模型 |
+| `setFilterModel(model)` | `(FilterModel) => void` | 设置筛选模型并重算 display 行 |
+| `getData(options?)` | `(GetDataOptions?) => RowData[]` | 导出业务数据；等价于 `api.getData()` |
+| `applyTransaction(tx)` | `(RowTransaction) => Promise<RowNodeTransaction \| undefined>` | 增量事务 add/update/remove |
+| `beginUpdate()` | `() => void` | 开启批量更新；与 `endUpdate` 配对 |
+| `endUpdate()` | `() => void` | 结束批量更新并 flush 累积变更 |
+| `ensureIndexVisible(index, position?)` | `(number, 'top'\|'bottom'\|'middle'?) => void` | 滚动使行下标进入视口；position 默认 `'middle'` |
+| `flushFrames()` | `() => void` | 强制 flush 待渲染帧（测试/同步场景） |
+
 ### 类型定义
 
 ```ts
 interface MagicGridExpose {
-  /** GridApi 实例（Ref） */
   api: Ref<GridApi | undefined>
-  /** 读取渲染与滚动指标 */
   getMetrics: () => GridMetrics | undefined
-  /** 编程式滚动 */
   scrollTo: (scrollTop: number, scrollLeft?: number) => void
-  /** 设置排序模型 */
   setSortModel: (model: SortModelItem[]) => void
-  /** 读取排序模型 */
   getSortModel: () => SortModelItem[]
-  /** 设置筛选模型 */
   setFilterModel: (model: FilterModel) => void
-  /** 导出当前表格业务数据 */
   getData: (options?: GetDataOptions) => RowData[]
-  /** 增量事务：add / update / remove */
   applyTransaction: (transaction: RowTransaction) => Promise<RowNodeTransaction | undefined>
-  /** 开启批量更新（与 endUpdate 配对） */
   beginUpdate: () => void
-  /** 结束批量更新并 flush */
   endUpdate: () => void
-  /** 滚动使指定行下标进入视口 */
   ensureIndexVisible: (index: number, position?: 'top' | 'bottom' | 'middle') => void
-  /** 强制 flush 待渲染帧 */
   flushFrames: () => void
 }
 ```
@@ -1095,109 +1603,109 @@ function scrollToRow(index: number) {
 
 ### GridApi（`gridRef.api`）
 
-`api` 是完整的命令式 API 面，按职责分组如下。完整参考见 [`docs/16-grid-api-reference.md`](docs/16-grid-api-reference.md)。
+`api` 是完整的命令式 API 面。以下按职责分组列出全部公开方法；入参 rowId 均接受 `string | number`，出参 rowId 恒为 `string`。
 
 #### 数据
 
-| 方法 | 说明 |
-|------|------|
-| `setData(rows)` | 全量替换表格数据 |
-| `applyTransaction(tx)` | 增量事务 add/update/remove |
-| `addRows(options)` | 在指定位置插入行 |
-| `removeRows(options)` | 按 rowId 或下标删除行 |
-| `getData(options?)` | 导出业务层 RowData[] |
-| `promoteRowId(options)` | 临时行 ID 提升为正式主键 |
-| `moveRow(rowId, toIndex, indexMode?)` | 编程式移动行 |
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `setData(rows)` | `RowData[]` | `void` | 全量替换数据；触发完整重绘 |
+| `applyTransaction(tx)` | `{ add?, update?, remove? }` | `Promise<RowNodeTransaction>` | 增量事务 add/update/remove |
+| `addRows(options)` | `AddRowsOptions` | `Promise<RowNodeTransaction>` | 指定位置插入行；省略 rowKey 生成临时行 |
+| `removeRows(options)` | `{ rowIds?, indexes?, indexMode? }` | `Promise<RowNodeTransaction>` | 按 rowId 或下标删除 |
+| `getData(options?)` | `{ sourceOrder?: boolean }` | `RowData[]` | 导出业务数据；默认 source 顺序 |
+| `promoteRowId(options)` | `{ rowId, businessId }` | `PromoteRowIdResult` | 临时 id 提升为正式主键 |
+| `moveRow(rowId, toIndex, indexMode?)` | rowId / 目标下标 / `'source'\|'display'` | `RowMoveResult` | 编程式移动行 |
 
 #### 排序 / 筛选
 
-| 方法 | 说明 |
-|------|------|
-| `setSortModel(model)` / `getSortModel()` | 排序模型读写 |
-| `setFilterModel(model)` / `getFilterModel()` | 筛选模型读写 |
-| `setColumnFilter(colId, condition)` | 设置单列筛选 |
-| `getColumnFilter(colId)` | 读取单列筛选条件 |
-| `isColumnFilterActive(colId)` | 单列是否有有效筛选 |
-| `isAnyFilterActive()` | 任一列 filter 或 quick filter 是否 active |
-| `setQuickFilterText(text)` / `getQuickFilterText()` | Quick filter 读写 |
-| `clearAllFilters()` | 清除全部筛选 |
-| `getColumnDistinctFilterValues(colId)` | 列 distinct 值（set filter 勾选列表） |
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `setSortModel(model)` / `getSortModel()` | `SortModelItem[]` | 排序模型读写；触发 `sortChanged` |
+| `setFilterModel(model)` / `getFilterModel()` | `FilterModel` | 筛选模型读写；触发 `filterChanged` |
+| `setColumnFilter(colId, condition)` | condition 或 `null` 清除 | 设置单列筛选 |
+| `getColumnFilter(colId)` | — | 读取单列条件；未设置返回 `null` |
+| `isColumnFilterActive(colId)` | — | 单列是否有有效筛选 |
+| `isAnyFilterActive()` | — | 任一列 filter 或 quick filter 是否 active |
+| `setQuickFilterText(text)` / `getQuickFilterText()` | `string` | Quick filter 读写 |
+| `clearAllFilters()` | — | 清除全部列筛选 + quick filter |
+| `getColumnDistinctFilterValues(colId)` | — | 列 distinct 值（set filter 勾选列表） |
 
 #### 列
 
-| 方法 | 说明 |
-|------|------|
-| `moveColumn(colId, toIndex)` | 编程式移动列 |
-| `resetColumnOrder()` | 各 lane 内用户列恢复 defOrder |
-| `resetColumnWidths()` | 用户列恢复 defWidth/defFlex |
-| `setColumnFixed(colId, fixed)` | 运行时改列 fixed |
-| `setColumnsHidden(colIds, hidden)` | 批量设置列 hidden |
-| `isColumnHidden(colId)` | 列是否 hidden |
-| `getDisplayedColumnIds()` | 当前 UI 展示的列 id |
-| `getColumns()` / `getDisplayedColumns()` | 全量列 / 展示列 |
-| `setColumnWidth(colId, width, finished?, source?)` | 设置单列宽度 |
-| `setColumnWidths(payloads, finished?, source?)` | 批量设置列宽 |
-| `getColumnWidth(colId)` | 读取列当前像素宽度 |
-| `autoSizeColumn(colId, skipHeader?)` | 按内容自动调整列宽 |
-| `autoSizeColumns(colIds, skipHeader?)` | 批量 auto-size |
-| `sizeColumnsToFit(params?)` | 列宽按比例分配至视口 |
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `moveColumn(colId, toIndex)` | 全局 columns 下标 | 编程式移动列 |
+| `resetColumnOrder()` | — | 各 lane 内用户列恢复 defOrder |
+| `resetColumnWidths()` | — | 用户列恢复 defWidth/defFlex |
+| `setColumnFixed(colId, fixed)` | `'left' \| 'right' \| null` | 运行时改列 fixed |
+| `setColumnsHidden(colIds, hidden)` | — | 批量设置列 hidden（仅对列模型中存在的列生效） |
+| `isColumnHidden(colId)` | — | 列是否 hidden |
+| `getDisplayedColumnIds()` | — | 当前 UI 展示列 id（左→右 · 跳过 hidden） |
+| `getColumns()` / `getDisplayedColumns()` | — | 全量列（含 hidden · 不含 `available: false`）/ 展示列（不含 hidden） |
+| `setColumnWidth(colId, width, finished?, source?)` | finished 默认 `true` | 设置单列宽度 |
+| `setColumnWidths(payloads, finished?, source?)` | `{ colId, width }[]` | 批量设置列宽 |
+| `getColumnWidth(colId)` | — | 读取列当前像素宽度 |
+| `autoSizeColumn(colId, skipHeader?)` | skipHeader 默认 `false` | 按内容 auto-size |
+| `autoSizeColumns(colIds, skipHeader?)` | — | 批量 auto-size |
+| `sizeColumnsToFit(params?)` | `SizeColumnsToFitParams` | 列宽按比例分配至视口 |
 
 #### 行高
 
-| 方法 | 说明 |
-|------|------|
-| `setRowHeight(rowId, height, finished?)` | 设置单行高度 |
-| `setRowHeights(changes, finished?)` | 批量设置行高 |
-| `getRowHeight(rowId)` | 读取行当前有效高度 |
-| `resetRowHeights(rowIds?)` | 清除 pinned 并重算行高 |
-| `updateDimensions(params)` | 热更新默认行高与 clamp 边界 |
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `setRowHeight(rowId, height, finished?)` | finished 默认 `true` | 设置单行高度并 pinned |
+| `setRowHeights(changes, finished?)` | `{ rowId, height }[]` | 批量设置行高 |
+| `getRowHeight(rowId)` | — | 读取行当前有效高度；不存在返回 `null` |
+| `resetRowHeights(rowIds?)` | 省略则全部 | 清除 pinned 并重算行高 |
+| `updateDimensions(params)` | `{ rowHeight?, rowHeightMin?, rowHeightMax? }` | 热更新默认行高与 clamp |
 
 #### 渲染 / 视口
 
-| 方法 | 说明 |
-|------|------|
-| `refreshCells(params?)` | 刷新指定行或列的单元格 DOM |
-| `refreshCellSpans()` | 强制重建单元格合并 cache |
-| `getCellSpan(rowId, colId)` | 查询 span 信息 |
-| `ensureIndexVisible(index, position?)` | 滚动使行下标进入视口 |
-| `getRowNode(id)` | 按 rowId 获取行节点快照 |
-| `getMetrics()` | 读取渲染与滚动指标 |
-| `beginUpdate()` / `endUpdate()` | 批量更新 |
-| `scrollTo(scrollTop, scrollLeft?)` | 编程式滚动 |
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `refreshCells(params?)` | `{ rowIds?, colIds?, force? }` | `number` | 刷新指定格 DOM |
+| `refreshCellSpans()` | — | `void` | 强制重建合并 cache |
+| `getCellSpan(rowId, colId)` | — | `CellSpanInfo \| null` | 查询 span 信息 |
+| `ensureIndexVisible(index, position?)` | position 默认 `'middle'` | `void` | 滚动使行下标进入视口 |
+| `getRowNode(id)` | rowId | `RowNode \| undefined` | 按 id 获取行节点 |
+| `getMetrics()` | — | `GridMetrics` | 读取渲染与滚动指标 |
+| `beginUpdate()` / `endUpdate()` | — | `void` | 批量更新（与 applyTransaction 配对） |
+| `scrollTo(scrollTop, scrollLeft?)` | px | `void` | 编程式滚动 |
 
 #### 编辑
 
-| 方法 | 说明 |
-|------|------|
-| `startEditingCell({ rowIndex, colKey })` | 编程式进入单元格编辑 |
-| `stopEditing(cancel?)` | 结束当前编辑会话 |
-| `isEditing()` | 是否存在编辑态 |
-| `isCommitting()` | 是否正在异步提交 |
-| `cancelCommit()` | 中断进行中的异步提交 |
-| `getEditSessionPhase()` | 当前编辑会话阶段 |
-| `getEditingCell()` | 当前主编辑单元格 |
-| `getEditingCells()` | 行编辑模式下所有编辑单元格 |
-| `registerCellEditor(name, editor)` | 注册命名单元格编辑器 |
-| `unregisterCellEditor(name)` | 注销实例级编辑器 |
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `startEditingCell({ rowIndex, colKey })` | colKey = colId 或 prop | `void` | 编程式进入编辑 |
+| `stopEditing(cancel?)` | cancel 默认 `false` | `Promise<void>` | 结束编辑；`true` 丢弃修改 |
+| `isEditing()` | — | `boolean` | 是否存在编辑态 |
+| `isCommitting()` | — | `boolean` | 是否正在异步提交 |
+| `cancelCommit()` | — | `void` | 中断异步提交 |
+| `getEditSessionPhase()` | — | `'idle' \| 'editing' \| 'committing' \| 'cancelling'` | 编辑会话阶段 |
+| `getEditingCell()` | — | `{ rowId, colId } \| null` | 当前主编辑格 |
+| `getEditingCells()` | — | `EditingCellPosition[]` | 行编辑模式下全部编辑格 |
+| `registerCellEditor(name, editor)` | — | `void` | 注册实例级命名编辑器 |
+| `unregisterCellEditor(name)` | — | `boolean` | 注销实例级编辑器 |
 
 #### 校验
 
-| 方法 | 说明 |
-|------|------|
-| `validate(options?)` | 校验全表或指定行 |
-| `validateRows(options)` | 校验指定行列表 |
-| `validateCells(options)` | 校验指定单元格列表 |
-| `clearValidation(options?)` | 清除校验视觉反馈 |
-| `clearRowValidation(options)` | 清除指定行校验反馈 |
-| `clearCellValidation(options)` | 清除指定单元格校验反馈 |
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `validate(options?)` | `ValidateGridOptions` | `Promise<GridValidationResult>` | 校验全表或指定行 |
+| `validateRows(options)` | rowIds 必填 | `Promise<GridValidationResult>` | 校验指定行 |
+| `validateCells(options)` | cells 必填 | `Promise<GridValidationResult>` | 校验指定格 |
+| `clearValidation(options?)` | — | `void` | 清除校验视觉反馈 |
+| `clearRowValidation(options)` | rowIds 必填 | `void` | 清除指定行反馈 |
+| `clearCellValidation(options)` | cells 必填 | `void` | 清除指定格反馈 |
 
 #### 行选择 / 索引定位
 
-| 方法 | 说明 |
-|------|------|
-| `toggleRowSelection(rowIds, selected?, force?)` | 切换或设置行 checkbox 选中 |
-| `toggleAllSelection(selected?)` | 表头全选 checkbox 操作 |
-| `setIndexFocus(rowIds)` | 设置索引列辅助定位 |
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `toggleRowSelection(rowIds, selected?, force?)` | selected 省略时 toggle | 切换/设置 checkbox 选中 |
+| `toggleAllSelection(selected?)` | 仅 multiple 模式 | 表头全选操作 |
+| `setIndexFocus(rowIds)` | — | 设置索引列辅助定位 |
 
 #### 展开 / 分组 / 树
 
@@ -1219,9 +1727,12 @@ function scrollToRow(index: number) {
 |------|------|
 | `getCellComment(rowId, colId)` / `setCellComment(...)` | 批注读写 |
 | `refreshCellComments(params?)` | 刷新批注角标 |
-| `getCellRanges()` / `clearCellSelection()` / `addCellRange(params)` | 框选操作 |
-| `getCellSelectionAggregation()` | 当前框选聚合统计 |
-| `copySelectedRangeToClipboard()` / `pasteFromClipboard()` | 剪贴板操作 |
+| `getCellRanges()` | 读取当前框选 range 列表 |
+| `clearCellSelection()` | 清除框选 |
+| `addCellRange(params)` | 编程式添加 range |
+| `getCellSelectionAggregation()` | 选区聚合统计（count / sum / average） |
+| `copySelectedRangeToClipboard()` | 复制选区至剪贴板 |
+| `pasteFromClipboard()` | 从剪贴板粘贴至选区 |
 | `showLoadingOverlay()` / `showNoRowsOverlay()` / `hideOverlay()` | overlay 控制 |
 | `isOverlayShowing()` / `getOverlayType()` | overlay 状态查询 |
 | `refreshDisabledState(params?)` | 重算 disabled 投影 |
@@ -1229,13 +1740,24 @@ function scrollToRow(index: number) {
 
 #### 事件订阅
 
+GridApi 支持 `on(eventType, handler)` 订阅内核事件（camelCase），返回取消函数：
+
+| 内核事件名 | 对应 Vue 事件 |
+|------------|---------------|
+| `selectionChanged` | `selection-changed` |
+| `cellValueChanged` | `cell-value-changed` |
+| `sortChanged` | `sort-changed` |
+| `filterChanged` | `filter-changed` |
+| `columnMoved` | `column-moved` |
+| `cellSelectionChanged` | `cell-selection-changed` |
+| … | 其余见 [Events](#events) |
+
 ```ts
 const api = gridRef.value?.api
 const off = api?.on('selectionChanged', (event) => {
   console.log(event.selectedRowIds)
 })
-// 取消订阅
-off?.()
+off?.() // 取消订阅
 ```
 
 ### rowId 约定
@@ -1248,7 +1770,23 @@ off?.()
 
 ## Slots
 
-MagicGrid 提供静态插槽与动态列插槽两类。
+MagicGrid 提供**静态插槽**（固定名称）与**动态列插槽**（`#cell-{colId}` / `#cell-editor-{colId}`）两类。插槽与同名 prop / 列配置的优先级见文末 [插槽优先级说明](#插槽优先级说明)。
+
+### 插槽一览
+
+| 插槽名 | 类型 | 说明 |
+|--------|------|------|
+| `#toolbar` | 静态 | 表格顶部工具栏 |
+| `#status-bar` | 静态 | 完全自定义底部状态栏（提供时替换默认布局） |
+| `#status-bar-left` | 静态 | 默认状态栏左侧区域 |
+| `#status-bar-right` | 静态 | 默认状态栏右侧区域 |
+| `#cell-{colId}` | 动态 | 自定义单元格渲染 |
+| `#cell-editor-{colId}` | 动态 | 自定义单元格编辑器 |
+| `#detail-row` | 静态 | 主从展开行详情区 |
+| `#tooltip` | 静态 | 全局自定义 tooltip |
+| `#loading` | 静态 | loading overlay 内容 |
+| `#no-rows` | 静态 | 无数据 overlay 内容 |
+| `#no-matching-rows` | 静态 | 筛选无匹配 overlay 内容 |
 
 ### 布局插槽
 
@@ -1588,7 +2126,7 @@ const gridRef = ref<MagicGridExpose>()
 
 ### ColumnSettingsPanel
 
-列设置面板本体。按 **左固定 / 中心 / 右固定 / 隐藏** 四组展示用户列，每行支持拖拽排序、排序切换、筛选面板、固定列、显隐控制；面板头部提供「清除全部筛选」。
+列设置面板本体。按 **左固定 / 中心 / 右固定 / 隐藏** 四组展示**已注册进列模型**的用户列（`available: false` 的列不会出现）；每行支持拖拽排序、排序切换、筛选面板、固定列、显隐控制；面板头部提供「清除全部筛选」。
 
 > 通常由 `ColumnSettingsButton` 内嵌使用；也可单独 import 嵌入任意容器。
 
@@ -1600,7 +2138,7 @@ const gridRef = ref<MagicGridExpose>()
 | 列排序 | 点击循环 none → asc → desc | `setSortModel` |
 | 列筛选 | 行内展开筛选面板（与表头 filter 同源） | `setColumnFilter` / `clearAllFilters` |
 | 列固定 | 切换 null / left / right | `setColumnFixed` |
-| 列显隐 | checkbox 切换 hidden | `setColumnsHidden` |
+| 列显隐 | checkbox 切换 `hidden`（不含 `available: false` 列） | `setColumnsHidden` |
 | 清除全部筛选 | 面板头部按钮 | `clearAllFilters` |
 | 显示全部隐藏列 | hidden 分组底部操作 | `setColumnsHidden(colIds, false)` |
 
@@ -1731,24 +2269,14 @@ import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid'
 
 ---
 
-## 相关文档
-
-| 文档 | 说明 |
-|------|------|
-| [`docs/README.md`](docs/README.md) | 内部设计文档索引（架构、里程碑、AG Grid 对照） |
-| [`docs/16-grid-api-reference.md`](docs/16-grid-api-reference.md) | GridApi 完整参考 |
-| [`docs/07-third-party-cell-editor-guide.md`](docs/07-third-party-cell-editor-guide.md) | 第三方编辑器接入（Element Plus 等） |
-| [`docs/35-phase24-cell-range-selection.md`](docs/35-phase24-cell-range-selection.md) | 单元格框选与剪贴板（Phase 24） |
-| [`docs/39-phase27-table-settings-button.md`](docs/39-phase27-table-settings-button.md) | 列设置按钮设计文档（Phase 27） |
+## 校验子路径
 
-### 校验子路径
+配合 `ColumnDef.validationRules` 使用 async-validator 规则时，可通过子路径导入列 enrich 工具：
 
 ```ts
 import { enrichColumnsWithValidation } from '@taocompany/magic-grid/validation'
 ```
 
-配合 `ColumnDef.validationRules` 使用 async-validator 规则。
-
 ---
 
 ## License