@taocompany/magic-grid

v0.5.3

Published

2 hours ago

A high-performance virtual table component library for Vue 3

0High
0Medium
0Low

iamrina

vue vue3 virtual-table virtual-grid component-library magic-grid

Magic Grid

面向 Vue 3 的高性能虚拟表格组件库。采用命令式渲染 + 行 DOM 池 + 双轴虚拟化，可稳定承载百万级行数据；API 设计对标 AG Grid 社区版，覆盖排序、筛选、编辑、行分组、树形表格、框选、剪贴板等完整表格能力。

概述

特性

| 类别 | 能力 | |------|------| | 性能 | 行/列双轴虚拟化、DOM 池复用、RAF 帧预算分片、Cell Renderer 滚动调度（idle flush · 按行合并 · placeholder-then-vue）、增量数据管线 | | 数据 | 排序、列筛选、Quick Filter、事务增量更新（applyTransaction）、行 CRUD | | 交互 | 单元格/行编辑（内置 text/number/checkbox/switch · overlay/inline）、校验、行选择、索引列定位、框选与剪贴板 | | 布局 | 固定列、列拖拽/调整宽度、列有效性与显隐（available / hidden）、合并单元格、动态行高、主从展开行 | | 结构 | 行分组、树形表格（含懒加载）、表尾汇总 | | 体验 | 溢出 Tooltip、单元格批注、空态 Overlay、暗色主题、底部状态栏 | | 扩展 | 列设置面板、内置编辑器（text/number/checkbox/switch）、Vue 第三方编辑器 Composable、inline 常驻编辑器、async-validator 校验 |

当前版本：0.3.0（@taocompany/magic-grid）。

环境要求

Node.js >= 20.19
Vue ^3.5.0
async-validator ^4.2.0（校验功能 peer dependency）

安装

pnpm add @taocompany/magic-grid async-validator

引入样式

组件样式不会随 JS 自动注入，需在应用入口或根组件中全局引入一次：

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 语义，渲染路径针对百万级行数据做了专门优化。设计文档见仓库 docs/；Cell Renderer 滚动性能专题见 docs/41-cell-renderer-scroll-performance.md。

分层结构

| 层级 | 职责 | 关键模块 | |------|------|----------| | 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（默认 60ms/帧）；cellRenderer / #cell-xxx 插槽走 f1 低优先级队列，可通过 Cell Renderer 滚动渲染调优；测试场景可调用 flushFrames() 同步 flush。

数据管线顺序

| 模式 | Stage 顺序 | |------|------------| | 扁平表格 | sort → filter → map | | 行分组 | group → filter → sort → aggregate → map | | 树形表格 | tree → filter → sort → map |

summaryScope: 'displayed'、状态栏行数、框选聚合均基于 rowsToDisplay；summaryScope: 'all' 对 sourceRows 全量汇总（忽略 filter）。

快速开始

<script setup lang="ts">
import { ref } from 'vue'
import { MagicGrid } 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>()

const columns: ColumnDef[] = [
  { prop: 'name', label: '姓名', width: 120 },
  { prop: 'age', label: '年龄', width: 80 },
  { prop: 'city', label: '城市', flex: 1 },
]

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"
    sortable
    filterable
    stripe
    @selection-changed="onSelectionChanged"
  />
</template>

提示：data 应为普通对象数组，避免对行数据使用 reactive() 深代理。

上例通过 Grid 级 sortable / filterable 开启全列默认可排序、可筛选；个别列可用 sortable: false / filterable: false 关闭。详见 Grid 级默认与列级覆盖。

替代写法（逐列显式配置）：

const columns: ColumnDef[] = [
  { prop: 'name', label: '姓名', width: 120, sortable: true },
  { prop: 'age', label: '年龄', width: 80, sortable: true },
  { prop: 'city', label: '城市', flex: 1, filterable: true },
]

