@taocompany/magic-grid

Magic Grid

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

目录

• 概述
• 架构与设计
• 快速开始
• 行移动
  • 核心概念：source 与 display
  • 前置配置
  • 平铺表：UI 拖拽与 API
  • 步进换序 moveUp / moveDown
  • 分组表：组内换序
  • indexMode 说明
  • 约束与常见失败原因
  • moveRows 参数与返回值
• 数据与性能最佳实践
  • Cell Renderer 滚动渲染
• 树形表格
  • 概述与核心概念
  • 快速上手
  • 配置项详解
  • 数据模型与 getDataPath
  • 树列 UI 与系统列
  • 展开与折叠
  • 树形懒加载
  • 排序、筛选与汇总
  • 行选择与 groupSelectsChildren
  • 行拖拽与层级变更
  • 与其它能力叠加
  • 常见错误与排查
• 默认配置
• Props
  • MagicGrid Props
    • Grid 级默认与列级覆盖
  • ColumnDef 列定义
    • 列有效性与显隐
• Options 类型参考
• 筛选模型参考
• Events
• Expose
• Slots
• 单元格编辑
  • 呈现模式：overlay 与 inline
  • 内置编辑器
  • Vue 自定义编辑器与生命周期
• 数据校验
• 键盘导航与快捷键
• 辅助组件
  • ColumnSettingsButton
  • ColumnSettingsPanel
  • ColumnSettingsMenuItem
  • ColumnSettingsMenuIcon
• 包入口与导出
• TypeScript 集成
• 类型与校验子路径

概述

特性

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

上手路径：安装 → 快速开始 → 按需查阅 行移动、树形表格 等专题，以及下文 Props / Events / GridApi 索引。

环境要求

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

安装

pnpm add @taocompany/magic-grid async-validator

引入样式

样式不会随 JS 自动注入。须先 token、后 style（全局引入一次）：

import '@taocompany/magic-grid/tokens.css'
import '@taocompany/magic-grid/style.css'

ColumnSettingsButton / ColumnSettingsPanel 与 MagicGrid 共用上述两份 CSS。按钮若在 MagicGrid 容器外，同样必须引入；列设置相关 token 在 .mg-column-settings-button / .mg-column-settings-portal 上也会注入，脱离 .magic-grid 可正常显示。主题拆分见 docs/48-theme-tokens-style-split.md；平台自定义 token 与可视化导出方案见 docs/49-theme-studio.md（在 tokens.css 之后加载 mg-theme-overrides.css）。

架构与设计

Magic Grid 采用 命令式渲染内核 + Vue 薄封装 的分层架构，对标 AG Grid 社区版 API 语义，渲染路径针对百万级行数据做了专门优化。

分层结构

渲染模型

• 行虚拟化：仅渲染视口 + rowBuffer 缓冲行；行 DOM 在行池内按 rowKey 复用，滚动时更新内容与位置。
• 列布局：左固定 / 中心 / 右固定三 lane；中心 lane 随横滚分配列宽。
• 增量更新：applyTransaction、setData 走 RowNode 增量管线；beginUpdate / endUpdate 可合并多次刷新。
• 帧预算：大批量 DOM 写入分片到 requestAnimationFrame（默认 60ms/帧）；cellRenderer / #cell-xxx 插槽走 f1 低优先级队列，可通过 Cell Renderer 滚动渲染 调优；测试场景可调用 flushFrames() 同步 flush。

数据管线顺序

详见 树形表格 专章。

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/tokens.css'
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" />

行移动

MagicGrid 支持编程式 API与索引列 UI 拖拽两种方式调整行序。无论哪种方式，最终都修改 source 数组（即 api.getData() / ref.getData() 返回的顺序），表格按当前 sort / filter / 分组 / 树形规则重新计算可见顺序（rowsToDisplay）。

核心概念：source 与 display

分组表 source 序：开启 rowGrouping 后，setData / 事务 / 分组键配置变更触发的全量 refresh 前，source 会按分组键 collation 归一化（组间 groupComparator，组内稳定相对顺序）。因此稳态下 getData() 已是「组块 + 组内序」，不是长期交错的 raw 数组。展开/折叠（map-only refresh）不会重排 source。

组内换序只改变 source 中同组 leaf 的相对位置，不会把行移到另一组（跨组须改分组字段值）。

