@taocompany/magic-grid 0.1.6 → 0.3.0

package/README.md

@@ -5,21 +5,32 @@
 ## 目录
 
 - [概述](#概述)
+- [架构与设计](#架构与设计)
 - [快速开始](#快速开始)
+- [数据与性能最佳实践](#数据与性能最佳实践)
+- [默认配置](#默认配置)
 - [Props](#props)
   - [MagicGrid Props](#magicgrid-props)
     - [Grid 级默认与列级覆盖](#grid-级默认与列级覆盖)
   - [ColumnDef 列定义](#columndef-列定义)
+    - [列有效性与显隐](#列有效性与显隐)
 - [Options 类型参考](#options-类型参考)
+- [筛选模型参考](#筛选模型参考)
 - [Events](#events)
 - [Expose](#expose)
 - [Slots](#slots)
+- [单元格编辑](#单元格编辑)
+- [数据校验](#数据校验)
+- [键盘导航与快捷键](#键盘导航与快捷键)
 - [辅助组件](#辅助组件)
   - [ColumnSettingsButton](#columnsettingsbutton)
   - [ColumnSettingsPanel](#columnsettingspanel)
   - [ColumnSettingsMenuItem](#columnsettingsmenuitem)
   - [ColumnSettingsMenuIcon](#columnsettingsmenuicon)
-- [相关文档](#相关文档)
+- [包入口与导出](#包入口与导出)
+- [TypeScript 集成](#typescript-集成)
+- [类型与校验子路径](#类型与校验子路径)
+- [本地开发与 Playground](#本地开发与-playground)
 
 ---
 
@@ -32,9 +43,12 @@
 | **性能** | 行/列双轴虚拟化、DOM 池复用、RAF 帧预算分片、增量数据管线 |
 | **数据** | 排序、列筛选、Quick Filter、事务增量更新（`applyTransaction`）、行 CRUD |
 | **交互** | 单元格/行编辑、校验、行选择、索引列定位、框选与剪贴板 |
-| **布局** | 固定列、列拖拽/调整宽度、合并单元格、动态行高、主从展开行 |
+| **布局** | 固定列、列拖拽/调整宽度、列有效性与显隐（`available` / `hidden`）、合并单元格、动态行高、主从展开行 |
 | **结构** | 行分组、树形表格（含懒加载）、表尾汇总 |
 | **体验** | 溢出 Tooltip、单元格批注、空态 Overlay、暗色主题、底部状态栏 |
+| **扩展** | 列设置面板、Vue 第三方编辑器 Composable、inline 常驻编辑器、async-validator 校验 |
+
+当前版本：**0.3.0**（`@taocompany/magic-grid`）。
 
 ### 环境要求
 
@@ -58,6 +72,40 @@ import '@taocompany/magic-grid/style.css'
 
 > **ColumnSettingsButton / ColumnSettingsPanel** 与 MagicGrid 共用同一份 `style.css`。按钮或下拉菜单若放在页头工具栏等 **MagicGrid 容器外**，同样必须引入该文件；样式 token 已在 `.mg-column-settings-button` / `.mg-column-settings-portal` 上自带 fallback，脱离 `.magic-grid` 也可正常显示。
 
+
+---
+
+## 架构与设计
+
+Magic Grid 采用 **命令式渲染内核 + Vue 薄封装** 的分层架构，对标 AG Grid 社区版 API 语义，渲染路径针对百万级行数据做了专门优化。
+
+### 分层结构
+
+| 层级 | 职责 | 关键模块 |
+|------|------|----------|
+| **Vue 层** | Props / Events / Slots 绑定、主题 CSS 变量、辅助 UI | `MagicGrid.vue`、ColumnSettings、StatusBar |
+| **Grid API** | 命令式数据、列、编辑、选择、框选 | `GridApi` |
+| **渲染引擎** | 双轴虚拟化、行 DOM 池、增量 cell 刷新 | `rowRenderer`、`rowPool` |
+| **数据管线** | 排序 / 筛选 / 分组 / 树形 / 映射 | pipeline stages |
+| **交互层** | 焦点、框选、编辑、拖拽、剪贴板、批注 | `gridInteraction` |
+
+### 渲染模型
+
+- **行虚拟化**：仅渲染视口 + `rowBuffer` 缓冲行；行 DOM 在行池内按 `rowKey` 复用，滚动时更新内容与位置。
+- **列布局**：左固定 / 中心 / 右固定三 lane；中心 lane 随横滚分配列宽。
+- **增量更新**：`applyTransaction`、`setData` 走 RowNode 增量管线；`beginUpdate` / `endUpdate` 可合并多次刷新。
+- **帧预算**：大批量 DOM 写入分片到 `requestAnimationFrame`；测试场景可调用 `flushFrames()` 同步 flush。
+
+### 数据管线顺序
+
+| 模式 | Stage 顺序 |
+|------|------------|
+| 扁平表格 | `sort` → `filter` → `map` |
+| 行分组 | `group` → `filter` → `sort` → `aggregate` → `map` |
+| 树形表格 | `tree` → `filter` → `sort` → `map` |
+
+`summaryScope: 'displayed'`、状态栏行数、框选聚合均基于 `rowsToDisplay`；`summaryScope: 'all'` 对 `sourceRows` 全量汇总（忽略 filter）。
+
 ---
 
 ## 快速开始
@@ -66,7 +114,7 @@ import '@taocompany/magic-grid/style.css'
 <script setup lang="ts">
 import { ref } from 'vue'
 import { MagicGrid } from '@taocompany/magic-grid'
-import type { ColumnDef, MagicGridExpose, RowData } from '@taocompany/magic-grid'
+import type { ColumnDef, MagicGridExpose, RowData } from '@taocompany/magic-grid/types/core'
 import '@taocompany/magic-grid/style.css'
 
 const gridRef = ref<MagicGridExpose>()
@@ -121,17 +169,250 @@ const columns: ColumnDef[] = [
 <MagicGrid :columns="columns" :data="data" row-key="id" height="400" />
 ```
 
+
+---
+
+## 数据与性能最佳实践
+
+### 行数据
+
+- **`data` 使用普通对象数组**，不要对行数据做 `reactive()` 深代理；Grid 内部维护 RowNode，深代理会显著拖慢增量更新。
+- **`rowKey` 必须稳定唯一**（业务主键）；临时新增行可省略主键，内核分配 `__mg_tmp_*`，落库后调用 `promoteRowId`。
+- **大批量写入**优先 `applyTransaction` 或 `beginUpdate` / `endUpdate` 包裹多次 API 调用，避免连续 `setData` 全量替换。
+
+### 列定义
+
+- 动态列用 `columns` prop 热更新即可；`available: false` 从模型裁剪，`hidden: true` 保留模型仅不渲染。
+- flex 列与固定 `width` 列混用时，剩余空间由 flex 权重分配；`sizeColumnsToFit` / `autoSizeStrategy` 可首屏自适应。
+- 需要权限裁剪时用 `available`，需要用户临时隐藏列时用 `hidden` + 列设置面板。
+
+### 性能提示
+
+- 避免在 `cellRenderer` / `formatter` / `valueGetter` 中创建重量级对象或触发外部副作用；这些函数在滚动时会高频调用。
+- 合并单元格（`enableCellSpan`）会启用 `style.top` 行定位并增加 span cache 开销，仅在确有需求时开启。
+- Playground 内置 `getMetrics()` 可观察 `activeDomRowCount`、`lastSetDataMs` 等指标；生产环境可通过 `scroll` / `data-rendered` 事件订阅。
+
+---
+
+## 默认配置
+
+以下为 `<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 无双三角提示 |
+
+### 编辑
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `editBehavior` | `'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%'` | 容器高度 |
@@ -190,7 +471,7 @@ const columns: ColumnDef[] = [
 | `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
 | `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
 | `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 #### 行选择
 
@@ -218,7 +499,7 @@ interface RowSelectionConfig {
 | `width` | `number` | `40` | 列宽 px（最小 40） |
 | `selectAllLabel` | `string` | `'全选'` | 表头全选 checkbox 的 aria-label |
 | `rowLabel` | `(rowIndex) => string` | — | 行 checkbox 的 aria-label 工厂 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 #### 表尾汇总
 
@@ -265,7 +546,7 @@ interface RowSelectionConfig {
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `editMode` | `'cell' \| 'row'` | `'cell'` | 编辑范围：单格 / 整行 |
+| `editBehavior` | `CellEditBehavior` | `'cell'` | 编辑范围：单格 / 整行 |
 | `editType` | `CellEditType` | `'singleClick'` | 进入编辑态的触发方式 |
 | `invalidEditValueMode` | `'block' \| 'revert' \| 'keep'` | `'block'` | 校验失败后：`block` 保持编辑；`revert` 退出并恢复旧值；`keep` 退出编辑但保留无效值 |
 | `rowValidator` | `RowValidator` | — | 行编辑跨字段校验 |
@@ -349,10 +630,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 +643,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 +700,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 +747,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`）。
 
 #### 尺寸
 
@@ -556,9 +879,9 @@ interface RowSelectionConfig {
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `headerAlign` / `headerValign` | 对齐枚举 | 表头对齐；默认 `center` |
-| `align` / `valign` | 对齐枚举 | 表体对齐；默认 `center` |
-| `footerAlign` / `footerValign` | 对齐枚举 | 表尾对齐；默认 `center` |
+| `headerAlign` / `headerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | 表头对齐；默认 `center` |
+| `align` / `valign` | `GridHorizontalAlign` / `GridVerticalAlign` | 表体对齐；默认 `center` |
+| `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | 表尾对齐；默认 `center` |
 
 #### 禁用与样式
 
@@ -601,7 +924,7 @@ interface RowSelectionConfig {
 | `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
 | `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
 | `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 ### SelectionColumnOptions
 
@@ -612,7 +935,7 @@ interface RowSelectionConfig {
 | `width` | `number` | `40` | 列宽 px（最小 40） |
 | `selectAllLabel` | `string` | `'全选'` | 表头全选 checkbox 的 aria-label |
 | `rowLabel` | `(rowIndex) => string` | — | 行 checkbox 的 aria-label 工厂 |
-| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | `GridHorizontalAlign` / `GridVerticalAlign` | `'center'` | 对齐配置 |
 
 ### RowSelectionConfig
 
@@ -634,21 +957,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
@@ -896,124 +1212,458 @@ type StatusBarRangeAggregationPrecisionInput =
 
 **ProcessDataFromClipboardParams**：`{ data: string[][], anchor: CellPosition }`，其中 `anchor` 为 `{ rowIndex, colId }`。
 
+
+---
+
+## 筛选模型参考
+
+筛选状态由 `FilterModel` 表示：`Record<colId, FilterCondition>`。通过 `setFilterModel` / `getFilterModel` / `filter-changed` 事件读写。
+
+### ColumnFilter（内置 UI / API 通用）
+
+单列条件结构（`filterType` 决定可用算子）：
+
+```ts
+interface ColumnFilter {
+  type: FilterType          // 算子，见下表
+  filter?: string           // 主比较值（文本 / 数字 / ISO 日期字符串）
+  filterTo?: string         // date inRange 第二端点
+  operator?: 'AND' | 'OR'   // 多条件组合，默认 AND
+  conditions?: ColumnFilterOperatorCondition[]  // 多条件列表，存在时优先于顶层 type/filter
+  setValues?: string[]      // 值选择：选中 key；缺省 = 全选（不约束）
+}
+```
+
+**文本列**（`filterType: 'text'`，默认）算子：
+
+| type | 说明 |
+|------|------|
+| `contains` / `notContains` | 包含 / 不包含 |
+| `equals` / `notEqual` | 等于 / 不等于 |
+| `startsWith` / `endsWith` | 前缀 / 后缀 |
+| `blank` / `notBlank` | 空 / 非空 |
+
+**数字列**（`filterType: 'number'`）额外支持：`lessThan`、`lessThanOrEqual`、`greaterThan`、`greaterThanOrEqual`。
+
+**日期列**（`filterType: 'date'`）v1 使用 ISO 文本（如 `2026-08-07`）；支持 `inRange`（需 `filter` + `filterTo`）。
+
+**值选择（set filter）**：表头 filter 面板勾选 distinct 值时写入 `setValues`；`filterSetValueMode: 'current'`（默认）在搜索时投影当前可见勾选，`'reserve'` 保留历史勾选。
+
+**Quick Filter**：Grid 级 `quickFilterText` 对全部 `filterable` 用户列做 OR 式 `contains`（不走 ColumnFilter 结构）。
+
+### CustomColumnFilter（编程式）
+
+```ts
+interface CustomColumnFilter {
+  predicate: (value: unknown, row: RowData) => boolean
+}
+```
+
+通过 `setColumnFilter(colId, { predicate: ... })` 设置；`getColumnFilter` 可读回。与内置 UI 筛选可并存（同一 colId 以后写入者为准）。
+
+### 示例
+
+```ts
+// 单列文本 contains
+api.setColumnFilter('name', { type: 'contains', filter: '张' })
+
+// 数字 greaterThanOrEqual
+api.setColumnFilter('amount', { type: 'greaterThanOrEqual', filter: '1000' })
+
+// 多条件 AND
+api.setColumnFilter('status', {
+  operator: 'AND',
+  conditions: [
+    { type: 'notEqual', filter: 'draft' },
+    { type: 'notEqual', filter: 'archived' },
+  ],
+})
+
+// 清除单列
+api.setColumnFilter('name', null)
+
+// 清除全部（含 quick filter）
+api.clearAllFilters()
+```
+
+---
+
 ---
 
 ## 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 +1675,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
 }
 ```
@@ -1069,7 +1722,7 @@ interface MagicGridExpose {
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import type { MagicGridExpose } from '@taocompany/magic-grid'
+import type { MagicGridExpose } from '@taocompany/magic-grid/types/core'
 
 const gridRef = ref<MagicGridExpose>()
 
@@ -1095,109 +1748,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 +1872,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 +1885,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 +1915,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 内容 |
 
 ### 布局插槽
 
@@ -1259,7 +1942,7 @@ MagicGrid 提供静态插槽与动态列插槽两类。
 | 插槽 prop | 类型 | 说明 |
 |-----------|------|------|
 | `api` | `GridApi \| undefined` | GridApi 实例 |
-| `size` | `MagicGridSize` | 当前尺寸 preset |
+| `size` | `GridSize` | 当前尺寸 preset |
 | `portalEl` | `HTMLElement \| undefined` | 浮层挂载 portal 元素 |
 
 ```vue
@@ -1418,6 +2101,228 @@ MagicGrid 提供静态插槽与动态列插槽两类。
 
 ---
 
+
+## 单元格编辑
+
+Magic Grid 支持 **overlay**（点击/Enter 进入编辑浮层）与 **inline**（控件常驻单元格内）两种呈现模式，以及内置编辑器、函数编辑器、Vue 组件编辑器与命名注册表。
+
+### 呈现模式：overlay 与 inline
+
+| 模式 | 配置 | 行为 |
+|------|------|------|
+| **overlay**（默认） | `cellEditorMode: 'overlay'` 或省略 | 非编辑态展示 formatter / cellRenderer；进入编辑态后在单元格上方挂载编辑器 |
+| **inline** | `cellEditorMode: 'inline'` + 必须配置 `cellEditor` | 编辑器始终渲染在格内；空格切换 checkbox；适合布尔列、简单输入 |
+
+**inline 限制**（开发模式会 console.warn）：
+
+- 系统列（索引 / 行选择）不支持 inline。
+- 推荐搭配内置 `'text'` / `'number'` / `'checkbox'`；依赖 teleport/下拉的第三方组件（如 Select）应使用 overlay + `useCellEditor({ strategy: 'overlay' })`。
+- inline 列通过 `params.commit()` / 空格（checkbox）提交；不走 overlay 的 Enter 捕获逻辑。
+
+```ts
+const columns: ColumnDef[] = [
+  { prop: 'done', label: '完成', width: 80, cellEditorMode: 'inline', cellEditor: 'checkbox' },
+  { prop: 'qty', label: '数量', cellEditorMode: 'inline', cellEditor: 'number', editable: true },
+]
+```
+
+Grid 级 `editBehavior: 'row'` 时整行同时进入编辑；Tab 在同行可编辑列间循环。`editType: 'doubleClick'` 改为双击进入编辑。
+
+### 内置编辑器
+
+| 名称 | 说明 |
+|------|------|
+| `'text'` | 单行文本 input |
+| `'number'` | `type="number"` input |
+| `'checkbox'` | 布尔 checkbox；inline 模式下空格切换 |
+
+列定义引用：`cellEditor: 'text'`。内置名不可用于 `registerCellEditor` 覆盖。
+
+### Vue 自定义编辑器
+
+包导出以下工具，用于集成 Element Plus 等 Vue 组件：
+
+| 导出 | 用途 |
+|------|------|
+| `useCellEditor` | Composable：注册 `setGetValue`、键盘 Enter/Esc、change 提交策略 |
+| `createVueCellEditor` | 将 Vue 组件包装为 `CellEditorFn` |
+| `createSlotCellEditor` | 将 `#cell-editor-{colId}` 插槽包装为 `CellEditorFn`（MagicGrid 内部使用） |
+| `VueCellEditorHost` | Vue 编辑器挂载宿主 |
+
+**`useCellEditor` 策略**：
+
+| strategy | Enter | change 时提交 | 典型场景 |
+|----------|-------|---------------|----------|
+| `'input'`（默认） | 立即提交 | 否 | ElInput、原生 input |
+| `'overlay'` | 延迟（由组件确认） | 是 | ElSelect、DatePicker |
+
+```vue
+<!-- MyInputEditor.vue -->
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { CellEditorParams } from '@taocompany/magic-grid/types/core'
+import { useCellEditor } from '@taocompany/magic-grid'
+
+const props = defineProps<{ params: CellEditorParams }>()
+const draft = ref(props.params.formattedValue)
+
+useCellEditor(props.params, {
+  strategy: 'input',
+  getValue: () => draft.value,
+})
+</script>
+
+<template>
+  <input v-model="draft" class="my-cell-editor" />
+</template>
+```
+
+```ts
+import { createVueCellEditor } from '@taocompany/magic-grid'
+import MyInputEditor from './MyInputEditor.vue'
+
+const columns: ColumnDef[] = [
+  {
+    prop: 'note',
+    label: '备注',
+    editable: true,
+    cellEditor: createVueCellEditor(MyInputEditor),
+  },
+]
+```
+
+`CellEditorParams` 主要字段：`value`、`data`、`stopEditing(commit?)`、`validate()`、`cancelCommit()`、`setGetValue`、`setKeyboardPolicy`、`inline`、`commit`（inline 模式）。
+
+### 命名编辑器注册表
+
+除列级函数 / 内置名外，可通过 **命名引用** 复用编辑器：
+
+```ts
+import { registerCellEditor } from '@taocompany/magic-grid'
+
+registerCellEditor('statusSelect', createVueCellEditor(StatusSelectEditor))
+
+// 列定义
+{ prop: 'status', cellEditor: 'statusSelect', editable: true }
+
+// 或实例级（仅当前 Grid）
+<MagicGrid :cell-editor-registry="{ statusSelect: myEditorFn }" ... />
+```
+
+优先级：**列级函数** > **实例 `cellEditorRegistry`** > **全局 `registerCellEditor`** > **内置名**。
+
+异步提交：`valueSetter` 返回 Promise 时进入 `committing` 阶段；Esc 可 `cancelCommit()`。配合 `asyncRowMutation` 做服务端持久化。
+
+---
+
+
+## 数据校验
+
+校验可在 **编辑提交时**（inline / overlay 共用）与 **编程式 API**（`validate` / `validateRows` / `validateCells`）两个入口触发。
+
+### 列级规则
+
+| 方式 | 字段 | 优先级 |
+|------|------|--------|
+| 手写 | `cellValidator` | 最高 |
+| async-validator | `validationRules` | 次之 |
+| 必填标记 | `validationRequired` | 与 rules.required 联动 |
+
+`validationRules` 使用 [async-validator](https://github.com/yiminghe/async-validator) 语法；magic-grid 会将异步 `validator` 自动映射为 `asyncValidator`。
+
+### enrichColumnsWithValidation
+
+在传入 Grid 前编译 rules 为运行时 `cellValidator`（可选，也可直接写 `cellValidator`）：
+
+```ts
+import { enrichColumnsWithValidation } from '@taocompany/magic-grid/validation'
+
+const rawColumns: ColumnDef[] = [
+  {
+    prop: 'email',
+    label: '邮箱',
+    validationRules: [
+      { required: true, message: '必填' },
+      { type: 'email', message: '格式不正确' },
+    ],
+  },
+]
+
+const columns = enrichColumnsWithValidation(rawColumns)
+```
+
+### 行级校验
+
+`rowValidator` 在 **行编辑模式** 提交时运行，返回 `string[]` 错误或 `{ errors, failedColIds }` 结构。失败触发 `row-validation-failed`。
+
+### 失败后行为
+
+由 `invalidEditValueMode` 控制：
+
+| 值 | 行为 |
+|----|------|
+| `'block'`（默认） | 保持编辑态，展示错误 |
+| `'revert'` | 退出编辑并恢复旧值 |
+| `'keep'` | 退出编辑但保留无效值 |
+
+### 编程式校验 API
+
+```ts
+const result = await api.validate({ rowIds: [1, 2], showFeedback: true })
+// result.valid · result.cellErrors · result.rowErrors
+
+await api.validateCells({ cells: [{ rowId: 1, colId: 'email' }] })
+api.clearValidation()
+```
+
+---
+
+
+## 键盘导航与快捷键
+
+焦点在表格视口内时（非编辑态），内核处理以下按键。编辑态下 Enter / Esc 等由编辑器或 `useCellEditor` 优先处理。
+
+### 导航
+
+| 按键 | 行为 |
+|------|------|
+| `↑` `↓` `←` `→` | 移动单元格焦点 |
+| `Shift` + 方向键 | 扩展框选 range（`cellSelection` 开启时） |
+| `Ctrl/Cmd` + 方向键 | 跳转到首/末行或导航序首/末列 |
+| `Tab` / `Shift+Tab` | 下一 / 上一可聚焦格（表头 ↔ 表体可衔接，`navigateHeader` / `navigateFooter` 控制） |
+| `Enter` | 表头：排序 / 全选；索引列：定位；树/分组：展开折叠；数据格：进入编辑 |
+| `Space` | 行选择 checkbox；inline checkbox 切换；表头/索引/树/分组同 Enter 的切换逻辑 |
+| `F2` | 进入编辑（若列可编辑） |
+| `Shift+F2` | 新建/打开单元格批注（批注功能启用时） |
+
+### 框选与剪贴板
+
+| 按键 | 行为 |
+|------|------|
+| `Delete` / `Backspace` | 清空选区内可编辑格（触发 `cell-selection-delete-*` 事件） |
+| `Ctrl/Cmd+C` | 复制选区为 TSV（需 `enableCellCopy`） |
+| `Ctrl/Cmd+V` | 从剪贴板粘贴至选区锚点（需 `enableCellPaste: true`） |
+
+### 列宽（表头焦点）
+
+| 按键 | 行为 |
+|------|------|
+| `Alt+←/→` | 键盘调整列宽 |
+| `Shift+Alt+←/→` | 邻列补偿（需 `colResizeDefault: 'shift'`） |
+| `Shift+←/→` | 移动表头焦点列（列拖拽排序辅助） |
+
+### 编辑态
+
+| 按键 | 行为 |
+|------|------|
+| `Esc` | 取消编辑；若正在 async commit 则 `cancelCommit()` |
+| `Enter` | overlay input 策略：提交；overlay 策略由组件处理 |
+| `Tab` | 行编辑模式：同行下一可编辑列 |
+
+---
+
+---
+
 ## 辅助组件
 
 表格列设置（Phase 27）提供一组**独立组件**，对标 AG Grid 的 Side Bar + Columns Tool Panel。只要持有 `GridApi` 即可使用，不强依赖 MagicGrid 内部 DOM。
@@ -1446,7 +2351,7 @@ import {
   ColumnSettingsMenuItem,
   ColumnSettingsMenuIcon,
 } from '@taocompany/magic-grid'
-import type { GridApi, ColumnDef, RowData } from '@taocompany/magic-grid'
+import type { GridApi, ColumnDef, RowData } from '@taocompany/magic-grid/types/core'
 import '@taocompany/magic-grid/style.css'
 
 const columns: ColumnDef[] = [/* ... */]
@@ -1489,7 +2394,7 @@ function onResetColumnOrder(api: GridApi) {
 <script setup lang="ts">
 import { ref } from 'vue'
 import { MagicGrid, ColumnSettingsButton } from '@taocompany/magic-grid'
-import type { GridApi, MagicGridExpose } from '@taocompany/magic-grid'
+import type { GridApi, MagicGridExpose } from '@taocompany/magic-grid/types/core'
 
 const gridRef = ref<MagicGridExpose>()
 </script>
@@ -1588,7 +2493,7 @@ const gridRef = ref<MagicGridExpose>()
 
 ### ColumnSettingsPanel
 
-列设置面板本体。按 **左固定 / 中心 / 右固定 / 隐藏** 四组展示用户列，每行支持拖拽排序、排序切换、筛选面板、固定列、显隐控制；面板头部提供「清除全部筛选」。
+列设置面板本体。按 **左固定 / 中心 / 右固定 / 隐藏** 四组展示**已注册进列模型**的用户列（`available: false` 的列不会出现）；每行支持拖拽排序、排序切换、筛选面板、固定列、显隐控制；面板头部提供「清除全部筛选」。
 
 > 通常由 `ColumnSettingsButton` 内嵌使用；也可单独 import 嵌入任意容器。
 
@@ -1600,7 +2505,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)` |
 
@@ -1722,7 +2627,7 @@ const gridRef = ref<MagicGridExpose>()
 类型 `ColumnSettingsMenuIconName` 已从包导出：
 
 ```ts
-import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid'
+import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid/types/core'
 ```
 
 #### Slots / Events / Expose
@@ -1731,23 +2636,213 @@ 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） |
+## 包入口与导出
+
+`package.json` `exports` 字段：
+
+| 子路径 | 说明 |
+|--------|------|
+| `@taocompany/magic-grid` | 主入口：组件、编辑器工具、常量、部分 core 工具 |
+| `@taocompany/magic-grid/types/core` | Grid / 列 / 事件 / API 类型（`ColumnDef`、`GridApi`、`MagicGridExpose` 等） |
+| `@taocompany/magic-grid/types/validation` | async-validator 类型别名（`Rule`、`Rules`） |
+| `@taocompany/magic-grid/validation` | 校验运行时（`enrichColumnsWithValidation`、`Schema` 等） |
+| `@taocompany/magic-grid/style.css` | 全局样式（**必须**手动引入） |
+
+### 主入口运行时导出
+
+**组件**
+
+- `MagicGrid`
+- `ColumnSettingsButton` / `ColumnSettingsPanel` / `ColumnSettingsMenuItem` / `ColumnSettingsMenuIcon`
+
+**单元格编辑器**
+
+- `useCellEditor`、`VueCellEditorHost`、`createVueCellEditor`、`createSlotCellEditor`
+- `textCellEditor`、`numberCellEditor`、`checkboxCellEditor`（内置实现，高级场景）
+- `registerCellEditor` / `unregisterCellEditor` / `getCellEditor` / `hasCellEditor` / `getRegisteredCellEditorNames`
+- `BUILTIN_CELL_EDITOR_NAMES`、`isBuiltInCellEditor`
+- `DEFAULT_CELL_EDITOR_MODE`、`resolveCellEditorMode`、`isInlineEditorColumn`
+
+**常量**
+
+- `INDEX_COLUMN_ID`、`DEFAULT_INDEX_COLUMN_START`、`INDEX_COLUMN_MIN_WIDTH`
+- `SELECTION_COLUMN_ID`、`SELECTION_COLUMN_DEFAULT_WIDTH`、`SELECTION_COLUMN_MIN_WIDTH`
+- `DEFAULT_STATUS_BAR_RANGE_AGGREGATION_PRECISION`
+- `COLUMN_DRAG_THRESHOLD_PX`、`SORT_AFTER_MOVE_GUARD_MS`
+
+**工具**
+
+- `toggleHeaderSort`
+- `toBusinessRowId`、`toBusinessRowIdFromInternal`、`toBusinessRowIdsFromInternal`、`isSyntheticRow`
+- `evaluateGridAcceptance`、`getGridAcceptanceThresholds`、`getGridSetDataLimit`（性能验收）
+- `RowMutationPersistError`
 
-### 校验子路径
+---
+
+
+## TypeScript 集成
+
+### 行数据泛型
+
+`ColumnDef` 与 `MagicGridProps` 支持泛型推导列 `prop` 与行数据字段：
 
 ```ts
-import { enrichColumnsWithValidation } from '@taocompany/magic-grid/validation'
+interface UserRow {
+  id: number
+  name: string
+  age: number
+}
+
+const columns: ColumnDef<UserRow>[] = [
+  { prop: 'name', label: '姓名' }, // prop 自动收窄为 'name' | 'age' | 'id'
+]
+
+// MagicGridProps<UserRow> 可用于包装组件 props 类型
+import type { MagicGridProps } from '@taocompany/magic-grid/types/core'
+```
+
+### 组件 ref 类型
+
+```ts
+import type { MagicGridExpose, GridApi } from '@taocompany/magic-grid/types/core'
+
+const gridRef = ref<MagicGridExpose>()
+const api = computed(() => gridRef.value?.api) // Ref<GridApi | undefined>
+```
+
+### 事件 payload
+
+事件回调参数类型均从 `@taocompany/magic-grid/types/core` 导出，例如 `CellValueChangedEvent`、`SelectionChangedEvent`、`FilterModel`、`SortModelItem`。
+
+### 严格模式建议
+
+- 项目启用 `strict: true`；避免对 `RowData` 使用 `any`。
+- 自定义 `cellRenderer` / `valueGetter` 返回值使用 `unknown`，formatter 负责展示字符串。
+
+---
+
+
+## 类型与校验子路径
+
+类型按职责拆分为多个子路径，避免主包体积膨胀。
+
+### `@taocompany/magic-grid/types/core`
+
+Grid / 列 / 事件 / API 的完整类型面。常用导出：
+
+```ts
+import type {
+  // 数据与列
+  RowData,
+  ColumnDef,
+  MagicGridProps,
+  MagicGridExpose,
+  GridApi,
+  RowNode,
+  BusinessRowId,
+  RowIdInput,
+  // 排序 / 筛选
+  SortModelItem,
+  FilterModel,
+  FilterCondition,
+  ColumnFilter,
+  // 编辑
+  CellEditorParams,
+  CellEditorFn,
+  CellEditorDef,
+  CellEditBehavior,
+  CellEditType,
+  CellEditorMode,
+  EditSessionPhase,
+  // 框选
+  CellRange,
+  CellSelectionOptions,
+  CellSelectionAggregation,
+  // 事件（示例）
+  CellValueChangedEvent,
+  SelectionChangedEvent,
+  ColumnMovedEvent,
+  // 校验
+  CellValidator,
+  RowValidator,
+  ValidationRules,
+  GridValidationResult,
+  // 列设置
+  ColumnSettingsResetScope,
+  ColumnSettingsMenuIconName,
+  // 插槽
+  StatusBarContext,
+  DetailRowSlotParams,
+  OverlaySlotParams,
+} from '@taocompany/magic-grid/types/core'
 ```
 
-配合 `ColumnDef.validationRules` 使用 async-validator 规则。
+完整列表见源码 `src/types/core.ts`（re-export 聚合）。
+
+### `@taocompany/magic-grid/types/validation`
+
+async-validator 类型透传：
+
+```ts
+import type { Rule, Rules, ValidateError, ValidateFieldsError } from '@taocompany/magic-grid/types/validation'
+```
+
+### `@taocompany/magic-grid/validation`
+
+校验运行时（需安装 `async-validator` peer dependency）：
+
+```ts
+import {
+  Schema,
+  enrichColumnsWithValidation,
+  createCellValidator,
+  createRowValidator,
+  validateWithSchema,
+  isValidationRequired,
+} from '@taocompany/magic-grid/validation'
+```
+
+---
+
+
+## 本地开发与 Playground
+
+### 环境
+
+```bash
+pnpm install
+pnpm dev          # 启动 Playground（默认 Vite dev server）
+pnpm build        # 构建 npm 包至 dist/
+pnpm test:run     # 单元测试
+pnpm typecheck    # Vue + TS 类型检查
+```
+
+要求 Node.js >= 20.19，包管理器推荐 pnpm 11.x。
+
+### Playground 路由
+
+开发服务器按 Phase 组织演示页，便于逐项验收能力：
+
+| 路由 | 主题 |
+|------|------|
+| `/phase2` – `/phase27` | 各 Phase 功能演示与验收用例 |
+| `/glossary` | 术语表 |
+
+典型入口：`pnpm dev` 后访问控制台输出的本地 URL，从侧边栏切换 Phase。例如列显隐验收 **`/phase22`**（T14–T15 · `available` 列切换）。
+
+Playground 源码位于仓库 `playground/` 目录；自定义 Vue 编辑器示例见 `playground/components/editors/`（Element Plus 集成参考）。
+
+### 构建产物
+
+`pnpm build` 输出：
+
+- `dist/index.es.js` / `dist/index.cjs.js` — 主包
+- `dist/types/*.js` — 类型子路径运行时垫片
+- `dist/style.css` — 样式
+- `dist/*.d.ts` — 类型声明（api-extractor rollup）
+
+发布前会自动执行 `prepublishOnly` → `pnpm run build`。
 
 ---