<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 中创建重量级对象或触发外部副作用；这些函数在滚动时会高频调用。
多列使用 #cell-{colId} Vue 插槽时，滚停后可能出现 renderer 列空白拖尾；见下方 Cell Renderer 滚动渲染与 docs/41-cell-renderer-scroll-performance.md。
合并单元格（enableCellSpan）会启用 style.top 行定位并增加 span cache 开销，仅在确有需求时开启。
生产环境可通过 scroll / data-rendered 事件订阅渲染完成时机；开发调试时可关注 DOM 行池规模与 setData 耗时。

Cell Renderer 滚动渲染

带 cellRenderer 或 #cell-{colId} 插槽的列在滚动时走 f1 异步队列（与 prop / formatter 列的同步 textContent 路径不同）。多 Vue 组件列场景下，可通过以下 Grid 级 prop 调优（默认均保持优化前行为，需显式开启）：

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | scrollEndFlushMs | number | 0 | 滚动停止 debounce 后 flush RAF；多 Vue 列建议 100~200 | | frameBudgetMs | number | 60 | 活跃滚动时每帧任务预算（ms） | | scrollEndFrameBudgetMs | number | -1 | idle flush 帧预算；-1 = 一次跑完 | | cellRendererDefer | 'always' \| 'never' \| 'sync-only' | 'always' | renderer 是否进入 f1；sync-only 仅 Vue renderer 异步 | | deferRowDestroyOnScroll | boolean | false | 滚动 active 期间延迟行 destroy + Vue unmount | | rendererFrameBudgetMs | number | 20 | 滚动 active 时为 f1 预留的每帧保底预算（ms）；0 = 与 p1/p2 共享 | | cellRendererPresentation | 'immediate' \| 'deferred' \| 'placeholder-then-vue' | 'deferred' | placeholder-then-vue：滚动态先显示 formattedValue，idle 后 mount Vue | | rowBuffer | number | 10 | 行虚拟化缓冲；多 Vue 列可降至 3~5 |

列级可选 cellRendererMount: 'vue' | 'sync'，配合 cellRendererDefer: 'sync-only' 精确控制哪些列走 f1。

多 slot 列业务表推荐配置（如 ProductOrder）：

<MagicGrid
  :row-buffer="5"
  :scroll-end-flush-ms="150"
  :renderer-frame-budget-ms="20"
  :defer-row-destroy-on-scroll="true"
  cell-renderer-presentation="placeholder-then-vue"
  cell-renderer-defer="always"
  ...
/>

placeholder-then-vue 模式下，slot 列需配置可读 prop 或 formatter，滚动态才有文字兜底。完整方案见 docs/41-cell-renderer-scroll-performance.md。

默认配置

以下为 <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 | 行虚拟化缓冲行数 | | scrollEndFlushMs | 0 | 滚动停止后 flush RAF（ms）；0 = 关闭 | | frameBudgetMs | 60 | 活跃滚动帧预算（ms） | | scrollEndFrameBudgetMs | -1 | idle flush 帧预算；-1 = 一次跑完 | | cellRendererDefer | 'always' | cellRenderer 调度策略 | | deferRowDestroyOnScroll | false | 滚动 active 期间延迟行 destroy | | rendererFrameBudgetMs | 20 | 滚动 active 时 f1 每帧保底预算（ms） | | cellRendererPresentation | 'deferred' | Vue renderer 呈现策略 | | 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[] | — | 必填。列定义数组；available: false 的项仍可在 prop 中保留，但不会进入 Grid 列模型 | | 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 | 行虚拟化缓冲行数 | | scrollEndFlushMs | number | 0 | 滚动停止 debounce 后 flush RAF（ms）；0 = 关闭 | | frameBudgetMs | number | 60 | 活跃滚动时每帧任务预算（ms） | | scrollEndFrameBudgetMs | number | -1 | scroll idle flush 帧预算；-1 = 一次跑完 | | cellRendererDefer | 'always' \| 'never' \| 'sync-only' | 'always' | cellRenderer 是否进入 f1 异步队列 | | deferRowDestroyOnScroll | boolean | false | 滚动 active 期间延迟行 destroy + Vue unmount | | rendererFrameBudgetMs | number | 20 | 滚动 active 时为 f1 预留的每帧保底预算（ms）；0 = 与 p1/p2 共享 | | cellRendererPresentation | 'immediate' \| 'deferred' \| 'placeholder-then-vue' | 'deferred' | Vue renderer 呈现策略；详见 Cell Renderer 滚动渲染 | | 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（MagicGrid 组件层默认 true） | 索引列定位是否单向同步到行选择列；仅当 focusMode 与 rowSelection 同为 single 或同为 multiple 时生效 | | index | (rowIndex) => number \| string | — | 自定义序号展示 | | showRowDragHandle | boolean | false | 在索引列显示行拖拽把柄 | | enableRowResizer | boolean | false | 索引列底边可拖拽调整行高 | | headerAlign / headerValign / align / valign / footerAlign / footerValign | GridHorizontalAlign / GridVerticalAlign | 'center' | 对齐配置 |