行移动前置配置

<MagicGrid
  show-index-column
  :index-column="{ showRowDragHandle: true, focusMode: 'multiple' }"
  row-drag-managed
  @row-moved="onRowMoved"
/>

平铺表：UI 拖拽与 API

UI 拖拽：在索引列 focus 一行或多行 → 拖左侧 handle → 松手后 source 顺序更新。

编程式 API：

const api = gridRef.value?.api

// 移动单行：将 id=3 的行移到 source 下标 0
api?.moveRow(3, 0)

// 批量移动：将 id 2、3、4 作为一块移到 source 下标 0，块内相对顺序不变
api?.moveRows({ rowIds: [2, 3, 4], toIndex: 0 })

// 结合索引列 focus（默认 mode: 'all'，含临时行 internalRowId）
const rowIds = api?.getIndexFocusedRowIds() ?? []
if (rowIds.length > 0) {
  api.moveRows({ rowIds, toIndex: 0, indexMode: 'display' })
}

moveRows 不读取 checkbox 选区（rowSelection）。若需按 checkbox 选中移动，请 generateSelectedRowIds(getSelectedRows())。 勿将 indexFocusChanged 的 focusedRowIds（临时行为 null）直接传给 moveRows；请用 getIndexFocusedRowIds() 或 generateFocusedRowIds(focusedRows)。

返回值 RowMoveResult：{ moved: true, fromIndex, toIndex, moves? } 或 { moved: false, reason }。失败时 不修改 source，不 emit row-moved。

步进换序 moveUp / moveDown

一行代码在相邻行之间步进换序，返回移动后的 RowSnapshot；边界或行不存在时 null。

import { generateRowId } from '@taocompany/magic-grid'

const row = api.getIndexFocusedRows()[0]
if (!row) return

const snapshot = api.moveUp(generateRowId(row))   // 上移一位
// api.moveDown(generateRowId(row))              // 下移一位
// snapshot?.sourceIndex · snapshot?.rowIndex    // 移动后的下标

Playground：/docs/row-move-step（平铺）· /docs/row-move-step-grouped（分组）。

分组表：组内换序

开启 rowGrouping 后，行移动**限定在同一分组下的数据行（leaf）**内，不可跨组、不能通过 drag/API 改分组字段。

<MagicGrid
  row-grouping
  show-group-header
  show-index-column
  :index-column="{ showRowDragHandle: true, focusMode: 'multiple' }"
  row-drag-managed
  :columns="[
    { prop: 'department', rowGroup: true, rowGroupIndex: 0, label: '部门', width: 120 },
    { prop: 'name', label: '姓名', width: 120 },
  ]"
/>

推荐：组内步进用上一节的 moveUp / moveDown（无需手算邻居下标）。

高级：moveRow / moveRows + indexMode: 'display'（与 UI drag 同语义）：

const rowIds = api.getIndexFocusedRowIds()
if (rowIds.length === 0) return

const rowId = rowIds[0]!
const department = api.getData().find((r) => String(r.id) === String(rowId))?.department
const groupLeaves = api.getData().filter((r) => r.department === department)
const pos = groupLeaves.findIndex((r) => String(r.id) === String(rowId))
const neighbor = groupLeaves[pos - 1] // 上移时
if (!neighbor) return

const toIndex = api.getRowIndex(neighbor.id, { type: 'display' })
if (toIndex == null) return

api.moveRow(rowId, toIndex, 'display')

跨组时返回 { moved: false, reason: 'cannot move rows across groups' }。

完整示例：Playground /docs/row-move-grouped。

indexMode 说明

sort 或 filter 激活时：moveRow / moveRows / moveUp / moveDown 与 managed 拖拽 handle 全部不可用；须先 clearAllFilters() / setSortModel([])。

约束与常见失败原因

常见 reason：row move is not allowed while sort or filter is active · no rows to move · selected rows must belong to the same group · cannot move rows across groups · selected rows must belong to the same tree parent

事件

moveRows 参数与返回值

MoveRowsGridApiOptions：

RowMoveResult：

moveRow(rowId, toIndex, indexMode?) 为单行语法糖；moveRows 在 rowIds.length === 1 时与之等价。更多 API 索引见 GridApi、事件见 row-moved。

数据与性能最佳实践

