@taocompany/magic-grid 0.1.1 → 0.1.3

package/README.md

@@ -8,7 +8,9 @@
 - [快速开始](#快速开始)
 - [Props](#props)
   - [MagicGrid Props](#magicgrid-props)
+    - [Grid 级默认与列级覆盖](#grid-级默认与列级覆盖)
   - [ColumnDef 列定义](#columndef-列定义)
+- [Options 类型参考](#options-类型参考)
 - [Events](#events)
 - [Expose](#expose)
 - [Slots](#slots)
@@ -48,10 +50,14 @@ pnpm add @taocompany/magic-grid async-validator
 
 ### 引入样式
 
+组件样式**不会**随 JS 自动注入，需在应用入口或根组件中**全局引入一次**：
+
 ```ts
 import '@taocompany/magic-grid/style.css'
 ```
 
+> **ColumnSettingsButton / ColumnSettingsPanel** 与 MagicGrid 共用同一份 `style.css`。按钮或下拉菜单若放在页头工具栏等 **MagicGrid 容器外**，同样必须引入该文件；样式 token 已在 `.mg-column-settings-button` / `.mg-column-settings-portal` 上自带 fallback，脱离 `.magic-grid` 也可正常显示。
+
 ---
 
 ## 快速开始
@@ -66,9 +72,9 @@ 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 },
+  { prop: 'name', label: '姓名', width: 120 },
+  { prop: 'age', label: '年龄', width: 80 },
+  { prop: 'city', label: '城市', flex: 1 },
 ]
 
 const data: RowData[] = [
@@ -89,6 +95,8 @@ function onSelectionChanged(event: { selectedRowIds: readonly (string | number)[
     row-key="id"
     height="400"
     row-selection="multiple"
+    sortable
+    filterable
     stripe
     @selection-changed="onSelectionChanged"
   />
@@ -97,6 +105,22 @@ function onSelectionChanged(event: { selectedRowIds: readonly (string | number)[
 
 > **提示**：`data` 应为普通对象数组，避免对行数据使用 `reactive()` 深代理。
 
+上例通过 Grid 级 `sortable` / `filterable` 开启全列默认可排序、可筛选；个别列可用 `sortable: false` / `filterable: false` 关闭。详见 [Grid 级默认与列级覆盖](#grid-级默认与列级覆盖)。
+
+替代写法（逐列显式配置）：
+
+```ts
+const columns: ColumnDef[] = [
+  { prop: 'name', label: '姓名', width: 120, sortable: true },
+  { prop: 'age', label: '年龄', width: 80, sortable: true },
+  { prop: 'city', label: '城市', flex: 1, filterable: true },
+]
+```
+
+```vue
+<MagicGrid :columns="columns" :data="data" row-key="id" height="400" />
+```
+
 ---
 
 ## Props
@@ -162,7 +186,7 @@ function onSelectionChanged(event: { selectedRowIds: readonly (string | number)[
 | `width` | `number` | `40` | 列宽 px（最小 40） |
 | `start` | `number` | `1` | 起始序号（1-based 展示 = rowIndex + start） |
 | `focusMode` | `'single' \| 'multiple'` | `'multiple'` | 辅助定位模式 |
-| `syncToSelectionColumn` | `boolean` | `false` | 索引列定位是否单向同步到行选择列 |
+| `syncToSelectionColumn` | `boolean` | `false`（MagicGrid 组件层默认 `true`） | 索引列定位是否单向同步到行选择列；仅当 `focusMode` 与 `rowSelection` 同为 single 或同为 multiple 时生效 |
 | `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
 | `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
 | `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
@@ -194,6 +218,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'` | 对齐配置 |
 
 #### 表尾汇总
 
@@ -209,6 +234,7 @@ interface RowSelectionConfig {
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `defaultSort` | `SortModelItem[]` | — | 初始排序（挂载时应用一次；v1 仅使用首项） |
+| `sortable` | `boolean` | `false` | 是否允许表头排序；列级 `columns[].sortable` **优先于**本配置；系统列恒为 false |
 | `showUnsortedSortHintOnHover` | `boolean` | `false` | 未排序 sortable 列 hover 显示 faint 双三角 |
 
 #### 列操作
@@ -219,8 +245,8 @@ interface RowSelectionConfig {
 | `resizable` | `boolean` | `true` | 是否允许拖拽调整列宽（列级 `resizable` 优先） |
 | `colResizeDefault` | `'shift'` | — | Shift 模式：拖拽列宽时相邻列反向补偿，总宽不变 |
 | `skipHeaderOnAutoSize` | `boolean` | `false` | 双击 resize 把柄 auto-size 时跳过表头宽度 |
-| `autoSizePadding` | `number` | — | auto-size 内容测量额外 padding（px） |
-| `autoSizeStrategy` | `AutoSizeStrategy` | — | 挂载/首屏 auto-size 策略 |
+| `autoSizePadding` | `number` | `16` | auto-size 内容测量额外 padding（px） |
+| `autoSizeStrategy` | `AutoSizeStrategy` | — | 挂载/首屏 auto-size 策略（见 [AutoSizeStrategy](#autosizestrategy)） |
 | `suppressMoveWhenColumnDragging` | `boolean` | `false` | `true` → 仅 mouseup 提交列序 |
 | `suppressColumnMoveAnimation` | `boolean` | `false` | 关闭列移动 transition |
 | `allowCrossLaneColumnMove` | `boolean` | `false` | 允许 drag/API 跨 fixed lane 并更新列 `fixed` |
@@ -229,8 +255,9 @@ interface RowSelectionConfig {
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `quickFilterText` | `string` | `''` | Grid 级 quick filter 文本 |
-| `floatingFilter` | `boolean` | `false` | 是否显示 floating filter 行 |
+| `filterable` | `boolean` | `false` | 是否允许列筛选；列级 `columns[].filterable` **优先于**本配置；系统列恒为 false |
+| `quickFilterText` | `string` | `''` | Grid 级 quick filter 文本（对 filterable 用户列 OR 式 contains） |
+| `floatingFilter` | `boolean` | `false` | 表头下方 floating filter 行（仅对 filterable 列渲染输入框） |
 | `filterSetValueMode` | `'reserve' \| 'current'` | `'current'` | 值选择搜索时的勾选投影模式 |
 | `filterSetDateLayoutMode` | `'list' \| 'tree'` | `'tree'` | 日期列值选择展示方式 |
 
@@ -240,10 +267,10 @@ interface RowSelectionConfig {
 |------|------|--------|------|
 | `editMode` | `'cell' \| 'row'` | `'cell'` | 编辑范围：单格 / 整行 |
 | `editType` | `CellEditType` | `'singleClick'` | 进入编辑态的触发方式 |
-| `invalidEditValueMode` | `'block' \| 'revert'` | `'block'` | 校验失败后：`block` 保持编辑；`revert` 退出并恢复旧值 |
+| `invalidEditValueMode` | `'block' \| 'revert' \| 'keep'` | `'block'` | 校验失败后：`block` 保持编辑；`revert` 退出并恢复旧值；`keep` 退出编辑但保留无效值 |
 | `rowValidator` | `RowValidator` | — | 行编辑跨字段校验 |
 | `cellEditorRegistry` | `Record<string, CellEditorFn>` | — | 实例级命名编辑器注册表 |
-| `asyncRowMutation` | `AsyncRowMutationHandlers` | — | 异步行 CRUD 持久化钩子 |
+| `asyncRowMutation` | `AsyncRowMutationHandlers` | — | 异步行 CRUD 持久化钩子（见 [AsyncRowMutationHandlers](#asyncrowmutationhandlers)） |
 
 #### 行拖拽与行高
 
@@ -312,7 +339,7 @@ interface RowSelectionConfig {
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `cellCommentsDataSource` | `CellCommentsDataSource` | — | 批注数据源；提供即启用 |
+| `cellCommentsDataSource` | `CellCommentsDataSource` | — | 批注数据源；提供即启用（见 [CellCommentsDataSource](#cellcommentsdatasource)） |
 | `suppressCellComments` | `boolean` | `false` | 全局抑制批注交互 |
 | `cellCommentTrigger` | `'click' \| 'hover'` | `'click'` | 查看已有批注的触发方式 |
 | `cellCommentShowDelay` | `number` | `180` | hover 模式展示延迟 ms |
@@ -322,12 +349,36 @@ interface RowSelectionConfig {
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `cellSelection` | `boolean \| CellSelectionOptions` | `false` | 单元格框选 |
-| `enableCellClipboard` | `boolean` | — | 启用剪贴板（通常随 cellSelection 开启） |
+| `cellSelection` | `boolean \| CellSelectionOptions` | `true` | 单元格框选；MagicGrid 默认开启、`enableColumnSelection` 为 `true`、`handle` 为 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 取消粘贴 |
 
+`CellSelectionOptions` 字段（`cellSelection` 为对象时）：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `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'` | 填充方向 |
+| `fillStrategy` | `'auto' \| 'copy'` | `'copy'` | `'auto'`：数字递增、非数字复制；`'copy'`：始终复制源边值 |
+| `fillReverseStrategy` | `'default' \| 'clear'` | `'default'` | 反拖缩小时：`'default'` 不处理；`'clear'` 置空缩出初始选区的格 |
+| `setFillValue` | `(params: FillOperationParams) => unknown` | — | 自定义填充值；缺省按 `fillStrategy` |
+
+`RangeHandleOptions`（`handle: { mode: 'range' }`）：仅含 `mode: 'range'`，用于右下角拖拽扩展选区。
+
+> 框选详细行为见 [`docs/35-phase24-cell-range-selection.md`](docs/35-phase24-cell-range-selection.md)。
+
 #### Tooltip
 
 | Prop | 类型 | 默认值 | 说明 |
@@ -355,9 +406,13 @@ interface RowSelectionConfig {
 | `overlayNoRowsTemplate` | `string` | — | 无数据模板 HTML |
 | `overlayNoMatchingRowsTemplate` | `string` | — | 筛选无匹配模板 HTML |
 | `loadingOverlayComponent` | `OverlayComponentType` | — | 自定义 loading 组件 |
+| `loadingOverlayComponentParams` | `Record<string, unknown>` | — | loading 组件额外参数 |
 | `noRowsOverlayComponent` | `OverlayComponentType` | — | 自定义无数据组件 |
+| `noRowsOverlayComponentParams` | `Record<string, unknown>` | — | 无数据组件额外参数 |
 | `noMatchingRowsOverlayComponent` | `OverlayComponentType` | — | 自定义筛选无匹配组件 |
+| `noMatchingRowsOverlayComponentParams` | `Record<string, unknown>` | — | 筛选无匹配组件额外参数 |
 | `overlayComponent` | `OverlayComponentType` | — | 通用 overlay 组件 |
+| `overlayComponentParams` | `Record<string, unknown>` | — | 通用 overlay 组件额外参数 |
 | `overlayInteraction` | `boolean` | — | overlay 内容是否可交互 |
 
 #### 状态栏
@@ -365,10 +420,38 @@ interface RowSelectionConfig {
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `showStatusBar` | `boolean` | `true` | 是否显示底部状态栏 |
-| `showDefaultStatusBarPanels` | `boolean` | `true` | 显示默认状态栏面板（行数/筛选态/选中数） |
+| `showDefaultStatusBarPanels` | `boolean` | `true` | 显示默认状态栏左侧面板（行数/筛选态/选中数）；`false` 时仍可自定义 `#status-bar-left` |
 | `showStatusBarRangeAggregation` | `boolean` | `true` | 框选时在状态栏展示平均值/计数/求和 |
 | `statusBarRangeAggregationPrecision` | `number \| { average?: number; sum?: number }` | `2` | 平均值/求和展示小数位数 |
 
+#### Grid 级默认与列级覆盖
+
+以下 Grid Prop 可一次性为**所有用户列**设定默认行为；列级字段显式配置时**以列为准**（对齐 AG Grid `defaultColDef` 语义）：
+
+| Grid Prop | 列级字段 | 默认值 | 说明 |
+|-----------|----------|--------|------|
+| `sortable` | `columns[].sortable` | `false` | 表头点击排序 |
+| `filterable` | `columns[].filterable` | `false` | 列筛选 / 表头 filter 把柄 / quick filter 参与列 |
+| `resizable` | `columns[].resizable` | `true` | 拖拽调整列宽 |
+| `columnMovable` | `columns[].movable` | `true` | 表头拖拽重排列 |
+
+系统列（索引 / 行选择 / 展开 / 分组等）不受 Grid 默认影响，相关能力恒为关闭。
+
+运行时修改 `:sortable` / `:filterable` / `:resizable` 会热更新列模型并刷新表头（无需重建 Grid）。
+
+```vue
+<!-- 全列默认可排序、可筛选；金额列单独关闭 -->
+<MagicGrid
+  :columns="[
+    { prop: 'name', label: '名称' },
+    { prop: 'amount', label: '金额', sortable: false, filterable: false },
+  ]"
+  sortable
+  filterable
+  floating-filter
+/>
+```
+
 ---
 
 ### ColumnDef 列定义
@@ -397,18 +480,18 @@ interface RowSelectionConfig {
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `sortable` | `boolean` | 是否可排序 |
+| `sortable` | `boolean` | 是否可排序；缺省继承 Grid `sortable`（默认 false） |
 | `comparator` | `ColumnComparatorFn` | 自定义排序比较器（asc 语义；desc 由内核取反） |
-| `filterable` | `boolean` | 是否可筛选 |
+| `filterable` | `boolean` | 是否可筛选；缺省继承 Grid `filterable`（默认 false） |
 | `filterType` | `ColumnDataFilterType` | 筛选数据类型；默认 `text` |
-| `filterParams` | `FilterParams` | 列级 filter 参数 |
+| `filterParams` | `FilterParams` | 列级 filter 参数（见 [FilterParams](#filterparams)） |
 | `filterValueGetter` | `(row) => unknown` | 筛选用取值；缺省同 getter/prop |
 | `editable` | `boolean \| (row) => boolean` | 是否可编辑 |
-| `resizable` | `boolean` | 是否允许拖拽调整列宽；缺省继承 Grid `resizable` |
+| `resizable` | `boolean` | 是否允许拖拽调整列宽；缺省继承 Grid `resizable`（默认 true） |
 | `suppressAutoSize` | `boolean` | 禁止 resize 把柄 dblclick / API auto-size |
 | `suppressSizeToFit` | `boolean` | 禁止参与 sizeColumnsToFit |
 | `fixed` | `'left' \| 'right' \| null` | 固定列 |
-| `movable` | `boolean` | 是否允许表头拖拽重排；默认继承 `columnMovable` |
+| `movable` | `boolean` | 是否允许表头拖拽重排；缺省继承 `columnMovable` |
 | `rowDrag` | `boolean` | 该列单元格作为行拖拽起点 |
 | `rowExpand` | `boolean` | 在该列渲染 expand/collapse 控件 |
 | `autoHeight` | `boolean` | 该列内容撑开行高 |
@@ -500,6 +583,321 @@ interface RowSelectionConfig {
 
 ---
 
+## Options 类型参考
+
+下列类型均可从 `@taocompany/magic-grid` 导入，供 Props、GridApi 与事件 payload 使用。
+
+### IndexColumnOptions
+
+索引列配置，通过 `indexColumn` prop 传入（`showIndexColumn=true` 时生效）。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `label` | `string` | `''` | 表头文案 |
+| `width` | `number` | `40` | 列宽 px（最小 40） |
+| `start` | `number` | `1` | 起始序号（1-based 展示 = rowIndex + start） |
+| `focusMode` | `'single' \| 'multiple'` | `'multiple'` | 辅助定位模式 |
+| `syncToSelectionColumn` | `boolean` | core `false` / MagicGrid `true` | 索引列定位单向同步到行选择列 |
+| `index` | `(rowIndex) => number \| string` | — | 自定义序号展示 |
+| `showRowDragHandle` | `boolean` | `false` | 在索引列显示行拖拽把柄 |
+| `enableRowResizer` | `boolean` | `false` | 索引列底边可拖拽调整行高 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+
+### SelectionColumnOptions
+
+行选择列配置，通过 `selectionColumn` prop 传入（`rowSelection !== false` 时生效）。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `width` | `number` | `40` | 列宽 px（最小 40） |
+| `selectAllLabel` | `string` | `'全选'` | 表头全选 checkbox 的 aria-label |
+| `rowLabel` | `(rowIndex) => string` | — | 行 checkbox 的 aria-label 工厂 |
+| `headerAlign` / `headerValign` / `align` / `valign` / `footerAlign` / `footerValign` | 对齐枚举 | `'center'` | 对齐配置 |
+
+### RowSelectionConfig
+
+`rowSelection` 的对象形式：
+
+```ts
+interface RowSelectionConfig {
+  mode: 'single' | 'multiple'
+  /** tree 模式下选中父节点是否级联子孙，默认 true */
+  groupSelectsChildren?: boolean
+}
+```
+
+### CellSelectionOptions
+
+`cellSelection` 的对象形式（`cellSelection: true` 等价 `{}` 并使用默认子项）。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `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'` | 填充方向 |
+| `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
+interface CellRange {
+  startRowIndex: number
+  endRowIndex: number
+  startColId: string
+  endColId: string
+}
+```
+
+### AutoSizeStrategy
+
+挂载 / 首屏列宽策略，通过 `autoSizeStrategy` prop 传入。三种 discriminated union：
+
+**fitGridWidth** — 列宽分配至视口：
+
+```ts
+interface SizeColumnsToFitGridStrategy {
+  type: 'fitGridWidth'
+  defaultMinWidth?: number
+  defaultMaxWidth?: number
+  columnLimits?: Array<{ colId: string; minWidth?: number; maxWidth?: number }>
+}
+```
+
+**fitProvidedWidth** — 分配至指定宽度：
+
+```ts
+interface SizeColumnsToFitProvidedWidthStrategy {
+  type: 'fitProvidedWidth'
+  width: number
+  defaultMinWidth?: number
+  defaultMaxWidth?: number
+  columnLimits?: Array<{ colId: string; minWidth?: number; maxWidth?: number }>
+}
+```
+
+**fitCellContents** — 按单元格内容 auto-size：
+
+```ts
+interface SizeColumnsToContentStrategy {
+  type: 'fitCellContents'
+  skipHeader?: boolean
+  colIds?: readonly string[]
+  defaultMinWidth?: number
+  defaultMaxWidth?: number
+  columnLimits?: Array<{ colId: string; minWidth?: number; maxWidth?: number }>
+  scaleUpToFitGridWidth?: boolean
+}
+```
+
+**SizeColumnsToFitParams**（`GridApi.sizeColumnsToFit(params?)`）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `gridWidth` | `number` | 目标宽度 px；缺省为视口宽度 |
+| `defaultMinWidth` / `defaultMaxWidth` | `number` | 列宽 clamp 默认值 |
+| `columnLimits` | `{ colId, minWidth?, maxWidth? }[]` | 单列限制 |
+| `colIds` | `string[]` | 仅调整指定列 |
+| `onlyScaleUp` | `boolean` | 仅放大以填满视口，不缩小 |
+
+### FilterParams
+
+列级筛选参数，通过 `ColumnDef.filterParams` 传入。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `caseSensitive` | `boolean` | `true` | 文本比较是否区分大小写 |
+| `locale` | `string` | — | 数字 / 日期解析 locale |
+
+### AsyncRowMutationHandlers
+
+异步行 CRUD 持久化钩子，通过 `asyncRowMutation` prop 传入。各 handler 在服务端成功后才 apply 本地；reject 则不写入。
+
+```ts
+interface AsyncRowMutationHandlers {
+  add?: (params: AsyncRowMutationAddParams) => Promise<AsyncRowMutationAddResult | void>
+  update?: (params: AsyncRowMutationUpdateParams) => Promise<void>
+  remove?: (params: AsyncRowMutationRemoveParams) => Promise<void>
+}
+```
+
+| Params 类型 | 主要字段 |
+|-------------|----------|
+| `AsyncRowMutationAddParams` | `rows: { data }[]`、`index?`、`indexMode?`、`signal` |
+| `AsyncRowMutationAddResult` | `rows?: { businessId?, data? }[]` — 写入正式主键或 enrich 字段 |
+| `AsyncRowMutationUpdateParams` | `rows: { rowId, data }[]`、`signal` |
+| `AsyncRowMutationRemoveParams` | `rowIds`、`rows: { rowId, data }[]`、`signal` |
+
+### CellCommentsDataSource
+
+批注持久化数据源，通过 `cellCommentsDataSource` prop 传入。
+
+```ts
+interface CellCommentsDataSource {
+  getComment: (params: CellCommentParams) => CellComment | undefined | null
+  setComment: (params: SetCellCommentParams) => void | Promise<void>
+  init?: (ctx: { api: GridApi }) => void
+  destroy?: () => void
+}
+```
+
+**CellCommentParams**：`{ rowId, colId, data, column }`。
+
+**SetCellCommentParams**：扩展 `CellCommentParams`，含 `comment: CellComment | undefined`（`undefined` 表示删除）。
+
+**CellComment**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `text` | `string` | 批注正文（纯文本） |
+| `readOnly` | `boolean` | `true` 时内置 UI 只读；API 仍可覆盖 |
+| `author` / `createdAt` / `updatedAt` | `string` | 元数据 |
+| `metadata` | `unknown` | 自定义扩展 |
+
+### GetDataOptions
+
+`GridApi.getData(options?)` / `MagicGridExpose.getData(options?)` 参数：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `sourceOrder` | `boolean` | `true` | `true` = source 存储顺序；`false` = 当前 display 顺序 |
+
+### AddRowsOptions / RemoveRowsOptions / PromoteRowIdOptions
+
+GridApi 行 CRUD 参数：
+
+**AddRowsOptions**：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rows` | `{ data: RowData }[]` | — | **必填** |
+| `index` | `number` | 末尾 | 插入起始下标 |
+| `indexMode` | `'source' \| 'display'` | `'source'` | 下标基准 |
+
+**RemoveRowsOptions**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowIds` | `(string \| number)[]` | 按 rowId / 业务主键删除 |
+| `indexes` | `number[]` | 按下标批量删除 |
+| `indexMode` | `'source' \| 'display'` | 下标基准，默认 `'source'` |
+
+**PromoteRowIdOptions**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `string \| number` | 当前 RowNode.id（通常为 `__mg_tmp_*`） |
+| `businessId` | `string \| number` | 正式业务主键，写入 `data[rowKey]` |
+
+### ValidateGridOptions / ValidateRowsOptions / ValidateCellsOptions
+
+GridApi 校验参数：
+
+**ValidateGridOptions**（`validate(options?)`）：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowIds` | `(string \| number)[]` | 全表 | 指定行 |
+| `signal` | `AbortSignal` | — | 中断信号 |
+| `showFeedback` | `boolean` | `true` | 是否更新 invalid 视觉反馈 |
+
+**ValidateRowsOptions**（`validateRows(options)`）：`rowIds` **必填**，其余同 `ValidateGridOptions`。
+
+**ValidateCellsOptions**（`validateCells(options)`）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `cells` | `{ rowId, colId }[]` | **必填** |
+| `signal` | `AbortSignal` | 中断信号 |
+| `showFeedback` | `boolean` | 默认 `true` |
+
+**ClearValidationOptions** / **ClearRowValidationOptions** / **ClearCellValidationOptions**：分别对应 `clearValidation` / `clearRowValidation` / `clearCellValidation`，字段与上述 `rowIds` / `cells` 对应。
+
+### MoveRowOptions / RefreshCellsParams
+
+**MoveRowOptions**（`GridApi.moveRow(rowId, toIndex, indexMode?)` 的对象重载形式）：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rowId` | `string` | — | **必填**。内部 rowId |
+| `toIndex` | `number` | — | **必填**。目标下标 |
+| `indexMode` | `'source' \| 'display'` | `'source'` | 下标基准 |
+| `finished` | `boolean` | `true` | live drag 中间态为 `false` |
+
+**RefreshCellsParams**（`GridApi.refreshCells(params?)`）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowIds` | `string[]` | 限定行 |
+| `colIds` | `string[]` | 限定列 |
+| `force` | `boolean` | 忽略值缓存，强制重绘 |
+
+**RefreshDisabledStateParams** / **RefreshCellStylesParams**（`refreshDisabledState` / `refreshCellStyles`）：可选 `rowIds`、`colIds` 限定重算范围。
+
+### StatusBarRangeAggregationPrecisionInput
+
+`statusBarRangeAggregationPrecision` prop 类型：
+
+```ts
+type StatusBarRangeAggregationPrecisionInput =
+  | number                              // 同时作用于 average / sum
+  | { average?: number; sum?: number }  // 分别指定
+```
+
+默认 `2`（平均值与求和各保留 2 位小数）。
+
+### SummaryMethodParams
+
+`summaryMethod` 回调入参：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `columns` | `Column[]` | 当前列模型 |
+| `data` | `RowData[]` | 按 `summaryScope` 选取的行快照 |
+| `rows` | `RowNode[]` | 对应 RowNode 列表 |
+
+返回值：`Record<colId, string | number | null | undefined>`。
+
+### CellSelectionAggregation
+
+`getCellSelectionAggregation()` 与状态栏 `#status-bar` 插槽的 `cellSelectionAggregation` 字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `count` | `number` | 非空单元格个数（含非数值） |
+| `numericCount` | `number` | 可解析为数值的单元格个数 |
+| `sum` | `number \| null` | 数值之和；无有效数值时为 `null` |
+| `average` | `number \| null` | 数值平均值；无有效数值时为 `null` |
+
+### 剪贴板回调参数
+
+**ProcessCellForClipboardParams** / **ProcessCellFromClipboardParams**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowIndex` / `colId` | `number` / `string` | 格位置 |
+| `rowNode` / `column` | — | 行 / 列模型 |
+| `value` | `unknown` | 复制：formatter/raw 候选；粘贴：clipboard 字符串 |
+| `formatValue` | `(value) => string` | 套列 formatter |
+| `parseValue` | `(text) => unknown` | 走 valueParser |
+
+`ProcessCellFromClipboardParams` 额外含 `oldValue`。
+
+**ProcessDataFromClipboardParams**：`{ data: string[][], anchor: CellPosition }`，其中 `anchor` 为 `{ rowIndex, colId }`。
+
+---
+
 ## Events
 
 MagicGrid 通过 Vue 事件向外暴露 Grid 内核事件。事件名采用 kebab-case。
@@ -1024,6 +1422,8 @@ MagicGrid 提供静态插槽与动态列插槽两类。
 
 表格列设置（Phase 27）提供一组**独立组件**，对标 AG Grid 的 Side Bar + Columns Tool Panel。只要持有 `GridApi` 即可使用，不强依赖 MagicGrid 内部 DOM。
 
+> **样式**：须全局引入 `@taocompany/magic-grid/style.css`（见 [引入样式](#引入样式)）。组件类名以 `mg-column-settings-*` 为前缀。
+
 | 组件 | 职责 |
 |------|------|
 | `ColumnSettingsButton` | 齿轮触发器 + 下拉菜单 + 列设置 Popover（推荐组合使用） |
@@ -1033,7 +1433,9 @@ MagicGrid 提供静态插槽与动态列插槽两类。
 
 ### 典型集成
 
-推荐放在 MagicGrid `#toolbar` 插槽内，并使用 `portalEl` 将 Popover Teleport 到 Grid 内部 portal，避免被表格容器 `overflow` 裁剪：
+#### 方式 A：MagicGrid `#toolbar`（推荐）
+
+Popover Teleport 到 Grid 内部 `.magic-grid__portal`，避免被表格 `overflow` 裁剪；按钮尺寸与 Grid `size` 对齐：
 
 ```vue
 <script setup lang="ts">
@@ -1045,6 +1447,7 @@ import {
   ColumnSettingsMenuIcon,
 } from '@taocompany/magic-grid'
 import type { GridApi, ColumnDef, RowData } from '@taocompany/magic-grid'
+import '@taocompany/magic-grid/style.css'
 
 const columns: ColumnDef[] = [/* ... */]
 const data: RowData[] = [/* ... */]
@@ -1055,7 +1458,7 @@ function onResetColumnOrder(api: GridApi) {
 </script>
 
 <template>
-  <MagicGrid :columns="columns" :data="data" row-key="id" height="400">
+  <MagicGrid :columns="columns" :data="data" row-key="id" height="400" sortable filterable>
     <template #toolbar="{ api, size, portalEl }">
       <ColumnSettingsButton
         v-if="api"
@@ -1078,7 +1481,38 @@ function onResetColumnOrder(api: GridApi) {
 </template>
 ```
 
-也可单独使用面板（例如侧边栏、Drawer 内）：
+#### 方式 B：页头 / 外部工具栏（ERP 常见）
+
+按钮放在 MagicGrid **外部**（如页面「新增」「刷新」旁）时，省略 `portalEl` 即可 Teleport 到 `document.body`；须确保已引入 `style.css`：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { MagicGrid, ColumnSettingsButton } from '@taocompany/magic-grid'
+import type { GridApi, MagicGridExpose } from '@taocompany/magic-grid'
+
+const gridRef = ref<MagicGridExpose>()
+</script>
+
+<template>
+  <div class="page-toolbar">
+    <button>新增用户</button>
+    <button>刷新</button>
+    <ColumnSettingsButton
+      v-if="gridRef?.api"
+      :grid-api="gridRef.api"
+    />
+  </div>
+
+  <MagicGrid ref="gridRef" sortable filterable ... />
+</template>
+```
+
+> 列设置面板内长列名单行截断显示（`text-overflow: ellipsis`），悬停可看完整 `title`。
+
+#### 方式 C：单独嵌入面板
+
+例如侧边栏、Drawer 内：
 
 ```vue
 <ColumnSettingsPanel
@@ -1199,11 +1633,27 @@ function onResetColumnOrder(api: GridApi) {
 
 #### 样式与主题
 
-面板使用 MagicGrid 语义 token（`--mg-color-bg` · `--mg-color-text` · `--mg-color-border` 等），在暗色主题下自动适配。Popover 容器类名：
+样式定义于 `style.css`（源码 `src/styles/tokens/column-settings.less`），主要类名：
 
-- `.mg-column-settings` — 面板根
-- `.mg-column-settings-popover` — Popover 外层
-- `.mg-column-settings-portal` — Teleport portal 容器
+| 类名 | 说明 |
+|------|------|
+| `.mg-column-settings-button` | 齿轮按钮根；**独立使用时在此定义主题 CSS 变量** |
+| `.mg-column-settings-button__trigger` | 可点击触发器（边框 / 背景 / 尺寸） |
+| `.mg-column-settings-menu` | 下拉菜单容器 |
+| `.mg-column-settings-popover` | Popover 定位层（`position: fixed`） |
+| `.mg-column-settings-portal` | Teleport portal；**独立使用时在此定义 z-index 等变量** |
+| `.mg-column-settings` | 列设置面板根 |
+
+主题 token 在 `.magic-grid` 与上述独立根节点上均可生效；在 MagicGrid 内使用时继承 `--mg-color-bg` · `--mg-color-primary` 等表格主题；在外部工具栏使用时自带 light 主题 fallback（`#fff` / `#d1d5db` 等）。暗色主题下若按钮在 Grid 外，可通过外层容器覆盖 CSS 变量：
+
+```css
+.page-toolbar .mg-column-settings-button,
+.page-toolbar .mg-column-settings-portal {
+  --mg-color-column-settings-bg: #1f2937;
+  --mg-color-column-settings-border: #374151;
+  --mg-color-column-settings-text: #f9fafb;
+}
+```
 
 ---
 
@@ -1288,6 +1738,7 @@ 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） |
 
 ### 校验子路径