行选择

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | rowSelection | 'single' \| 'multiple' \| false \| RowSelectionConfig | 'single' | 行选择模式；false 禁用 | | selectionColumn | SelectionColumnOptions | — | 行选择列配置 | | selectable | SelectableFn | — | 行 checkbox 是否可勾选；省略时全部可选 | | reserveSelection | boolean | false | 数据刷新后是否保留选中行 | | isRowDisabled | boolean \| IsRowDisabledFn | — | 行级禁用（该行全部数据列 disabled） |

RowSelectionConfig：

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 工厂 | | headerAlign / headerValign / align / valign / footerAlign / footerValign | GridHorizontalAlign / GridVerticalAlign | 'center' | 对齐配置 |

表尾汇总

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | showSummary | boolean | false | 是否展示表尾汇总行 | | summaryScope | 'displayed' \| 'all' | 'displayed' | 汇总范围：displayed 当前可见行；all 全量 sourceRows | | summaryRowHeight | number | — | 汇总行高度 px；未传时跟随 rowHeight | | summaryMethod | SummaryMethod | — | 全局汇总方法（优先级高于列级 summaryAgg） |

排序

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | defaultSort | SortModelItem[] | — | 初始排序（挂载时应用一次；v1 仅使用首项） | | sortable | boolean | false | 是否允许表头排序；列级 columns[].sortable 优先于本配置；系统列恒为 false | | 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 | 16 | auto-size 内容测量额外 padding（px） | | autoSizeStrategy | AutoSizeStrategy | — | 挂载/首屏 auto-size 策略（见 AutoSizeStrategy） | | suppressMoveWhenColumnDragging | boolean | false | true → 仅 mouseup 提交列序 | | suppressColumnMoveAnimation | boolean | false | 关闭列移动 transition | | allowCrossLaneColumnMove | boolean | false | 允许 drag/API 跨 fixed lane 并更新列 fixed |

筛选

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | 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' | 日期列值选择展示方式 |

编辑

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | editBehavior | CellEditBehavior | 'cell' | 编辑范围：单格 / 整行 | | editType | CellEditType | 'singleClick' | 进入编辑态的触发方式 | | invalidEditValueMode | 'block' \| 'revert' \| 'keep' | 'block' | 校验失败后：block 保持编辑；revert 退出并恢复旧值；keep 退出编辑但保留无效值 | | rowValidator | RowValidator | — | 行编辑跨字段校验 | | cellEditorRegistry | Record<string, CellEditorFn> | — | 实例级命名编辑器注册表 | | asyncRowMutation | AsyncRowMutationHandlers | — | 异步行 CRUD 持久化钩子（见 AsyncRowMutationHandlers） |

行拖拽与行高

| 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 | — | 自定义分组单元格渲染器 |