行数据

• 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 滚动渲染。
• 合并单元格（enableCellSpan）会启用 style.top 行定位并增加 span cache 开销，仅在确有需求时开启。
• 生产环境可通过 @scroll（ScrollEvent）监听滚动位置，通过 @data-rendered（GridMetrics）订阅渲染完成时机；开发调试时可关注 DOM 行池规模与 setData 耗时。

Cell Renderer 滚动渲染

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

列级可选 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，滚动态才有文字兜底。调优项见上表。

树形表格

树形表格（Tree Table）在 扁平 data 数组 上，通过 getDataPath 为每行提供 从根到当前节点的路径（string[]），内核据此构建层级并 DFS 投影 为可见的 rowsToDisplay。对标 AG Grid Tree Data 社区版语义。

与行分组互斥：tree: true 与 rowGrouping: true 不得同时生效。双开时控制台 dev 警告，tree 优先，rowGrouping 及 ColumnDef.rowGroup 被忽略。flat / group / tree 三选一，见 概述与核心概念。

概述与核心概念

为什么用扁平数组 + getDataPath？

Magic Grid 不支持嵌套 children 字段作为树数据源（与 AG Grid CSRM 一致）。所有行仍存放在 同一个 data 数组 中；层级关系完全由 getDataPath({ data }) => string[] 表达：

示例路径（组织树）：

路径规则（必须遵守）

1. 前缀唯一确定父子：['A','B'] 的父路径必须是 ['A']；缺父路径 → 建树 throw。
2. 同一路径不得对应多行：重复路径 → 建树 throw。
3. 路径段为任意字符串：可含中文、空格、特殊字符；内核用 \0 拼接做内部 key。
4. rowKey 必须稳定唯一：与 flat 表格相同；临时行内部 id 为 __MG_TMP__::*，落库后 promoteRowId。

数据管线（tree 模式）

启用 tree: true 后，阶段顺序为：

sourceRows（flat）
  → [tree] TreeBuildStage（getDataPath 建树）
  → [filter] 递归过滤 · 空枝剪枝
  → [sort] 同级兄弟排序（不跨层）
  → [map] DFS 扁平化（折叠跳过子树）
  → [afterMap] detail 行注入（若 masterDetail）
  → positionRows → displayRows

• expand/collapse 走 map-only 快路径（refreshModel({ stages: ['map'] })），不重跑 tree/filter/sort。
• summaryScope: 'displayed'、状态栏行数、框选聚合均基于投影后的可见行。

与 rowGrouping 的区别

树形表格快速上手

<script setup lang="ts">
import { ref } from 'vue'
import { MagicGrid } from '@taocompany/magic-grid'
import type { ColumnDef, GetDataPathFn, RowData } from '@taocompany/magic-grid/types/core'
import '@taocompany/magic-grid/tokens.css'
import '@taocompany/magic-grid/style.css'

interface OrgRow extends RowData {
  id: string
  org: string
  dept?: string
  team?: string
  name: string
  headcount: number
}

/** flat 源数据——无 children 嵌套 */
const data = ref<OrgRow[]>([
  { id: 'hq', org: 'HQ', name: '总部', headcount: 120 },
  { id: 'eng', org: 'HQ', dept: '研发', name: '研发部', headcount: 80 },
  { id: 'fe', org: 'HQ', dept: '研发', team: '前端', name: '前端组', headcount: 20 },
  { id: 'be', org: 'HQ', dept: '研发', team: '后端', name: '后端组', headcount: 25 },
  { id: 'sales', org: 'HQ', dept: '销售', name: '销售部', headcount: 30 },
])

const columns: ColumnDef[] = [
  { prop: 'name', label: '名称', width: 140, filterable: true },
  { prop: 'headcount', label: '人数', width: 88, sortable: true },
]

/** 由 org → dept → team 拼路径；也可直接读 row.pathSegments */
const getDataPath: GetDataPathFn = ({ data }) =>
  [data.org, data.dept, data.team].filter(Boolean).map(String)
</script>

<template>
  <MagicGrid
    :data="data"
    :columns="columns"
    row-key="id"
    height="480"
    tree
    :get-data-path="getDataPath"
    :group-default-expanded="-1"
    :row-selection="{ mode: 'multiple', groupSelectsChildren: true }"
    @tree-node-opened="(e) => console.log('treeNodeOpened', e)"
  />
