@taocompany/magic-grid 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,1305 @@
+# Magic Grid
+
+面向 Vue 3 的高性能虚拟表格组件库。采用命令式渲染 + 行 DOM 池 + 双轴虚拟化，可稳定承载百万级行数据；API 设计对标 [AG Grid](https://www.ag-grid.com/) 社区版，覆盖排序、筛选、编辑、行分组、树形表格、框选、剪贴板等完整表格能力。
+
+## 目录
+
+- [概述](#概述)
+- [快速开始](#快速开始)
+- [Props](#props)
+  - [MagicGrid Props](#magicgrid-props)
+  - [ColumnDef 列定义](#columndef-列定义)
+- [Events](#events)
+- [Expose](#expose)
+- [Slots](#slots)
+- [辅助组件](#辅助组件)
+  - [ColumnSettingsButton](#columnsettingsbutton)
+  - [ColumnSettingsPanel](#columnsettingspanel)
+  - [ColumnSettingsMenuItem](#columnsettingsmenuitem)
+  - [ColumnSettingsMenuIcon](#columnsettingsmenuicon)
+- [相关文档](#相关文档)
+
+---
+
+## 概述
+
+### 特性
+
+| 类别 | 能力 |
+|------|------|
+| **性能** | 行/列双轴虚拟化、DOM 池复用、RAF 帧预算分片、增量数据管线 |
+| **数据** | 排序、列筛选、Quick Filter、事务增量更新（`applyTransaction`）、行 CRUD |
+| **交互** | 单元格/行编辑、校验、行选择、索引列定位、框选与剪贴板 |
+| **布局** | 固定列、列拖拽/调整宽度、合并单元格、动态行高、主从展开行 |
+| **结构** | 行分组、树形表格（含懒加载）、表尾汇总 |
+| **体验** | 溢出 Tooltip、单元格批注、空态 Overlay、暗色主题、底部状态栏 |
+
+### 环境要求
+
+- Node.js >= 20.19
+- Vue ^3.5.0
+- async-validator ^4.2.0（校验功能 peer dependency）
+
+### 安装
+
+```bash
+pnpm add @taocompany/magic-grid async-validator
+```
+
+### 引入样式
+
+```ts
+import '@taocompany/magic-grid/style.css'
+```
+
+---
+
+## 快速开始
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { MagicGrid } from '@taocompany/magic-grid'
+import type { ColumnDef, MagicGridExpose, RowData } from '@taocompany/magic-grid'
+import '@taocompany/magic-grid/style.css'
+
+const gridRef = ref<MagicGridExpose>()
+
+const columns: ColumnDef[] = [
+  { prop: 'name', label: '姓名', width: 120, sortable: true },
+  { prop: 'age', label: '年龄', width: 80, sortable: true },
+  { prop: 'city', label: '城市', flex: 1, filterable: true },
+]
+
+const data: RowData[] = [
+  { id: 1, name: '张三', age: 28, city: '上海' },
+  { id: 2, name: '李四', age: 32, city: '北京' },
+]
+
+function onSelectionChanged(event: { selectedRowIds: readonly (string | number)[] }) {
+  console.log('选中行:', event.selectedRowIds)
+}
+</script>
+
+<template>
+  <MagicGrid
+    ref="gridRef"
+    :columns="columns"
+    :data="data"
+    row-key="id"
+    height="400"
+    row-selection="multiple"
+    stripe
+    @selection-changed="onSelectionChanged"
+  />
+</template>
+```
+
+> **提示**：`data` 应为普通对象数组，避免对行数据使用 `reactive()` 深代理。
+
+---
+
+## Props
+
+### MagicGrid Props
+
+#### 基础
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `columns` | `ColumnDef[]` | — | **必填**。列定义数组 |
+| `data` | `RowData[]` | — | **必填**。行数据（普通对象，禁止 reactive 深代理） |
+| `rowKey` | `string` | `'id'` | 行主键字段名，用于行池复用与增量更新 |
+| `height` | `string \| number` | `'100%'` | 容器高度 |
+| `width` | `string \| number` | `'100%'` | 容器宽度 |
+
+#### 外观
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `stripe` | `boolean` | `false` | 斑马纹 |
+| `border` | `'border' \| 'none' \| 'linear'` | `'border'` | 边框样式：`border` 全网格线；`none` 无单元格线；`linear` 仅底部分隔线 |
+| `theme` | `'light' \| 'dark'` | `'light'` | 主题 preset |
+| `size` | `'mini' \| 'small' \| 'default' \| 'large'` | `'default'` | 尺寸 preset（影响行高、字号、间距等） |
+| `rounded` | `number \| boolean` | `false` | 容器圆角：`false`/`0` 无圆角；`true` 跟随 size；`number` 自定义 px |
+| `rowHeight` | `number` | — | 固定行高（px）；显式传入时覆盖 size preset |
+| `headerHeight` | `number` | — | 表头高度（px）；显式传入时覆盖 size preset |
+| `rowStyle` | `RowStyle \| RowStyleFn` | — | 行级样式（对象=全表同色；函数=按行）；作用于表体用户数据列与行选择列 |
+
+#### 对齐（全局默认）
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `headerAlign` | `'left' \| 'center' \| 'right'` | `'center'` | 表头水平对齐 |
+| `headerValign` | `'top' \| 'center' \| 'bottom'` | `'center'` | 表头垂直对齐 |
+| `align` | `'left' \| 'center' \| 'right'` | `'center'` | 表体水平对齐 |
+| `valign` | `'top' \| 'center' \| 'bottom'` | `'center'` | 表体垂直对齐 |
+| `footerAlign` | `'left' \| 'center' \| 'right'` | `'center'` | 表尾汇总水平对齐 |
+| `footerValign` | `'top' \| 'center' \| 'bottom'` | `'center'` | 表尾汇总垂直对齐 |
+
+#### 虚拟化与导航
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowBuffer` | `number` | `10` | 行虚拟化缓冲行数 |
+| `navigateHeader` | `boolean` | `false` | 是否允许键盘/鼠标将焦点导航到表头 |
+| `navigateFooter` | `boolean` | `false` | 是否允许焦点导航到表尾汇总行（需 `showSummary: true`） |
+| `enableHeaderHighlight` | `boolean` | `true` | 表头高亮 |
+| `enableIndexColumnHighlight` | `boolean` | `true` | 索引列高亮 |
+
+#### 索引列
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `showIndexColumn` | `boolean` | `false` | 是否显示最左侧索引列 |
+| `indexColumn` | `IndexColumnOptions` | — | 索引列配置（`showIndexColumn=true` 时生效） |
+
+`IndexColumnOptions` 字段：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `label` | `string` | `''` | 表头文案 |
+| `width` | `number` | `40` | 列宽 px（最小 40） |
+| `start` | `number` | `1` | 起始序号（1-based 展示 = rowIndex + start） |
+| `focusMode` | `'single' \| 'multiple'` | `'multiple'` | 辅助定位模式 |
+| `syncToSelectionColumn` | `boolean` | `false` | 索引列定位是否单向同步到行选择列 |
+| `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
+| `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
+| `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+
+#### 行选择
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowSelection` | `'single' \| 'multiple' \| false \| RowSelectionConfig` | `'single'` | 行选择模式；`false` 禁用 |
+| `selectionColumn` | `SelectionColumnOptions` | — | 行选择列配置 |
+| `selectable` | `SelectableFn` | — | 行 checkbox 是否可勾选；省略时全部可选 |
+| `reserveSelection` | `boolean` | `false` | 数据刷新后是否保留选中行 |
+| `isRowDisabled` | `boolean \| IsRowDisabledFn` | — | 行级禁用（该行全部数据列 disabled） |
+
+`RowSelectionConfig`：
+
+```ts
+interface RowSelectionConfig {
+  mode: 'single' | 'multiple'
+  groupSelectsChildren?: boolean  // tree 模式下选中父节点是否级联子孙，默认 true
+}
+```
+
+`SelectionColumnOptions` 字段：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `width` | `number` | `40` | 列宽 px（最小 40） |
+| `selectAllLabel` | `string` | `'全选'` | 表头全选 checkbox 的 aria-label |
+| `rowLabel` | `(rowIndex) => string` | — | 行 checkbox 的 aria-label 工厂 |
+
+#### 表尾汇总
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `showSummary` | `boolean` | `false` | 是否展示表尾汇总行 |
+| `summaryScope` | `'displayed' \| 'all'` | `'displayed'` | 汇总范围：`displayed` 当前可见行；`all` 全量 sourceRows |
+| `summaryRowHeight` | `number` | — | 汇总行高度 px；未传时跟随 rowHeight |
+| `summaryMethod` | `SummaryMethod` | — | 全局汇总方法（优先级高于列级 `summaryAgg`） |
+
+#### 排序
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `defaultSort` | `SortModelItem[]` | — | 初始排序（挂载时应用一次；v1 仅使用首项） |
+| `showUnsortedSortHintOnHover` | `boolean` | `false` | 未排序 sortable 列 hover 显示 faint 双三角 |
+
+#### 列操作
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `columnMovable` | `boolean` | `true` | 是否允许表头拖拽重排列 |
+| `resizable` | `boolean` | `true` | 是否允许拖拽调整列宽（列级 `resizable` 优先） |
+| `colResizeDefault` | `'shift'` | — | Shift 模式：拖拽列宽时相邻列反向补偿，总宽不变 |
+| `skipHeaderOnAutoSize` | `boolean` | `false` | 双击 resize 把柄 auto-size 时跳过表头宽度 |
+| `autoSizePadding` | `number` | — | auto-size 内容测量额外 padding（px） |
+| `autoSizeStrategy` | `AutoSizeStrategy` | — | 挂载/首屏 auto-size 策略 |
+| `suppressMoveWhenColumnDragging` | `boolean` | `false` | `true` → 仅 mouseup 提交列序 |
+| `suppressColumnMoveAnimation` | `boolean` | `false` | 关闭列移动 transition |
+| `allowCrossLaneColumnMove` | `boolean` | `false` | 允许 drag/API 跨 fixed lane 并更新列 `fixed` |
+
+#### 筛选
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `quickFilterText` | `string` | `''` | Grid 级 quick filter 文本 |
+| `floatingFilter` | `boolean` | `false` | 是否显示 floating filter 行 |
+| `filterSetValueMode` | `'reserve' \| 'current'` | `'current'` | 值选择搜索时的勾选投影模式 |
+| `filterSetDateLayoutMode` | `'list' \| 'tree'` | `'tree'` | 日期列值选择展示方式 |
+
+#### 编辑
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `editMode` | `'cell' \| 'row'` | `'cell'` | 编辑范围：单格 / 整行 |
+| `editType` | `CellEditType` | `'singleClick'` | 进入编辑态的触发方式 |
+| `invalidEditValueMode` | `'block' \| 'revert'` | `'block'` | 校验失败后：`block` 保持编辑；`revert` 退出并恢复旧值 |
+| `rowValidator` | `RowValidator` | — | 行编辑跨字段校验 |
+| `cellEditorRegistry` | `Record<string, CellEditorFn>` | — | 实例级命名编辑器注册表 |
+| `asyncRowMutation` | `AsyncRowMutationHandlers` | — | 异步行 CRUD 持久化钩子 |
+
+#### 行拖拽与行高
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowDragManaged` | `boolean` | `true` | managed 行拖拽：拖拽过程中实时改 source 顺序 |
+| `rowDragCommitMode` | `'sync' \| 'deferred'` | `'sync'` | commit 策略：`sync` live move；`deferred` mouseup 后 await `onRowDragCommit` |
+| `onRowDragCommit` | `RowDragCommitHandler` | — | deferred 模式：mouseup 后、apply 前调用；返回 `false` 则不写 source |
+| `getRowHeight` | `GetRowHeightFn` | — | 行级动态高度（无 DOM） |
+| `rowHeightMin` | `number` | — | 行高下限 px |
+| `rowHeightMax` | `number` | — | 行高上限 px |
+
+#### 合并单元格
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enableCellSpan` | `boolean` | `false` | 启用单元格合并（列级 `colSpan` / `rowSpan` / `spanRows`） |
+
+#### 主从展开行
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `masterDetail` | `boolean` | `false` | 启用主从展开行 |
+| `isRowMaster` | `IsRowMasterFn` | — | 是否为主行（可展示 expand 控件） |
+| `masterDefaultExpanded` | `number` | — | 默认展开层级：0=无；1=第一层；-1=全部 |
+| `detailRowHeight` | `number \| DetailRowHeightFn` | — | 详情行固定高度 px |
+| `detailRowAutoHeight` | `boolean` | — | 详情行按内容自动撑高 |
+| `embedFullWidthRows` | `boolean` | — | `true`：详情嵌入 center lane 随横滚 |
+| `showExpandColumn` | `boolean` | — | 最左展示专用展开列 |
+| `getDetailRowData` | `GetDetailRowDataFn` | — | 异步提供详情区数据 |
+| `detailCellRenderer` | `DetailCellRendererFn` | — | 自定义详情行渲染器（与 `#detail-row` 插槽二选一） |
+
+#### 行分组
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowGrouping` | `boolean` | `false` | 启用行分组 |
+| `groupDefaultExpanded` | `number` | `-1` | 默认展开分组层级：0=全折叠；1=第一层；-1=全部 |
+| `showGroupHeader` | `boolean` | `false` | 展示 groupHeader 分组标题行 |
+| `showGroupFooter` | `boolean` | `false` | 为每个已展开分组展示 footer 汇总行 |
+| `groupDisplayType` | `'singleColumn'` | `'singleColumn'` | 分组展示模式（v1 仅 singleColumn） |
+| `showGroupColumn` | `boolean` | `false` | 展示 auto group 系统列 |
+| `autoGroupColumnDef` | `Partial<ColumnDef>` | — | 覆盖 auto group 列 colDef |
+| `groupKeyCreator` | `GroupKeyCreatorFn` | — | 分组键归一化 |
+| `groupComparator` | `GroupComparatorFn` | — | 同级 group 节点排序 |
+| `groupFooterLabel` | `string` | — | groupFooter 首列展示标签 |
+| `groupCellRenderer` | `GroupCellRendererFn` | — | 自定义分组单元格渲染器 |
+
+#### 树形表格
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `tree` | `boolean` | `false` | 启用树形表格（与 `rowGrouping` 互斥） |
+| `getDataPath` | `GetDataPathFn` | — | 树形路径回调（`tree: true` 时必填） |
+| `treeDragScope` | `'siblings' \| 'hierarchy'` | `'siblings'` | 树形拖拽范围 |
+| `setDataPath` | `SetDataPathFn` | — | hierarchy 模式下写回 dataPath |
+| `showTreeColumn` | `boolean` | `true` | 展示 tree 系统列 |
+| `autoTreeColumnDef` | `Partial<ColumnDef>` | — | 覆盖 tree 系统列 colDef |
+| `treeValueGetter` | `TreeValueGetterFn` | — | 自定义 tree 列展示值 |
+| `treeDisplayType` | `'singleColumn'` | — | 树节点展示列模式 |
+| `treeLazyLoad` | `boolean` | `false` | 启用树形懒加载 |
+| `hasTreeChildren` | `HasTreeChildrenFn` | — | lazy 模式：节点是否可能有未加载子行 |
+| `loadTreeChildren` | `LoadTreeChildrenFn` | — | lazy 模式：首次展开时拉取子数据 |
+
+#### 单元格批注
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cellCommentsDataSource` | `CellCommentsDataSource` | — | 批注数据源；提供即启用 |
+| `suppressCellComments` | `boolean` | `false` | 全局抑制批注交互 |
+| `cellCommentTrigger` | `'click' \| 'hover'` | `'click'` | 查看已有批注的触发方式 |
+| `cellCommentShowDelay` | `number` | `180` | hover 模式展示延迟 ms |
+| `cellCommentHideDelay` | `number` | `220` | 离开 cell/popup 后隐藏延迟 ms |
+
+#### 框选与剪贴板
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cellSelection` | `boolean \| CellSelectionOptions` | `false` | 单元格框选 |
+| `enableCellClipboard` | `boolean` | — | 启用剪贴板（通常随 cellSelection 开启） |
+| `processCellForClipboard` | `ProcessCellForClipboardFn` | — | 复制单格时自定义导出值 |
+| `processCellFromClipboard` | `ProcessCellFromClipboardFn` | — | 粘贴单格时预处理 clipboard 字符串 |
+| `processDataFromClipboard` | `ProcessDataFromClipboardFn` | — | 整表粘贴前处理 TSV 矩阵；return null 取消粘贴 |
+
+#### Tooltip
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enableTooltips` | `boolean` | `true` | 是否启用溢出 tooltip |
+| `tooltipShowMode` | `'whenTruncated' \| 'always' \| 'never'` | `'whenTruncated'` | 溢出 tooltip 显示策略 |
+| `tooltipShowDelay` | `number` | `500` | 首次 hover 展示延迟 ms |
+| `tooltipSwitchShowDelay` | `number` | `200` | 格间切换展示延迟 ms |
+| `tooltipHideDelay` | `number` | `3000` | 离开后隐藏延迟 ms |
+| `tooltipInteraction` | `boolean` | — | tooltip 是否可交互 |
+| `tooltipMouseTrack` | `boolean` | — | tooltip 是否跟随鼠标 |
+| `tooltipComponent` | `TooltipComponentType` | — | 自定义 tooltip 组件（与 `#tooltip` 插槽二选一） |
+| `tooltipComponentParams` | `Record<string, unknown>` | — | tooltip 组件额外参数 |
+
+#### 空态 Overlay
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `loading` | `boolean` | — | 显示 loading overlay；`undefined` 为挂载后首次 setData 前自动 loading |
+| `suppressOverlays` | `OverlayType[]` | — | 逐项抑制内置 overlay |
+| `suppressLoadingOverlay` | `boolean` | — | 抑制 loading overlay |
+| `suppressNoRowsOverlay` | `boolean` | — | 抑制无数据 overlay |
+| `suppressNoMatchingRowsOverlay` | `boolean` | — | 抑制筛选无匹配 overlay |
+| `overlayLoadingTemplate` | `string` | — | loading 模板 HTML |
+| `overlayNoRowsTemplate` | `string` | — | 无数据模板 HTML |
+| `overlayNoMatchingRowsTemplate` | `string` | — | 筛选无匹配模板 HTML |
+| `loadingOverlayComponent` | `OverlayComponentType` | — | 自定义 loading 组件 |
+| `noRowsOverlayComponent` | `OverlayComponentType` | — | 自定义无数据组件 |
+| `noMatchingRowsOverlayComponent` | `OverlayComponentType` | — | 自定义筛选无匹配组件 |
+| `overlayComponent` | `OverlayComponentType` | — | 通用 overlay 组件 |
+| `overlayInteraction` | `boolean` | — | overlay 内容是否可交互 |
+
+#### 状态栏
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `showStatusBar` | `boolean` | `true` | 是否显示底部状态栏 |
+| `showDefaultStatusBarPanels` | `boolean` | `true` | 显示默认状态栏面板（行数/筛选态/选中数） |
+| `showStatusBarRangeAggregation` | `boolean` | `true` | 框选时在状态栏展示平均值/计数/求和 |
+| `statusBarRangeAggregationPrecision` | `number \| { average?: number; sum?: number }` | `2` | 平均值/求和展示小数位数 |
+
+---
+
+### ColumnDef 列定义
+
+每列通过 `columns` 数组传入。`key` 为列唯一标识，缺省等于 `prop`。
+
+#### 标识与展示
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 列唯一标识（colId），缺省等于 `prop` |
+| `prop` | `string` | 数据字段 |
+| `label` | `string` | 表头文案 |
+| `hidden` | `boolean` | 是否隐藏该列（不渲染、不参与布局）；默认 `false` |
+
+#### 尺寸
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `width` | `number` | 固定列宽 px |
+| `minWidth` | `number` | 最小列宽 px |
+| `maxWidth` | `number` | 最大列宽 px |
+| `flex` | `number` | 弹性列宽权重 |
+
+#### 行为
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `sortable` | `boolean` | 是否可排序 |
+| `comparator` | `ColumnComparatorFn` | 自定义排序比较器（asc 语义；desc 由内核取反） |
+| `filterable` | `boolean` | 是否可筛选 |
+| `filterType` | `ColumnDataFilterType` | 筛选数据类型；默认 `text` |
+| `filterParams` | `FilterParams` | 列级 filter 参数 |
+| `filterValueGetter` | `(row) => unknown` | 筛选用取值；缺省同 getter/prop |
+| `editable` | `boolean \| (row) => boolean` | 是否可编辑 |
+| `resizable` | `boolean` | 是否允许拖拽调整列宽；缺省继承 Grid `resizable` |
+| `suppressAutoSize` | `boolean` | 禁止 resize 把柄 dblclick / API auto-size |
+| `suppressSizeToFit` | `boolean` | 禁止参与 sizeColumnsToFit |
+| `fixed` | `'left' \| 'right' \| null` | 固定列 |
+| `movable` | `boolean` | 是否允许表头拖拽重排；默认继承 `columnMovable` |
+| `rowDrag` | `boolean` | 该列单元格作为行拖拽起点 |
+| `rowExpand` | `boolean` | 在该列渲染 expand/collapse 控件 |
+| `autoHeight` | `boolean` | 该列内容撑开行高 |
+
+#### 行分组（需 `rowGrouping: true`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowGroup` | `boolean` | 该列参与行分组 |
+| `rowGroupIndex` | `number` | 多级分组顺序（小者优先） |
+| `groupAgg` | `SummaryAgg` | 分组 footer 行的聚合 |
+| `showGroupHeaderCell` | `boolean` | 在该列渲染 groupHeader 单元格 |
+| `showGroupFooterCell` | `boolean` | 在该列渲染 groupFooter 标签 |
+| `groupFooterLabel` | `string` | 覆盖 Grid `groupFooterLabel` 的本列小计文案 |
+
+#### 合并单元格（需 `enableCellSpan: true`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `colSpan` | `ColSpanFn` | 横向合并列数（≥1） |
+| `rowSpan` | `RowSpanFn` | 纵向合并行数（≥1）；与 `spanRows` 互斥时本字段优先 |
+| `spanRows` | `boolean \| SpanRowsFunc` | 相邻等值自动纵向合并 |
+
+#### 数据转换与渲染
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `getter` | `(row, value) => unknown` | 取值转换 |
+| `formatter` | `(row, value) => string` | 展示格式化 |
+| `cellRenderer` | `CellRendererFn` | 自定义单元格渲染器（函数；Vue 组件通过 `#cell-{colId}` 插槽） |
+| `cellEditor` | `CellEditorDef` | 自定义单元格编辑器（函数、内置 `text`/`number`/`checkbox`、或命名引用） |
+| `cellEditorMode` | `'overlay' \| 'inline'` | 编辑器呈现方式；默认 `overlay` |
+| `valueParser` | `(value, params) => unknown` | 提交前解析编辑值 |
+| `valueSetter` | `(params) => boolean \| Promise<boolean>` | 自定义写回逻辑；返回 `false` 拒绝提交 |
+| `editType` | `CellEditType` | 编辑触发策略；缺省继承 grid 级配置 |
+
+#### 校验
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `cellValidator` | `CellValidator` | 手写校验（优先级高于 validationRules） |
+| `validationRules` | `ValidationRules` | async-validator 规则 |
+| `validationRequired` | `boolean` | 必填列标记 |
+
+#### 剪贴板
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `suppressPaste` | `boolean \| SuppressPasteFn` | 禁止粘贴 |
+| `useParserForClipboard` | `boolean` | 粘贴是否走 valueParser；默认 `true` |
+| `useFormatterForClipboard` | `boolean` | 复制是否走 formatter；默认 `true` |
+
+#### 汇总
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `summary` | `boolean` | 是否参与表尾汇总；缺省：有 `summaryAgg` 则为 true |
+| `summaryAgg` | `SummaryAgg` | 表尾汇总聚合：`sum`/`avg`/`min`/`max`/`count` 或自定义函数 |
+| `summaryFormatter` | `(value) => string` | 汇总格专用 formatter |
+
+#### 对齐
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `headerAlign` / `headerValign` | 对齐枚举 | 表头对齐；默认 `center` |
+| `align` / `valign` | 对齐枚举 | 表体对齐；默认 `center` |
+| `footerAlign` / `footerValign` | 对齐枚举 | 表尾对齐；默认 `center` |
+
+#### 禁用与样式
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `disabled` | `boolean` | 列级禁用：该列全部数据行 disabled |
+| `cellDisabled` | `boolean \| CellDisabledFn` | 格级禁用；与 disabled / isRowDisabled 叠加 |
+| `cellStyle` | `CellStyle \| CellStyleFn` | 列级静态背景或格级 cellStyle 回调 |
+| `suppressCellComments` | `boolean \| SuppressCellCommentFn` | 抑制该列（或特定行）的批注新建/编辑/删除 |
+
+#### Tooltip
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `tooltipField` | `string` | 读 `row.data[field]` 作为 tooltip |
+| `tooltipValueGetter` | `TooltipValueGetter` | 自定义 tooltip 文案 |
+| `headerTooltip` | `string` | 表头静态 tooltip |
+| `headerTooltipValueGetter` | `HeaderTooltipValueGetter` | 表头自定义 tooltip |
+| `suppressTooltip` | `boolean` | 抑制该列溢出 tooltip |
+| `tooltipComponent` | `TooltipComponentType` | 列级自定义 tooltip 组件 |
+| `tooltipComponentParams` | `Record<string, unknown>` | tooltip 组件参数 |
+
+---
+
+## Events
+
+MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 kebab-case。
+
+### 渲染与滚动
+
+| 事件 |  payload | 说明 |
+|------|----------|------|
+| `scroll` | `GridMetrics` | 滚动后触发（含 scrollTop、可见行范围等） |
+| `data-rendered` | `GridMetrics` | 数据渲染完成后触发 |
+
+### 交互
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `cell-clicked` | `CellClickedEvent` | 单元格点击 |
+| `row-click` | `RowClickedEvent` | 行点击 |
+| `row-dblclick` | `RowDoubleClickedEvent` | 行双击 |
+| `selection-changed` | `SelectionChangedEvent` | 行选择变更；含 `selectedRowIds` |
+| `index-focus-changed` | `IndexFocusChangedEvent` | 索引列辅助定位变更 |
+
+### 编辑
+
+| 事件 | 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` | 行异步提交完成 |
+
+### 校验
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `cell-validation-failed` | `CellValidationFailedEvent` | 单元格校验失败 |
+| `row-validation-failed` | `RowValidationFailedEvent` | 行校验失败 |
+
+### 排序与筛选
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `sort-changed` | `SortModelItem[]` | 排序模型变更 |
+| `filter-changed` | `FilterModel` | 筛选模型变更 |
+
+### 列
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `column-moved` | `ColumnMovedEvent` | 列拖拽重排完成 |
+| `column-resized` | `ColumnResizedEvent` | 列宽调整 |
+| `column-pinned` | `ColumnPinnedEvent` | 列固定状态变更 |
+| `column-hidden-changed` | `ColumnHiddenChangedEvent` | 列显隐变更 |
+
+### 行 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` | 行高变更 |
+
+### 展开行
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `row-expanded` | `RowExpansionChangedEvent` | 主行展开 |
+| `row-collapsed` | `RowExpansionChangedEvent` | 主行折叠 |
+
+### 行分组
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `row-group-opened` | `RowGroupOpenedEvent` | 分组节点展开/折叠 |
+| `row-group-changed` | `RowGroupChangedEvent` | 分组列配置变更 |
+
+### 树形表格
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `tree-node-opened` | `TreeNodeOpenedEvent` | 树节点展开/折叠 |
+| `tree-children-loading` | `TreeChildrenLoadingEvent` | 懒加载子节点开始 |
+| `tree-children-loaded` | `TreeChildrenLoadedEvent` | 懒加载子节点成功 |
+| `tree-children-load-failed` | `TreeChildrenLoadFailedEvent` | 懒加载子节点失败 |
+
+### 批注
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `cell-comment-changed` | `CellCommentChangedEvent` | 单元格批注变更 |
+
+### 框选
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `cell-selection-changed` | `CellSelectionChangedEvent` | 框选范围变更 |
+| `cell-selection-delete-start` | `CellSelectionDeleteStartEvent` | Delete 清空选区开始 |
+| `cell-selection-delete-end` | `CellSelectionDeleteEndEvent` | Delete 清空选区结束 |
+
+### 空态
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `overlay-shown` | `OverlayShownEvent` | overlay 显示 |
+| `overlay-hidden` | `OverlayHiddenEvent` | overlay 隐藏 |
+
+### 事件监听示例
+
+```vue
+<MagicGrid
+  @cell-value-changed="({ rowId, colId, newValue, oldValue }) => { ... }"
+  @sort-changed="(model) => { ... }"
+  @filter-changed="(model) => { ... }"
+/>
+```
+
+除 Vue 事件外，也可通过 `gridRef.api` 订阅内核事件（见 [Expose](#expose)）。
+
+---
+
+## Expose
+
+通过组件 `ref` 获取 `MagicGridExpose` 实例，进行命令式操作。
+
+### 类型定义
+
+```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
+}
+```
+
+### 使用示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { MagicGridExpose } from '@taocompany/magic-grid'
+
+const gridRef = ref<MagicGridExpose>()
+
+async function addRow() {
+  await gridRef.value?.applyTransaction({
+    add: [{ id: Date.now(), name: '新行' }],
+  })
+}
+
+function exportData() {
+  return gridRef.value?.getData({ sourceOrder: true })
+}
+
+function scrollToRow(index: number) {
+  gridRef.value?.ensureIndexVisible(index, 'middle')
+}
+</script>
+
+<template>
+  <MagicGrid ref="gridRef" ... />
+</template>
+```
+
+### GridApi（`gridRef.api`）
+
+`api` 是完整的命令式 API 面，按职责分组如下。完整参考见 [`docs/16-grid-api-reference.md`](docs/16-grid-api-reference.md)。
+
+#### 数据
+
+| 方法 | 说明 |
+|------|------|
+| `setData(rows)` | 全量替换表格数据 |
+| `applyTransaction(tx)` | 增量事务 add/update/remove |
+| `addRows(options)` | 在指定位置插入行 |
+| `removeRows(options)` | 按 rowId 或下标删除行 |
+| `getData(options?)` | 导出业务层 RowData[] |
+| `promoteRowId(options)` | 临时行 ID 提升为正式主键 |
+| `moveRow(rowId, toIndex, indexMode?)` | 编程式移动行 |
+
+#### 排序 / 筛选
+
+| 方法 | 说明 |
+|------|------|
+| `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 勾选列表） |
+
+#### 列
+
+| 方法 | 说明 |
+|------|------|
+| `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?)` | 列宽按比例分配至视口 |
+
+#### 行高
+
+| 方法 | 说明 |
+|------|------|
+| `setRowHeight(rowId, height, finished?)` | 设置单行高度 |
+| `setRowHeights(changes, finished?)` | 批量设置行高 |
+| `getRowHeight(rowId)` | 读取行当前有效高度 |
+| `resetRowHeights(rowIds?)` | 清除 pinned 并重算行高 |
+| `updateDimensions(params)` | 热更新默认行高与 clamp 边界 |
+
+#### 渲染 / 视口
+
+| 方法 | 说明 |
+|------|------|
+| `refreshCells(params?)` | 刷新指定行或列的单元格 DOM |
+| `refreshCellSpans()` | 强制重建单元格合并 cache |
+| `getCellSpan(rowId, colId)` | 查询 span 信息 |
+| `ensureIndexVisible(index, position?)` | 滚动使行下标进入视口 |
+| `getRowNode(id)` | 按 rowId 获取行节点快照 |
+| `getMetrics()` | 读取渲染与滚动指标 |
+| `beginUpdate()` / `endUpdate()` | 批量更新 |
+| `scrollTo(scrollTop, scrollLeft?)` | 编程式滚动 |
+
+#### 编辑
+
+| 方法 | 说明 |
+|------|------|
+| `startEditingCell({ rowIndex, colKey })` | 编程式进入单元格编辑 |
+| `stopEditing(cancel?)` | 结束当前编辑会话 |
+| `isEditing()` | 是否存在编辑态 |
+| `isCommitting()` | 是否正在异步提交 |
+| `cancelCommit()` | 中断进行中的异步提交 |
+| `getEditSessionPhase()` | 当前编辑会话阶段 |
+| `getEditingCell()` | 当前主编辑单元格 |
+| `getEditingCells()` | 行编辑模式下所有编辑单元格 |
+| `registerCellEditor(name, editor)` | 注册命名单元格编辑器 |
+| `unregisterCellEditor(name)` | 注销实例级编辑器 |
+
+#### 校验
+
+| 方法 | 说明 |
+|------|------|
+| `validate(options?)` | 校验全表或指定行 |
+| `validateRows(options)` | 校验指定行列表 |
+| `validateCells(options)` | 校验指定单元格列表 |
+| `clearValidation(options?)` | 清除校验视觉反馈 |
+| `clearRowValidation(options)` | 清除指定行校验反馈 |
+| `clearCellValidation(options)` | 清除指定单元格校验反馈 |
+
+#### 行选择 / 索引定位
+
+| 方法 | 说明 |
+|------|------|
+| `toggleRowSelection(rowIds, selected?, force?)` | 切换或设置行 checkbox 选中 |
+| `toggleAllSelection(selected?)` | 表头全选 checkbox 操作 |
+| `setIndexFocus(rowIds)` | 设置索引列辅助定位 |
+
+#### 展开 / 分组 / 树
+
+| 方法 | 说明 |
+|------|------|
+| `expandRow(rowId)` / `collapseRow(rowId)` | 展开/折叠主行 |
+| `isRowExpanded(rowId)` | 主行是否已展开 |
+| `expandAll()` / `collapseAll()` | 全部展开/折叠 |
+| `setRowGroupColumns(colIds)` / `getRowGroupColumns()` | 分组列读写 |
+| `expandGroup(groupId)` / `collapseGroup(groupId)` | 展开/折叠分组节点 |
+| `isGroupExpanded(groupId)` | 分组是否已展开 |
+| `expandNode(rowId)` / `collapseNode(rowId)` | 展开/折叠 tree 节点 |
+| `isNodeExpanded(rowId)` | tree 节点是否已展开 |
+| `getDataPath(rowId)` | 查询行的 dataPath |
+
+#### 批注 / 框选 / 空态
+
+| 方法 | 说明 |
+|------|------|
+| `getCellComment(rowId, colId)` / `setCellComment(...)` | 批注读写 |
+| `refreshCellComments(params?)` | 刷新批注角标 |
+| `getCellRanges()` / `clearCellSelection()` / `addCellRange(params)` | 框选操作 |
+| `getCellSelectionAggregation()` | 当前框选聚合统计 |
+| `copySelectedRangeToClipboard()` / `pasteFromClipboard()` | 剪贴板操作 |
+| `showLoadingOverlay()` / `showNoRowsOverlay()` / `hideOverlay()` | overlay 控制 |
+| `isOverlayShowing()` / `getOverlayType()` | overlay 状态查询 |
+| `refreshDisabledState(params?)` | 重算 disabled 投影 |
+| `refreshCellStyles(params?)` | 重算 cellStyle 投影 |
+
+#### 事件订阅
+
+```ts
+const api = gridRef.value?.api
+const off = api?.on('selectionChanged', (event) => {
+  console.log(event.selectedRowIds)
+})
+// 取消订阅
+off?.()
+```
+
+### rowId 约定
+
+- **入参**：接受 `string | number`，与 `data[rowKey]` 类型一致；API 边界自动 `String()`。
+- **出参 / 事件**：内核 rowId 恒为 `string`（与 DOM `data-row-id` 一致）。
+- **临时行**：新增时省略 `rowKey` 或值为 `null` 时生成 `__mg_tmp_*` 内部 id；`getData()` 导出时对应字段为 `null`。
+
+---
+
+## Slots
+
+MagicGrid 提供静态插槽与动态列插槽两类。
+
+### 布局插槽
+
+#### `#toolbar`
+
+表格顶部工具栏区域。
+
+| 插槽 prop | 类型 | 说明 |
+|-----------|------|------|
+| `api` | `GridApi \| undefined` | GridApi 实例 |
+| `size` | `MagicGridSize` | 当前尺寸 preset |
+| `portalEl` | `HTMLElement \| undefined` | 浮层挂载 portal 元素 |
+
+```vue
+<MagicGrid ...>
+  <template #toolbar="{ api, size }">
+    <button @click="api?.clearAllFilters()">清除筛选</button>
+  </template>
+</MagicGrid>
+```
+
+#### `#status-bar`
+
+完全自定义底部状态栏（提供时替换默认状态栏布局）。
+
+| 插槽 prop | 类型 | 说明 |
+|-----------|------|------|
+| `api` | `GridApi \| undefined` | GridApi 实例 |
+| `totalRowCount` | `number` | 源数据总行数（过滤前） |
+| `displayedRowCount` | `number` | 当前展示行数 |
+| `isFiltered` | `boolean` | 是否处于过滤态 |
+| `selectedRowCount` | `number` | 当前选中行数 |
+| `rowSelectionEnabled` | `boolean` | 是否启用行选择 |
+| `cellSelectionEnabled` | `boolean` | cellSelection 是否启用 |
+| `cellSelectionAggregation` | `CellSelectionAggregation \| null` | 当前选区聚合 |
+| `statusBarRangeAggregationPrecision` | `{ average: number; sum: number }` | 聚合小数位数 |
+| `metrics` | `GridMetrics \| undefined` | 最近一次 metrics |
+
+#### `#status-bar-left` / `#status-bar-right`
+
+默认状态栏布局下的左右区域（未提供 `#status-bar` 时生效）。props 同 `#status-bar`。
+
+```vue
+<MagicGrid ...>
+  <template #status-bar-left="{ displayedRowCount, totalRowCount }">
+    共 {{ totalRowCount }} 行，显示 {{ displayedRowCount }} 行
+  </template>
+  <template #status-bar-right="{ selectedRowCount }">
+    已选 {{ selectedRowCount }} 行
+  </template>
+</MagicGrid>
+```
+
+### 列级动态插槽
+
+插槽名中的 `{colId}` 为列的 `key` 或 `prop`（与 `ColumnDef` 中 `resolveColId` 规则一致）。
+
+#### `#cell-{colId}`
+
+自定义单元格渲染（等价于 `column.cellRenderer`，插槽优先）。
+
+| 插槽 prop | 类型 | 说明 |
+|-----------|------|------|
+| `row` | `RowData` | 行数据 |
+| `value` | `unknown` | 原始值 |
+| `formattedValue` | `string` | 格式化后的值 |
+| `rowIndex` | `number` | rowsToDisplay 中的行下标 |
+| `rowId` | `BusinessRowId` | 行 id |
+| `colId` | `string` | 列 id |
+| `isSummaryRow` | `boolean` | 是否为表尾汇总格 |
+
+```vue
+<MagicGrid :columns="[{ key: 'status', prop: 'status', label: '状态' }]" ...>
+  <template #cell-status="{ value, row }">
+    <span :class="value === 'active' ? 'text-green' : 'text-gray'">
+      {{ value }}
+    </span>
+  </template>
+</MagicGrid>
+```
+
+#### `#cell-editor-{colId}`
+
+自定义单元格编辑器（等价于 `column.cellEditor` 函数形式）。
+
+| 插槽 prop | 类型 | 说明 |
+|-----------|------|------|
+| `row` | `RowData` | 行数据 |
+| `value` | `unknown` | 当前值 |
+| `formattedValue` | `string` | 格式化后的值 |
+| `rowIndex` | `number` | 行下标 |
+| `rowId` | `BusinessRowId` | 行 id |
+| `colId` | `string` | 列 id |
+| `stopEditing` | `(cancel?: boolean) => void` | 结束编辑 |
+
+### 功能插槽
+
+#### `#detail-row`
+
+主从展开行的详情区渲染（与 `detailCellRenderer` prop 二选一）。
+
+| 插槽 prop | 类型 | 说明 |
+|-----------|------|------|
+| `row` | `RowData` | 主行数据 |
+| `rowId` | `string` | 详情行 id |
+| `masterRowId` | `string` | 主行 id |
+| `detailRowData` | `unknown` | 详情区数据 |
+| `loading` | `boolean` | 是否加载中 |
+| `loadFailed` | `boolean` | 是否加载失败 |
+| `loadError` | `unknown` | 加载错误 |
+
+```vue
+<MagicGrid master-detail :get-detail-row-data="fetchDetail" ...>
+  <template #detail-row="{ row, detailRowData, loading }">
+    <div v-if="loading">加载中...</div>
+    <pre v-else>{{ detailRowData }}</pre>
+  </template>
+</MagicGrid>
+```
+
+#### `#tooltip`
+
+全局自定义 tooltip 组件（与 `tooltipComponent` prop 二选一）。接收 `ITooltipParams`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `location` | `'cell' \| 'header' \| 'footer' \| 'statusBar'` | 触发位置 |
+| `value` | `unknown` | 原始值 |
+| `valueFormatted` | `string \| null` | 格式化值 |
+| `colId` / `rowId` | `string` | 列/行 id |
+| `data` | `Record<string, unknown>` | 行数据 |
+| `hideTooltipCallback` | `() => void` | 隐藏 tooltip |
+| `api` | `GridApi` | GridApi 实例 |
+
+#### `#loading` / `#no-rows` / `#no-matching-rows`
+
+空态 overlay 自定义内容（与对应 `*OverlayComponent` prop 二选一）。
+
+| 插槽 prop | 类型 | 说明 |
+|-----------|------|------|
+| `overlayType` | `OverlayType` | `'loading' \| 'noRows' \| 'noMatchingRows'` |
+| `api` | `GridApi` | GridApi 实例 |
+| `overlayText` | `string` | 内置模板文案（可选） |
+
+```vue
+<MagicGrid :data="[]" ...>
+  <template #no-rows="{ api }">
+    <div class="empty-state">
+      <p>暂无数据</p>
+      <button @click="api?.showLoadingOverlay()">刷新</button>
+    </div>
+  </template>
+</MagicGrid>
+```
+
+### 插槽优先级说明
+
+| 能力 | 插槽 | 等价 prop | 优先级 |
+|------|------|-----------|--------|
+| 单元格渲染 | `#cell-{colId}` | `column.cellRenderer` | 插槽覆盖函数 |
+| 单元格编辑 | `#cell-editor-{colId}` | `column.cellEditor`（函数） | 插槽覆盖函数 |
+| 详情行 | `#detail-row` | `detailCellRenderer` | 插槽优先 |
+| Tooltip | `#tooltip` | `tooltipComponent` | 插槽优先 |
+| Loading | `#loading` | `loadingOverlayComponent` | 插槽优先 |
+| 无数据 | `#no-rows` | `noRowsOverlayComponent` | 插槽优先 |
+| 筛选无匹配 | `#no-matching-rows` | `noMatchingRowsOverlayComponent` | 插槽优先 |
+
+---
+
+## 辅助组件
+
+表格列设置（Phase 27）提供一组**独立组件**，对标 AG Grid 的 Side Bar + Columns Tool Panel。只要持有 `GridApi` 即可使用，不强依赖 MagicGrid 内部 DOM。
+
+| 组件 | 职责 |
+|------|------|
+| `ColumnSettingsButton` | 齿轮触发器 + 下拉菜单 + 列设置 Popover（推荐组合使用） |
+| `ColumnSettingsPanel` | 列设置面板本体（可单独嵌入自定义容器） |
+| `ColumnSettingsMenuItem` | 下拉菜单中的自定义菜单项 |
+| `ColumnSettingsMenuIcon` | 菜单项内置图标（Lucide 风格 SVG） |
+
+### 典型集成
+
+推荐放在 MagicGrid `#toolbar` 插槽内，并使用 `portalEl` 将 Popover Teleport 到 Grid 内部 portal，避免被表格容器 `overflow` 裁剪：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  MagicGrid,
+  ColumnSettingsButton,
+  ColumnSettingsMenuItem,
+  ColumnSettingsMenuIcon,
+} from '@taocompany/magic-grid'
+import type { GridApi, ColumnDef, RowData } from '@taocompany/magic-grid'
+
+const columns: ColumnDef[] = [/* ... */]
+const data: RowData[] = [/* ... */]
+
+function onResetColumnOrder(api: GridApi) {
+  api.resetColumnOrder()
+}
+</script>
+
+<template>
+  <MagicGrid :columns="columns" :data="data" row-key="id" height="400">
+    <template #toolbar="{ api, size, portalEl }">
+      <ColumnSettingsButton
+        v-if="api"
+        :grid-api="api"
+        :size="size"
+        :portal-el="portalEl"
+      >
+        <!-- 可选：在下拉菜单中追加自定义项 -->
+        <template #menu>
+          <ColumnSettingsMenuItem @click="onResetColumnOrder(api!)">
+            <template #icon>
+              <ColumnSettingsMenuIcon name="order" />
+            </template>
+            重置列顺序
+          </ColumnSettingsMenuItem>
+        </template>
+      </ColumnSettingsButton>
+    </template>
+  </MagicGrid>
+</template>
+```
+
+也可单独使用面板（例如侧边栏、Drawer 内）：
+
+```vue
+<ColumnSettingsPanel
+  v-if="gridApi"
+  :grid-api="gridApi"
+  :open="panelOpen"
+  @close="panelOpen = false"
+/>
+```
+
+---
+
+### ColumnSettingsButton
+
+表格设置齿轮按钮。点击后先展开**下拉菜单**（含「列设置」「重置」及可选自定义项），选择「列设置」后打开**列设置 Popover 面板**。
+
+#### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `gridApi` | `GridApi` | — | **必填**。Grid 命令式 API |
+| `portalEl` | `HTMLElement` | `'body'` | Teleport 挂载点；MagicGrid `#toolbar` 提供 `portalEl`（`.magic-grid__portal`） |
+| `label` | `string` | `'表格设置'` | 无障碍标签（`aria-label` / `title`）；按钮仅显示 settings 图标 |
+| `disabled` | `boolean` | `false` | 禁用触发器；已打开时不允许再次打开 |
+| `size` | `'mini' \| 'small' \| 'default' \| 'large'` | — | 按钮尺寸；与 MagicGrid `size` 对齐；省略时继承父级 `.magic-grid` CSS 变量 |
+| `open` | `boolean` | — | 受控：列设置面板打开态（`v-model:open`） |
+| `defaultOpen` | `boolean` | `false` | 非受控：列设置面板初始打开态 |
+| `showVisibility` | `boolean` | `true` | 传递给内嵌 `ColumnSettingsPanel`：是否展示列显隐 checkbox |
+| `showFilter` | `boolean` | `true` | 传递给内嵌 `ColumnSettingsPanel`：是否展示筛选展开区 |
+
+#### Events
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `update:open` | `boolean` | 列设置面板打开态变更（配合 `v-model:open`） |
+| `open` | — | 列设置面板打开 |
+| `close` | — | 列设置面板关闭 |
+
+> 下拉菜单的「重置」操作直接调用 `GridApi`，不额外 emit 事件；自定义 `#menu` 项的点击需自行处理。
+
+#### Slots
+
+| 插槽 | 说明 |
+|------|------|
+| `#menu` | 下拉菜单底部自定义菜单项区域；提供时会在内置项与自定义项之间显示分隔线 |
+
+内置下拉菜单项（无需自行实现）：
+
+| 菜单项 | 行为 |
+|--------|------|
+| **列设置** | 打开列设置 Popover 面板 |
+| **重置 → 排序** | 调用 `setSortModel([])` |
+| **重置 → 筛选** | 调用 `clearAllFilters()` |
+| **重置 → 列宽** | 调用 `resetColumnWidths()` |
+| **重置 → 列顺序** | 调用 `resetColumnOrder()` |
+| **重置 → 固定列** | 取消全部用户列 fixed |
+| **重置 → 全部** | 依次执行以上全部重置 |
+
+重置作用域类型 `ColumnSettingsResetScope`：`'sort' | 'filter' | 'width' | 'order' | 'pin' | 'all'`（已从包导出）。
+
+#### Expose
+
+无。通过 Props / Events / Slots 交互即可。
+
+#### 交互行为
+
+- **Esc**：先关闭列设置面板，再关闭下拉菜单
+- **点击外部**：关闭菜单与面板（打开瞬间有短暂防抖，避免误触）
+- **滚动 / resize**：自动重新定位浮层
+- **`portalEl` / `size` 变更**：关闭所有浮层并重建 Teleport
+
+---
+
+### ColumnSettingsPanel
+
+列设置面板本体。按 **左固定 / 中心 / 右固定 / 隐藏** 四组展示用户列，每行支持拖拽排序、排序切换、筛选面板、固定列、显隐控制；面板头部提供「清除全部筛选」。
+
+> 通常由 `ColumnSettingsButton` 内嵌使用；也可单独 import 嵌入任意容器。
+
+#### 面板能力一览
+
+| 能力 | 说明 | 对应 GridApi |
+|------|------|--------------|
+| 列顺序 | lane 内拖拽重排 | `moveColumn` |
+| 列排序 | 点击循环 none → asc → desc | `setSortModel` |
+| 列筛选 | 行内展开筛选面板（与表头 filter 同源） | `setColumnFilter` / `clearAllFilters` |
+| 列固定 | 切换 null / left / right | `setColumnFixed` |
+| 列显隐 | checkbox 切换 hidden | `setColumnsHidden` |
+| 清除全部筛选 | 面板头部按钮 | `clearAllFilters` |
+| 显示全部隐藏列 | hidden 分组底部操作 | `setColumnsHidden(colIds, false)` |
+
+面板打开时自动订阅以下 Grid 事件并刷新 UI，与表头 / 列操作菜单状态同源：
+
+`sortChanged` · `filterChanged` · `columnMoved` · `columnPinned` · `columnHiddenChanged`
+
+#### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `gridApi` | `GridApi` | — | **必填**。Grid 命令式 API |
+| `open` | `boolean` | `true` | 打开态；`false` 时不订阅 Grid 事件（节省开销） |
+| `showVisibility` | `boolean` | `true` | 是否展示列显隐 checkbox |
+| `showFilter` | `boolean` | `true` | 是否展示筛选展开按钮与内嵌筛选面板 |
+
+#### Events
+
+| 事件 | payload | 说明 |
+|------|---------|------|
+| `close` | — | 用户点击面板右上角关闭按钮 |
+
+#### Slots
+
+无公开插槽。面板 UI 由组件内部组合（`ColumnSettingsGroupedLists` · `ColumnSettingsRow` · `ColumnFilterPanelEmbed` 等）。
+
+#### Expose
+
+无。
+
+#### 样式与主题
+
+面板使用 MagicGrid 语义 token（`--mg-color-bg` · `--mg-color-text` · `--mg-color-border` 等），在暗色主题下自动适配。Popover 容器类名：
+
+- `.mg-column-settings` — 面板根
+- `.mg-column-settings-popover` — Popover 外层
+- `.mg-column-settings-portal` — Teleport portal 容器
+
+---
+
+### ColumnSettingsMenuItem
+
+下拉菜单中的可点击菜单项。用于 `#menu` 插槽扩展 `ColumnSettingsButton` 的自定义操作。
+
+#### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `label` | `string` | — | 菜单项文案；也可通过默认插槽覆盖 |
+
+#### Slots
+
+| 插槽 | 说明 |
+|------|------|
+| 默认 | 菜单项文案（优先于 `label` prop） |
+| `#icon` | 菜单项左侧图标区域 |
+
+#### Events
+
+无 Vue 自定义事件。根元素为 `<button>`，可监听原生 DOM 事件：
+
+```vue
+<ColumnSettingsMenuItem @click="handleExport">
+  <template #icon>
+    <ColumnSettingsMenuIcon name="filter" />
+  </template>
+  导出当前视图
+</ColumnSettingsMenuItem>
+```
+
+> 点击自定义菜单项后，`ColumnSettingsButton` 会自动关闭下拉菜单（通过 `@custom-action` 内部处理）。
+
+#### Expose
+
+无。
+
+---
+
+### ColumnSettingsMenuIcon
+
+菜单项内置 SVG 图标组件，渲染 Lucide 风格路径。
+
+#### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `name` | `ColumnSettingsMenuIconName` | — | **必填**。图标名称 |
+| `size` | `number` | `16` | 图标尺寸 px |
+
+#### `ColumnSettingsMenuIconName` 可选值
+
+| name | 用途 |
+|------|------|
+| `sliders-vertical` | 列设置（内置菜单项） |
+| `list-restart` | 重置（内置子菜单） |
+| `sort` | 排序重置 |
+| `filter` | 筛选重置 |
+| `width` | 列宽重置 |
+| `order` | 列顺序重置 |
+| `pin` | 固定列重置 |
+| `all` | 全部重置 |
+
+类型 `ColumnSettingsMenuIconName` 已从包导出：
+
+```ts
+import type { ColumnSettingsMenuIconName } from '@taocompany/magic-grid'
+```
+
+#### Slots / Events / Expose
+
+无。
+
+---
+
+## 相关文档
+
+| 文档 | 说明 |
+|------|------|
+| [`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/39-phase27-table-settings-button.md`](docs/39-phase27-table-settings-button.md) | 列设置按钮设计文档（Phase 27） |
+
+### 校验子路径
+
+```ts
+import { enrichColumnsWithValidation } from '@taocompany/magic-grid/validation'
+```
+
+配合 `ColumnDef.validationRules` 使用 async-validator 规则。
+
+---
+
+## License
+
+MIT © [songjiuzhang](mailto:jiuzhang.song@taoandcompany02.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taocompany/magic-grid",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A high-performance virtual table component library for Vue 3",
   "type": "module",
   "license": "MIT",