编辑：启用单元格编辑时，仅 leaf 数据行可进入编辑态；groupHeader / groupFooter 不渲染 inline 或 overlay 编辑器（由 isCellEditable + cellCtrl 共同保证）。

树形表格

| 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 | — | 批注数据源；提供即启用（见 CellCommentsDataSource） | | suppressCellComments | boolean | false | 全局抑制批注交互 | | cellCommentTrigger | 'click' \| 'hover' | 'click' | 查看已有批注的触发方式 | | cellCommentShowDelay | number | 180 | hover 模式展示延迟 ms | | cellCommentHideDelay | number | 220 | 离开 cell/popup 后隐藏延迟 ms |

框选与剪贴板

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | cellSelection | boolean \| CellSelectionOptions | true | 单元格框选；MagicGrid 默认开启、enableColumnSelection 为 true、handleMode 为 off；Grid API 未传时默认关闭 | | enableCellCopy | boolean | true | Ctrl+C / copySelectedRangeToClipboard | | enableCellPaste | boolean | false | Ctrl+V / pasteFromClipboard | | processCellForClipboard | ProcessCellForClipboardFn | — | 复制单格时自定义导出值 | | processCellFromClipboard | ProcessCellFromClipboardFn | — | 粘贴单格时预处理 clipboard 字符串 | | processDataFromClipboard | ProcessDataFromClipboardFn | — | 整表粘贴前处理 TSV 矩阵；return null 取消粘贴 |

CellSelectionOptions 字段（cellSelection 为对象时）：

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | suppressMultiRanges | boolean | true | true 时仅允许单个 range | | enableColumnSelection | boolean | MagicGrid true / Grid API false | 点击表头选中整列 | | 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 |

FillOperationParams：{ rowNode, column, baseValue, step, direction }。

框选行为要点：

鼠标拖拽或 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

| 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 组件 | | 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 内容是否可交互 |

状态栏

| 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 级默认与列级覆盖

以下 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）。

<!-- 全列默认可排序、可筛选；金额列单独关闭 -->
<MagicGrid
  :columns="[
    { prop: 'name', label: '名称' },
    { prop: 'amount', label: '金额', sortable: false, filterable: false },
  ]"
  sortable
  filterable
  floating-filter
/>

ColumnDef 列定义

每列通过 columns 数组传入。key 为列唯一标识，缺省等于 prop。

标识与展示

| 字段 | 类型 | 说明 | |------|------|------| | key | string | 列唯一标识（colId），缺省等于 prop | | prop | string | 数据字段 | | label | string | 表头文案 |

列有效性与显隐

通过 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 | | 列设置面板 | 不出现（未注册进模型） | 出现在「隐藏」分组 | | 典型用途 | 按权限/场景裁剪列定义 | 用户临时隐藏列 |

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 列显隐语义一致）。

尺寸

| 字段 | 类型 | 说明 | |------|------|------| | width | number | 固定列宽 px | | minWidth | number | 最小列宽 px | | maxWidth | number | 最大列宽 px | | flex | number | 弹性列宽权重 |

行为

| 字段 | 类型 | 说明 | |------|------|------| | sortable | boolean | 是否可排序；缺省继承 Grid sortable（默认 false） | | comparator | ColumnComparatorFn | 自定义排序比较器（asc 语义；desc 由内核取反） | | filterable | boolean | 是否可筛选；缺省继承 Grid filterable（默认 false） | | filterType | ColumnDataFilterType | 筛选数据类型；默认 text | | filterParams | FilterParams | 列级 filter 参数（见 FilterParams） | | filterFormatter | (row) => unknown | 筛选用取值；缺省 formatter → valueGetter → prop | | editable | boolean \| (row) => boolean | 是否可编辑 | | resizable | boolean | 是否允许拖拽调整列宽；缺省继承 Grid resizable（默认 true） | | 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 | 相邻等值自动纵向合并 |

数据转换与渲染