</template>

效果：左侧自动注入 tree 系统列（缩进 + chevron + 路径末段或 name），支持折叠/展开、同级排序筛选、父子联动行选。

树形表格配置项详解

以下为树形相关 Grid 级 prop 完整说明。类型定义见 @taocompany/magic-grid/types/core 中的 TreeTableGridOptions。

回调类型签名：

type GetDataPathFn = (params: { data: RowData }) => string[]

interface TreeValueGetterParams {
  data: RowData
  dataPath: string[]
  treeLevel: number
}
type TreeValueGetterFn = (params: TreeValueGetterParams) => string

interface HasTreeChildrenParams {
  data: RowData
  dataPath: string[]
  treeLevel: number
}
type HasTreeChildrenFn = (params: HasTreeChildrenParams) => boolean

interface LoadTreeChildrenParams {
  parentRowId: BusinessRowId
  parentData: RowData
  dataPath: string[]
  treeLevel: number
  signal: AbortSignal  // 折叠 / destroy 时可 abort
}
type LoadTreeChildrenFn = (
  params: LoadTreeChildrenParams,
) => Promise<RowData[] | void> | RowData[] | void

interface SetDataPathParams {
  data: RowData
  dataPath: string[]
  treeLevel: number
  previousPath: readonly string[]
}
type SetDataPathFn = (params: SetDataPathParams) => void

setDataPath 默认行为：未传入时，若 data.pathSegments 为数组，内核会自动 data.pathSegments = [...dataPath]。业务字段（如 org / dept）需自行在 setDataPath 中同步。

数据模型与 getDataPath

推荐建模方式

方式 A — 路径存于业务字段（推荐，便于持久化）：

interface MenuRow {
  id: number
  pathSegments: string[]  // ['系统管理', '用户管理', '角色列表']
  title: string
}

const getDataPath: GetDataPathFn = ({ data }) => data.pathSegments

方式 B — 路径由字段拼接（适合固定层级列）：

const getDataPath: GetDataPathFn = ({ data }) =>
  [data.org, data.dept, data.team].filter(Boolean).map(String)

方式 C — hierarchy 拖拽后写回（需 setDataPath）：

const setDataPath: SetDataPathFn = ({ data, dataPath }) => {
  data.pathSegments = [...dataPath]
  data.org = dataPath[0]
  data.dept = dataPath[1]
  data.team = dataPath[2]
}

Transaction 与增量更新

树形模式下 applyTransaction 仍操作 flat sourceRows：

// 新增子节点（路径必须含正确父前缀）
api.applyTransaction({
  add: [{ id: 'new-fe', org: 'HQ', dept: '研发', team: '前端', name: '新小组', headcount: 5 }],
})

// 删除节点不会自动删子孙——需自行收集子树 id 后 remove
api.applyTransaction({ remove: ['fe', 'be'] })

懒加载成功时，内核 内部等价于 applyTransaction({ add: children }) 并 refresh tree 阶段。

getDataPath 与 getData() 的关系

• api.getData() 返回 flat sourceRows（与 AG Grid 一致），不是 DFS 投影顺序。
• api.getDataPath(rowId) 查询某行的当前路径。
• 展示顺序以 rowsToDisplay 为准；行索引列对 display 行 连续编号（1…N）。

树列 UI 与系统列

系统列顺序

启用 tree 后，列注入顺序为：

index（可选） → selection（可选） → expand（masterDetail 可选） → tree（__tree__） → 用户列

• tree 列默认 左固定（pinned: 'left'），默认宽 200px，最小 120px。
• 用户 columns 中 不得占用保留 colId：__tree__、__index__、__selection__、__expand__、__group__（冲突时 dev 警告并忽略）。

展示内容

自定义 tree 列

<MagicGrid
  tree
  :get-data-path="getDataPath"
  :auto-tree-column-def="{
    headerName: '组织结构',
    width: 240,
    pinned: 'left',
  }"
  :tree-value-getter="({ data, dataPath }) => `${dataPath.join(' / ')} · ${data.name}`"
/>

隐藏 tree 列（仅保留层级逻辑、自行在业务列渲染缩进）：

<MagicGrid tree :get-data-path="getDataPath" :show-tree-column="false" />