| 字段 | 类型 | 说明 | |------|------|------| | valueGetter | (row, value) => unknown | 取值转换 | | formatter | (row, value) => string | 展示格式化 | | cellRenderer | CellRendererFn | 自定义单元格渲染器（函数；Vue 组件通过 #cell-{colId} 插槽） | | cellRendererMount | 'vue' \| 'sync' | 列级 renderer 挂载类型；配合 cellRendererDefer: 'sync-only' 使用 | | cellEditor | CellEditorDef | 自定义单元格编辑器（函数、内置 text/number/checkbox/switch、或命名引用） | | checkboxEditorParams | CheckboxEditorParams | 内置 checkbox：自定义选中/未选中写回值（默认 true/false） | | switchEditorParams | SwitchEditorParams | 内置 switch：自定义开启/未开启写回值（默认 true/false） | | 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 | GridHorizontalAlign / GridVerticalAlign | 表头对齐；默认 center | | align / valign | GridHorizontalAlign / GridVerticalAlign | 表体对齐；默认 center | | footerAlign / footerValign | GridHorizontalAlign / GridVerticalAlign | 表尾对齐；默认 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 组件参数 |

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 | GridHorizontalAlign / GridVerticalAlign | 'center' | 对齐配置 |

SelectionColumnOptions

行选择列配置，通过 selectionColumn prop 传入（rowSelection !== false 时生效）。

RowSelectionConfig

rowSelection 的对象形式：

interface RowSelectionConfig {
  mode: 'single' | 'multiple'
  /** tree 模式下选中父节点是否级联子孙，默认 true */
  groupSelectsChildren?: boolean
}

CellSelectionOptions

cellSelection 的对象形式（cellSelection: true 等价 {} 并使用默认子项）。

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | suppressMultiRanges | boolean | true | 仅允许单个 range | | enableColumnSelection | boolean | MagicGrid true / Grid API false | 点击表头选中整列 | | 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 }。

CellRange（addCellRange / getCellRanges 返回值）：

interface CellRange {
  startRowIndex: number
  endRowIndex: number
  startColId: string
  endColId: string
}

AutoSizeStrategy

挂载 / 首屏列宽策略，通过 autoSizeStrategy prop 传入。三种 discriminated union：

fitGridWidth — 列宽分配至视口：

interface SizeColumnsToFitGridStrategy {
  type: 'fitGridWidth'
  defaultMinWidth?: number
  defaultMaxWidth?: number
  columnLimits?: Array<{ colId: string; minWidth?: number; maxWidth?: number }>
}

fitProvidedWidth — 分配至指定宽度：

interface SizeColumnsToFitProvidedWidthStrategy {
  type: 'fitProvidedWidth'
  width: number
  defaultMinWidth?: number
  defaultMaxWidth?: number
  columnLimits?: Array<{ colId: string; minWidth?: number; maxWidth?: number }>
}

fitCellContents — 按单元格内容 auto-size：

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 则不写入。

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 传入。

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 类型：

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 }。

筛选模型参考

筛选状态由 FilterModel 表示：Record<colId, FilterCondition>。通过 setFilterModel / getFilterModel / filter-changed 事件读写。

ColumnFilter（内置 UI / API 通用）

单列条件结构（filterType 决定可用算子）：

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（编程式）

interface CustomColumnFilter {
  predicate: (value: unknown, row: RowData) => boolean
}

通过 setColumnFilter(colId, { predicate: ... }) 设置；getColumnFilter 可读回。与内置 UI 筛选可并存（同一 colId 以后写入者为准）。

示例

// 单列文本 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。除 Vue 事件外，也可通过 gridRef.value?.api.on(...) 订阅 camelCase 内核事件（见 Expose）。

生命周期

| Vue 事件 | 内核事件 | 频率 | 说明 | |----------|----------|------|------| | @grid-ready | gridReady | 每次 Grid 实例创建 | initGrid 完成、setData 已调用；event.api 可立即使用 | | @grid-destroyed | gridDestroyed | 每次 Grid 实例销毁 | reinit 或组件卸载前；event.reason 为 'reinit' | 'unmount' | | @first-rendered | firstRendered | 每个实例一次 | 该实例首次 RAF 渲染完成；payload 含 api 与 metrics |

@data-rendered 仍表示每一轮数据渲染完成（见下节），与 @first-rendered 语义分离。

<script setup lang="ts">
import { useGridLifecycle } from '@taocompany/magic-grid'

const lifecycle = useGridLifecycle({
  onReady: ({ api }) => {
    api.setSortModel([{ colId: 'name', sort: 'asc' }])
  },
  onDestroyed: ({ reason }) => {
    if (reason === 'reinit') {
      // 清理旧 api 订阅
    }
  },
  onFirstRendered: ({ api }) => {
    api.ensureIndexVisible(0, 'top')
  },
})
</script>

<template>
  <MagicGrid :columns="columns" :data="rows" v-on="lifecycle" />
</template>

也可直接在模板绑定 @grid-ready / @grid-destroyed / @first-rendered。

内核订阅（payload 与 Vue 事件相同）：

function onGridReady({ api }: GridReadyEvent) {
  const off = api.on('selectionChanged', handler)
  // 在 @grid-destroyed 或 api.on('gridDestroyed') 里 off()
}

渲染与滚动

`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。

交互

`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 列表 |

编辑

`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 事件。

校验

`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 模式 |

排序与筛选

`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）。

列

`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 与拖拽

`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 | 触发来源 |

展开行

`row-expanded` / `row-collapsed`

payload 为 RowExpansionChangedEvent：

| 字段 | 类型 | 说明 | |------|------|------| | rowId | BusinessRowId | 主行 id | | expanded | boolean | 展开 / 折叠 |

行分组

`row-group-opened`

| 字段 | 类型 | 说明 | |------|------|------| | groupId | string | 分组节点 id | | expanded | boolean | 展开 / 折叠 | | field | string | 分组字段 | | key | string | 分组键值 | | level | number | 分组层级 | | source | RowGroupingSource | 触发来源 |

`row-group-changed`

| 字段 | 类型 | 说明 | |------|------|------| | columns | string[] | 当前分组列 id 列表 | | source | RowGroupingSource | 触发来源 |

树形表格

`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 | 是否被中断 |

批注

`cell-comment-changed`

| 字段 | 类型 | 说明 | |------|------|------| | rowId / colId | — | 格位置 | | comment | CellComment \| undefined | 新批注；undefined 表示删除 |

框选