键盘与无障碍

• 焦点在 tree cell 时：Enter / Space 切换展开/折叠。
• Chevron 带 aria-expanded；lazy loading 时 aria-busy="true"。

展开与折叠

用户交互

• 点击 tree 列 chevron 切换当前节点展开/折叠。
• 点击 tree 列头 chevron（与行内同款图标）：全部展开 / 全部收起；当所有可展开节点均已展开时 chevron 旋转为展开态，再次点击则 collapseAll()。
• 折叠父节点时，子孙不出现在 rowsToDisplay（非 display: none，而是从投影中移除，不参与虚拟化行计数）。

Grid API

const api = gridRef.value?.api
api?.expandNode('eng')
api?.collapseNode('hq')
console.log(api?.isNodeExpanded('eng'))  // false
console.log(api?.getDataPath('fe'))      // ['HQ', '研发', '前端']

事件 tree-node-opened

树形懒加载

适用于 初始仅加载根节点、按需展开拉取子级的场景。仍为 CSRM（客户端行模型），不是 SSRM 服务端分页树。

启用条件

<MagicGrid
  tree
  tree-lazy-load
  :get-data-path="getDataPath"
  :has-tree-children="({ data }) => Boolean(data.hasChildren)"
  :load-tree-children="loadChildren"
  @tree-children-loading="onLoading"
  @tree-children-loaded="onLoaded"
  @tree-children-load-failed="onFailed"
/>

首次展开时序

用户点击 chevron / expandNode API
  → 若 loadedParentIds 已有 → 直接 map 展开
  → 若 inflight 已有 → 复用同一 Promise
  → emit treeChildrenLoading
  → await loadTreeChildren({ parentRowId, parentData, dataPath, treeLevel, signal })
  → 成功：校验路径 / rowKey 唯一 → applyTransaction({ add }) → refresh tree 阶段
  → emit treeChildrenLoaded → 子孙可见
  → 失败：emit treeChildrenLoadFailed · source 不变 · 保持折叠
  → Abort（折叠/destroy）：丢弃 late resolve · 不污染 source

loadTreeChildren 实现要点

async function loadChildren({
  parentRowId,
  parentData,
  dataPath,
  signal,
}: LoadTreeChildrenParams): Promise<RowData[]> {
  const res = await fetch(`/api/org/${parentRowId}/children`, { signal })
  if (!res.ok) throw new Error('load failed')
  const rows = await res.json()
  // 每行必须能被 getDataPath 解析，且路径前缀包含 parent 的 dataPath
  return rows
}

懒加载事件

排序、筛选与汇总

行选择与 groupSelectsChildren

树形模式下行选择配置与 flat 相同，通过 row-selection prop：

<MagicGrid
  :row-selection="{ mode: 'multiple', groupSelectsChildren: true }"
/>

注意：

• 折叠的子孙不参与级联（未投影到 display 的行不在选区内）。
• lazy 加载完成前，父选中 不会 预选尚未加载的子孙。
• 所有 data 行（含非叶节点）均可被选中、编辑。

行拖拽与层级变更

树形行拖拽需开启 indexColumn.showRowDragHandle: true（或列级 drag handle）。与 rowDragManaged 配合使用；配置 asyncRowMutation.move 时拖拽自动 await 持久化。

treeDragScope: 'siblings'（默认）

• drop 仅限同一 parentRowId 下兄弟 间换序。
• 跨父 drag → 禁止光标 · 不 emit rowMoved。
• 不改变 dataPath；仅调整 source 平铺顺序中的兄弟区间。

treeDragScope: 'hierarchy'

允许 跨层级改挂（改父节点），必须提供 setDataPath 写回路径：

层级快捷菜单语义：

菜单项 按节点动态过滤——不可用时隐藏；至少一项可用时才显示 settings 按钮。

asyncRowMutation.move 与 hierarchyChanges

配置了 asyncRowMutation.move 时，拖拽 mouseup 后先 await move（source: 'uiRowDrag'），成功才写 source。

树形改挂、快捷菜单等操作常使 moves 为空 而 hierarchyChanges 非空：

import { getRowDragCommitHierarchy } from '@taocompany/magic-grid'