`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）实际变更的格数 |

空态

`overlay-shown` / `overlay-hidden`

| 字段 | 类型 | 说明 | |------|------|------| | overlayType | 'loading' \| 'noRows' \| 'noMatchingRows' | overlay 类型 |

事件监听示例

<MagicGrid
  @cell-value-changed="({ rowId, colId, newValue, oldValue }) => { ... }"
  @sort-changed="(model) => { ... }"
  @filter-changed="(model) => { ... }"
/>

Expose

通过组件 ref 获取 MagicGridExpose 实例，进行命令式操作。

MagicGridExpose 方法

| 成员 | 类型 | 说明 | |------|------|------| | api | 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 待渲染帧（测试/同步场景） | | getPendingFrameTaskCount() | () => number | RAF 队列待处理任务总数 | | getPendingRendererTaskCount() | () => number | f1 队列待处理 cellRenderer 任务数 |

类型定义

interface MagicGridExpose {
  api: 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[]
  applyTransaction: (transaction: RowTransaction) => Promise<RowNodeTransaction | undefined>
  beginUpdate: () => void
  endUpdate: () => void
  ensureIndexVisible: (index: number, position?: 'top' | 'bottom' | 'middle') => void
  flushFrames: () => void
  getPendingFrameTaskCount: () => number
  getPendingRendererTaskCount: () => number
}

使用示例

<script setup lang="ts">
import { ref } from 'vue'
import type { GridReadyEvent, MagicGridExpose } from '@taocompany/magic-grid/types/core'

const gridRef = ref<MagicGridExpose>()

function onGridReady({ api }: GridReadyEvent) {
  api.setSortModel([{ colId: 'name', sort: 'asc' }])
}

async function addRow() {
  await gridRef.value?.applyTransaction({
    add: [{ id: Date.now(), name: '新行' }],
  })
}
</script>

<template>
  <MagicGrid ref="gridRef" @grid-ready="onGridReady" ... />
</template>

获取 api 的推荐方式见 Events · 生命周期。ref 亦可直接调用：gridRef.value?.api?.getData()。

在 computed / 模板中追踪 api 时，可用 useGridApi(gridRef)（等价于 computed(() => gridRef.value?.api)）。

GridApi（`gridRef.value?.api`）

api 是完整的命令式 API 面。以下按职责分组列出全部公开方法；入参 rowId 均接受 string | number，出参 rowId 恒为 string。

数据

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | 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() | 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) | 全局 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?) | finished 默认 true | 设置单行高度并 pinned | | setRowHeights(changes, finished?) | { rowId, height }[] | 批量设置行高 | | getRowHeight(rowId) | — | 读取行当前有效高度；不存在返回 null | | resetRowHeights(rowIds?) | 省略则全部 | 清除 pinned 并重算行高 | | updateDimensions(params) | { rowHeight?, rowHeightMin?, rowHeightMax? } | 热更新默认行高与 clamp |

渲染 / 视口

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | 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 | 读取渲染与滚动指标 | | getPendingFrameTaskCount() | — | number | RAF 队列待处理任务总数 | | getPendingRendererTaskCount() | — | number | f1 队列待处理 cellRenderer 任务数 | | beginUpdate() / endUpdate() | — | void | 批量更新（与 applyTransaction 配对） | | scrollTo(scrollTop, scrollLeft?) | px | void | 编程式滚动 |

编辑

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | startEditingCell({ rowIndex, colKey }) | colKey = colId 或 prop | void | 编程式进入编辑 | | stopEditing(cancel?) | cancel 默认 false | Promise<void> | 结束编辑；true 丢弃修改 |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Magic Grid

目录

概述

特性

环境要求

安装

引入样式

架构与设计

分层结构

渲染模型

数据管线顺序

快速开始

数据与性能最佳实践

行数据

列定义

性能提示

Cell Renderer 滚动渲染

默认配置

尺寸 preset（size）

基础与外观

对齐

虚拟化与导航

索引列

行选择

表尾汇总

排序 / 筛选 / 列操作

编辑

行拖拽与行高

合并 / 展开 / 分组 / 树

批注

框选与剪贴板

Tooltip

空态 Overlay

状态栏

ColumnDef 列级默认

Props

MagicGrid Props

基础

外观

对齐（全局默认）

虚拟化与导航

索引列

行选择

表尾汇总

排序

列操作

筛选

编辑

行拖拽与行高

合并单元格

主从展开行

行分组

树形表格

单元格批注

框选与剪贴板

Tooltip

空态 Overlay

状态栏

Grid 级默认与列级覆盖

ColumnDef 列定义

标识与展示

列有效性与显隐

尺寸

行为

行分组（需 rowGrouping: true）

合并单元格（需 enableCellSpan: true）

数据转换与渲染

校验

剪贴板

汇总

对齐

禁用与样式

Tooltip

Options 类型参考

尺寸 preset（`size`）

行分组（需 `rowGrouping: true`）

合并单元格（需 `enableCellSpan: true`）

`scroll`

`data-rendered`

`cell-clicked`

`row-click` / `row-dblclick`

`selection-changed`

`index-focus-changed`

`cell-editing-started`

`cell-editing-stopped`

`cell-value-changed`

`cell-commit-started` / `cell-commit-finished`

`edit-commit-aborted`

`row-editing-started`

`row-editing-stopped`

`row-value-changed`