async function persistMove(params: AsyncRowMutationMoveParams): Promise<void> {
  // 推荐：过滤掉仅 treeLevel 变化的项，持久化 parentId + order
  const changes = getRowDragCommitHierarchy(params, 'noLevel')
  await api.saveHierarchy({ changes })
}

RowHierarchyChange 含 rowId、parentRowId、siblingIndex、treeLevel 等字段，由 asyncRowMutation.move 在 source: 'uiRowDrag' 时传入。

树形与其它能力叠加

常见错误与排查

相关 API 索引：Props · 树形表格 · Events · 树形表格 · GridApi · expandNode。

默认配置

以下为 <MagicGrid> 未显式传入 prop 时的生效值。部分 prop 在组件层与内核层默认不同（标注 MG = MagicGrid 组件层覆盖），使用时以组件行为为准。

尺寸 preset（size）

rowHeight / headerHeight / statusBarHeight（statusBarHeight: 'auto' 时）未显式传入时，由 size 推导：

基础与外观

对齐

虚拟化与导航

索引列

行选择

rowSelection 对象形式时，groupSelectsChildren 默认 true（tree 模式父节点级联子孙）。

表尾汇总

排序 / 筛选 / 列操作

编辑

行拖拽与行高

合并 / 展开 / 分组 / 树

批注

框选与剪贴板

Tooltip

空态 Overlay

状态栏

ColumnDef 列级默认

Props

各 prop 的默认值汇总见上一节 默认配置。下列按功能分组逐项说明类型、默认值与行为。

MagicGrid Props

基础

外观

对齐（全局默认）

虚拟化与导航

索引列

IndexColumnOptions 字段：

行选择

RowSelectionConfig：

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

SelectionColumnOptions 字段：

表尾汇总

排序

列操作

筛选

编辑

行拖拽与行高

合并单元格

主从展开行

行分组

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

树形表格

完整消费端指南见 树形表格 专章（概念、懒加载、拖拽、排查）。下表为 Props 速查。

单元格批注

框选与剪贴板

CellSelectionOptions 字段（cellSelection 为对象时）：

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

空态 Overlay

状态栏

Grid 级默认与列级覆盖

以下 Grid Prop 可一次性为所有用户列设定默认行为；列级字段显式配置时以列为准（对齐 AG Grid defaultColDef 语义）：

系统列（索引 / 行选择 / 展开 / 分组等）不受 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。

标识与展示

列有效性与显隐

通过 available 与 hidden 控制列是否参与表格。二者均可在 columns prop 中动态修改；Grid 会重解析列模型并刷新布局。

语义对照：

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 重解析。available 集合变化时列顺序按 ColumnDef 声明序重置；同集合热更新（如仅改 width/label）仍保留 runtime 顺序（含用户拖拽）。hidden 在 columnDefs 未改 hidden 声明时，会保留运行时 API/菜单设置的值（与 Phase 22 列显隐语义一致）。

尺寸

行为

行分组（需 rowGrouping: true）

合并单元格（需 enableCellSpan: true）

数据转换与渲染

校验

剪贴板

汇总

对齐

禁用与样式

Tooltip

Options 类型参考

下列类型均可从 @taocompany/magic-grid 导入，供 Props、GridApi 与事件 payload 使用。

IndexColumnOptions

索引列配置，通过 indexColumn prop 传入（showIndexColumn=true 时生效）。

配置了 asyncRowMutation.update / remove / move 时，await 期间受影响行会在索引列显示 loading spinner（.mg-cell--index-loading）。

SetIndexFocusOptions

setIndexFocus 的可选第二参数：

api.setIndexFocus(2)                                              // 默认模式
api.setIndexFocus(2, { mode: 'default' })                       // 同上
api.setIndexFocus(2, { mode: 'manual', syncToSelectionColumn: false })  // 仅定位，不选中
api.setIndexFocus(2, { mode: 'manual', syncToSelectionColumn: true })   // 强制同步选中
api.setIndexFocus([])                                             // 清除定位

ClearRowSelectionOptions

clearRowSelection 的可选参数：

api.clearRowSelection()                        // 清空全部
api.clearRowSelection({ scope: 'all' })        // 同上
api.clearRowSelection({ scope: 'current' })    // 仅清当前可见 display 中的选中

SelectionColumnOptions

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

RowSelectionConfig

rowSelection 的对象形式：

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

CellSelectionOptions

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

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?)）：