@taocompany/magic-grid 0.6.6 → 0.7.1

package/README.md

@@ -9,6 +9,20 @@
 - [快速开始](#快速开始)
 - [数据与性能最佳实践](#数据与性能最佳实践)
   - [Cell Renderer 滚动渲染](#cell-renderer-滚动渲染)
+- [树形表格](#树形表格)
+  - [概述与核心概念](#概述与核心概念)
+  - [快速上手](#树形表格快速上手)
+  - [配置项详解](#树形表格配置项详解)
+  - [数据模型与 getDataPath](#数据模型与-getdatapath)
+  - [树列 UI 与系统列](#树列-ui-与系统列)
+  - [展开与折叠](#展开与折叠)
+  - [树形懒加载](#树形懒加载)
+  - [排序、筛选与汇总](#排序筛选与汇总)
+  - [行选择与 groupSelectsChildren](#行选择与-groupselectschildren)
+  - [行拖拽与层级变更](#行拖拽与层级变更)
+  - [与其它能力叠加](#树形与其它能力叠加)
+  - [常见错误与排查](#常见错误与排查)
+  - [Playground 与延伸阅读](#playground-与延伸阅读)
 - [默认配置](#默认配置)
 - [Props](#props)
   - [MagicGrid Props](#magicgrid-props)
@@ -107,6 +121,8 @@ Magic Grid 采用 **命令式渲染内核 + Vue 薄封装** 的分层架构，
 | 行分组 | `group` → `filter` → `sort` → `aggregate` → `map` |
 | 树形表格 | `tree` → `filter` → `sort` → `map` |
 
+详见 **[树形表格](#树形表格)** 专章。
+
 `summaryScope: 'displayed'`、状态栏行数、框选聚合均基于 `rowsToDisplay`；`summaryScope: 'all'` 对 `sourceRows` 全量汇总（忽略 filter）。
 
 ---
@@ -231,6 +247,514 @@ const columns: ColumnDef[] = [
 
 ---
 
+## 树形表格
+
+树形表格（Tree Table）在 **扁平 `data` 数组** 上，通过 **`getDataPath`** 为每行提供 **从根到当前节点的路径**（`string[]`），内核据此构建层级并 **DFS 投影** 为可见的 `rowsToDisplay`。对标 [AG Grid Tree Data](https://www.ag-grid.com/javascript-data-grid/tree-data/) 社区版语义；设计细节见 [`docs/30-phase19-tree-table.md`](docs/30-phase19-tree-table.md)。
+
+> **与行分组互斥**：`tree: true` 与 `rowGrouping: true` **不得同时生效**。双开时控制台 dev 警告，**`tree` 优先**，`rowGrouping` 及 `ColumnDef.rowGroup` 被忽略。flat / group / tree 三选一，见 [概述与核心概念](#概述与核心概念)。
+
+### 概述与核心概念
+
+#### 为什么用扁平数组 + getDataPath？
+
+Magic Grid **不支持**嵌套 `children` 字段作为树数据源（与 AG Grid CSRM 一致）。所有行仍存放在 **同一个 `data` 数组** 中；层级关系完全由 **`getDataPath({ data }) => string[]`** 表达：
+
+| 概念 | 说明 |
+|------|------|
+| **`dataPath`** | 从根到当前节点的路径段，如 `['总部', '研发部', '前端组']` |
+| **`treeLevel`** | 深度，根节点 = `0`，等于 `dataPath.length - 1` |
+| **`parentRowId`** | 父节点 `rowKey`；根节点为 `undefined` |
+| **`rowsToDisplay`** | 折叠感知的 DFS 扁平投影；渲染层 **只消费此数组** |
+| **`sourceRows`** | 业务 flat 数组；`getData()` / `applyTransaction` 仍操作此层 |
+
+**示例路径**（组织树）：
+
+| 行 id | dataPath | treeLevel | 含义 |
+|-------|----------|-----------|------|
+| `hq` | `['HQ']` | 0 | 根 |
+| `eng` | `['HQ', '研发']` | 1 | HQ 下研发部 |
+| `fe` | `['HQ', '研发', '前端']` | 2 | 研发部下前端组 |
+
+#### 路径规则（必须遵守）
+
+1. **前缀唯一确定父子**：`['A','B']` 的父路径必须是 `['A']`；缺父路径 → 建树 **throw**。
+2. **同一路径不得对应多行**：重复路径 → 建树 **throw**。
+3. **路径段为任意字符串**：可含中文、空格、特殊字符；内核用 `\0` 拼接做内部 key。
+4. **`rowKey` 必须稳定唯一**：与 flat 表格相同；临时行可用 `__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 的区别
+
+| 维度 | 行分组 (`rowGrouping`) | 树形表格 (`tree`) |
+|------|------------------------|-------------------|
+| 层级来源 | 列值 `rowGroup` 聚合 | `getDataPath` 路径 |
+| 数据行 | leaf + synthetic group 行 | **全部为 user data 行** |
+| 系统列 | auto group 列（`__group__`） | tree 列（`__tree__`） |
+| 管线 | `group → filter → sort → aggregate → map` | `tree → filter → sort → map` |
+| 互斥 | 与 `tree` 不得双开 | 与 `rowGrouping` 不得双开 |
+
+### 树形表格快速上手
+
+```vue
+<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/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`），支持折叠/展开、同级排序筛选、父子联动行选。完整交互验收见 Playground **`/phase19`**。
+
+### 树形表格配置项详解
+
+以下为树形相关 **Grid 级 prop** 完整说明。类型定义见 `@taocompany/magic-grid/types/core` 中的 `TreeTableGridOptions`。
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `tree` | `boolean` | `false` | **总闸**。`true` 时启用树形模式；**必填** `getDataPath` |
+| `getDataPath` | `GetDataPathFn` | — | `( { data } ) => string[]`，每行返回路径。**`tree: true` 时必填**，缺失则 throw |
+| `groupDefaultExpanded` | `number` | `-1` | 默认展开层级（tree / group **共用**此 prop）。`0` = 全折叠；`1` = 仅展开第一层；`-1` = 全部展开 |
+| `showTreeColumn` | `boolean` | `true` | 是否注入 tree 系统列（colId `__tree__`） |
+| `autoTreeColumnDef` | `Partial<ColumnDef>` | — | 覆盖 tree 列宽、pinned、headerName 等；对标 AG Grid `autoGroupColumnDef` |
+| `treeValueGetter` | `TreeValueGetterFn` | — | 自定义 tree 列展示文案；缺省为 **`dataPath` 末段** |
+| `treeDisplayType` | `'singleColumn'` | `'singleColumn'` | v1 仅单列树展示 |
+| `treeLazyLoad` | `boolean` | `false` | 启用 CSRM 懒加载；`true` 时需 `loadTreeChildren` |
+| `hasTreeChildren` | `HasTreeChildrenFn` | — | lazy：`true` 时即使 source 尚无子孙也展示 expand chevron |
+| `loadTreeChildren` | `LoadTreeChildrenFn` | — | lazy：首次展开且无已加载子行时异步拉取子数据 |
+| `treeDragScope` | `'siblings' \| 'hierarchy'` | `'siblings'` | 行拖拽范围，见 [行拖拽与层级变更](#行拖拽与层级变更) |
+| `setDataPath` | `SetDataPathFn` | — | `hierarchy` 模式下 drag/shortcut 写回路径到 `row.data` |
+| `treeHierarchyActions` | `boolean` | `true` | `hierarchy` + `setDataPath` 时，tree 列 hover 展示 **上移一级 / 下移一级** 菜单 |
+
+**回调类型签名**：
+
+```ts
+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 — 路径存于业务字段**（推荐，便于持久化）：
+
+```ts
+interface MenuRow {
+  id: number
+  pathSegments: string[]  // ['系统管理', '用户管理', '角色列表']
+  title: string
+}
+
+const getDataPath: GetDataPathFn = ({ data }) => data.pathSegments
+```
+
+**方式 B — 路径由字段拼接**（适合固定层级列）：
+
+```ts
+const getDataPath: GetDataPathFn = ({ data }) =>
+  [data.org, data.dept, data.team].filter(Boolean).map(String)
+```
+
+**方式 C — hierarchy 拖拽后写回**（需 `setDataPath`）：
+
+```ts
+const setDataPath: SetDataPathFn = ({ data, dataPath }) => {
+  data.pathSegments = [...dataPath]
+  data.org = dataPath[0]
+  data.dept = dataPath[1]
+  data.team = dataPath[2]
+}
+```
+
+#### Transaction 与增量更新
+
+树形模式下 **`applyTransaction` 仍操作 flat `sourceRows`**：
+
+```ts
+// 新增子节点（路径必须含正确父前缀）
+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 警告并忽略）。
+
+#### 展示内容
+
+| 元素 | 说明 |
+|------|------|
+| **缩进** | 每级 `16px`（`padding-left = treeLevel × 16`） |
+| **Chevron** | 可展开节点显示；叶节点隐藏或占位对齐 |
+| **文案** | 默认 `dataPath` **末段**；可用 `treeValueGetter` 覆盖 |
+| **Loading** | lazy 加载中 chevron 区 spinner + `aria-busy` |
+| **Settings 菜单** | `treeDragScope: 'hierarchy'` 且 `setDataPath` 可用时，hover 显示 settings 按钮 |
+
+#### 自定义 tree 列
+
+```vue
+<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 列（仅保留层级逻辑、自行在业务列渲染缩进）：
+
+```vue
+<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
+
+| 方法 | 说明 |
+|------|------|
+| `expandNode(rowId)` | 展开节点；lazy 模式下若子行未加载会先 await `loadTreeChildren` |
+| `collapseNode(rowId)` | 折叠节点；会 abort 该节点在途 lazy 请求 |
+| `isNodeExpanded(rowId)` | 查询展开态 |
+| `expandAll()` | 展开 **已加载** 子树；**不会**递归触发 lazy load（避免请求风暴） |
+| `collapseAll()` | 折叠全部 |
+| `getDataPath(rowId)` | 返回 `string[]` 或 `undefined` |
+
+```ts
+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`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rowId` | `BusinessRowId` | 节点 id |
+| `expanded` | `boolean` | `true` 展开 / `false` 折叠 |
+| `level` | `number` | `treeLevel` |
+| `dataPath` | `string[]` | 节点路径 |
+| `source` | `'api' \| 'ui'` | API 调用或用户点击 chevron |
+
+### 树形懒加载
+
+适用于 **初始仅加载根节点**、按需展开拉取子级的场景。仍为 **CSRM**（客户端行模型），**不是** SSRM 服务端分页树。
+
+#### 启用条件
+
+```vue
+<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"
+/>
+```
+
+| 配置 | 必填 | 说明 |
+|------|------|------|
+| `treeLazyLoad: true` | 是 | 总闸 |
+| `loadTreeChildren` | **是** | 未提供时 dev 警告，行为退化为 M24 全量 tree |
+| `hasTreeChildren` | 强烈建议 | 控制 **尚未加载** 时是否显示 chevron |
+| `getDataPath` | 是 | 与全量 tree 相同 |
+
+#### 首次展开时序
+
+```
+用户点击 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 实现要点
+
+```ts
+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
+}
+```
+
+| 规则 | 说明 |
+|------|------|
+| **幂等** | 同一 `parentRowId` 成功加载后 **不重复请求** |
+| **空子树** | 返回 `[]` → 标记为已加载叶节点 · chevron 消失 |
+| **路径校验** | 子行 `getDataPath` 必须以父路径为前缀；否则 loadFailed |
+| **AbortSignal** | 须在 `signal.aborted` 时停止；折叠父节点会 abort |
+| **expandAll** | **不**批量触发 lazy load |
+
+#### 懒加载事件
+
+| 事件 | 关键字段 |
+|------|----------|
+| `tree-children-loading` | `parentRowId`, `dataPath`, `treeLevel`, `source` |
+| `tree-children-loaded` | `parentRowId`, `children`, `childCount`, `source` |
+| `tree-children-load-failed` | `parentRowId`, `reason?`, `aborted?` |
+
+### 排序、筛选与汇总
+
+| 操作 | 树形语义 |
+|------|----------|
+| **列排序** | 仅在 **同一 `parentRowId` 下兄弟** 间重排；**不改变** `dataPath` |
+| **列筛选 / Quick Filter** | 递归匹配 data 行；某父下子孙全被滤掉 → **父节点隐藏**（空枝剪枝） |
+| **表尾汇总** | `summaryScope: 'displayed'` 时仅聚合 **可见** data 行（含各层父节点） |
+| **lazy 未加载分支** | 不参与 filter/sort/drag（RowNode 尚不存在） |
+
+### 行选择与 groupSelectsChildren
+
+树形模式下行选择配置与 flat 相同，通过 `row-selection` prop：
+
+```vue
+<MagicGrid
+  :row-selection="{ mode: 'multiple', groupSelectsChildren: true }"
+/>
+```
+
+| `groupSelectsChildren` | 行为 |
+|------------------------|------|
+| **`true`（默认）** | 选中父 → 递归选中 **display 中可见** 子孙；取消父 → 递归取消 |
+| **`false`** | 父子 checkbox **独立**；子全选时父 **indeterminate**；父选中 **不**自动选子 |
+
+注意：
+
+- **折叠的子孙不参与级联**（未投影到 display 的行不在选区内）。
+- lazy 加载完成前，父选中 **不会** 预选尚未加载的子孙。
+- 所有 **data 行**（含非叶节点）均可被选中、编辑。
+
+### 行拖拽与层级变更
+
+树形行拖拽需开启 **`indexColumn.showRowDragHandle: true`**（或列级 drag handle）。与 `rowDragManaged` / `rowDragCommitMode` 配合使用。
+
+#### treeDragScope: `'siblings'`（默认）
+
+- drop **仅限同一 `parentRowId` 下兄弟** 间换序。
+- 跨父 drag → 禁止光标 · **不 emit** `rowMoved`。
+- **不改变** `dataPath`；仅调整 source 平铺顺序中的兄弟区间。
+
+#### treeDragScope: `'hierarchy'`
+
+允许 **跨层级改挂**（改父节点），**必须**提供 `setDataPath` 写回路径：
+
+| 操作 | 如何触发 |
+|------|----------|
+| **挂到目标行下（nest）** | 拖到 tree 列 **子级缩进热区**（目标行右侧），或 **按住 Alt** 再 drop |
+| **同级换序 / 改父到根或旁支** | 拖到目标行 **同级区域**（默认 drop 区） |
+| **上移一级 / 下移一级** | tree 列 hover **settings-2** 菜单（需 `treeHierarchyActions !== false`） |
+
+**层级快捷菜单语义**：
+
+| 菜单项 | 行为 |
+|--------|------|
+| **上移一级** | 有父节点 → outdent 到父的同级；已是根 → 将 **上一个同级节点及其子树** 挂到当前节点下 |
+| **下移一级** | 挂到 display 中 **上一个同级节点** 的子树末尾 |
+
+菜单项 **按节点动态过滤**——不可用时隐藏；至少一项可用时才显示 settings 按钮。
+
+#### deferred commit 与 hierarchyChanges
+
+`rowDragCommitMode: 'deferred'` 时，mouseup 后先 `await onRowDragCommit`，成功才写 source。
+
+树形改挂、快捷菜单等操作常使 **`moves` 为空** 而 **`hierarchyChanges` 非空**：
+
+```ts
+import { getRowDragCommitHierarchy } from '@taocompany/magic-grid'
+
+async function onRowDragCommit(context: RowDragCommitContext): Promise<boolean> {
+  // 推荐：过滤掉仅 treeLevel 变化的项，持久化 parentId + order
+  const changes = getRowDragCommitHierarchy(context, 'noLevel')
+  await api.saveHierarchy({ changes })
+  return true  // false 则回滚，source 不变
+}
+```
+
+`RowHierarchyChange` 含 `rowId`、`parentRowId`、`siblingIndex`、`treeLevel`、`dataPath` 等；详见 [`src/core/types/rowDrag.ts`](src/core/types/rowDrag.ts) 与 Playground T11/T12。
+
+### 树形与其它能力叠加
+
+| 场景 | 预期行为 |
+|------|----------|
+| **固定列 / 列虚拟化** | tree 列默认左固定；tree cell 仍受列窗口约束 |
+| **行虚拟化** | 全部 display 行参与 `rowTop` 累计；百万行靠虚拟化 |
+| **Master Detail** | detail 行紧跟 master leaf；**不参与** tree 路径与子树计数 |
+| **合并单元格** | tree 行 **不参与** colSpan/rowSpan |
+| **单元格编辑** | 所有 data 行可编辑（含父节点）；group 模式下的 leaf 限制 **不适用** |
+| **索引列** | 对 **全部 display 行**连续编号 |
+| **cellComments / 框选 / 剪贴板** | 与 flat 相同，基于 display 索引 |
+| **rowGrouping** | **互斥** · 勿双开 |
+
+### 常见错误与排查
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| 初始化 throw `tree: true requires getDataPath` | 未传 `getDataPath` | 添加回调 |
+| refresh throw `missing parent path` | 子行路径缺父节点行 | 补全中间层或修正 path |
+| refresh throw 重复路径 | 两行 `getDataPath` 相同 | 保证路径唯一 |
+| 双开 tree + rowGrouping 但无分组 | 设计如此，tree 优先 | 二选一 |
+| lazy 展开无 chevron | 未传 `hasTreeChildren` 且 source 无子行 | 提供 `hasTreeChildren` |
+| lazy 展开无反应 | 未传 `loadTreeChildren` | 检查 dev 警告 |
+| hierarchy drag 无效 | 未传 `setDataPath` | 实现写回或使用默认 `pathSegments` |
+| 跨父 drag 被拒绝 | `treeDragScope: 'siblings'` | 改为 `hierarchy` |
+| 选中父但子孙未选中 | 子孙折叠不可见，或 `groupSelectsChildren: false` | 展开 / 检查配置 |
+| `expandAll` 未加载 lazy 子级 | 设计限制 | 逐节点 expand 或预加载 |
+
+### Playground 与延伸阅读
+
+- **交互验收**：本地运行 Playground，访问 **`/phase19`**（`Phase19Demo.vue`）。
+- **数据集**：组织树全量 · 组织树 lazy · 菜单 mock（多根、深层路径）。
+- **验收步骤 T1–T15**：见 [`playground/shared/phase19-grid.ts`](playground/shared/phase19-grid.ts) 中 `PHASE19_ACCEPTANCE_STEPS`。
+- **设计文档**：[`docs/30-phase19-tree-table.md`](docs/30-phase19-tree-table.md)（架构、拍板记录、测试矩阵）。
+- **Props / Events / GridApi 索引**：[Props · 树形表格](#树形表格-1) · [Events · 树形表格](#树形表格-2) · [Expose · expandNode](#展开--分组--树)。
+
+---
+
 ## 默认配置
 
 以下为 `<MagicGrid>` **未显式传入 prop** 时的生效值。部分 prop 在组件层与内核层默认不同（标注 **MG** = MagicGrid 组件层覆盖），使用时以组件行为为准。
@@ -372,6 +896,7 @@ const columns: ColumnDef[] = [
 | `tree` | `false` | 不启用树形表格 |
 | `showTreeColumn` | `true` | 展示 tree 系统列（启用 tree 后） |
 | `treeDragScope` | `'siblings'` | 树拖拽仅同层兄弟 |
+| `treeHierarchyActions` | `true` | hierarchy 模式下展示层级快捷菜单 |
 | `treeDisplayType` | `'singleColumn'` | 单列树展示 |
 | `treeLazyLoad` | `false` | 不启用懒加载 |
 
@@ -610,7 +1135,7 @@ interface RowSelectionConfig {
 |------|------|--------|------|
 | `rowDragManaged` | `boolean` | `true` | managed 行拖拽：拖拽过程中实时改 source 顺序 |
 | `rowDragCommitMode` | `'sync' \| 'deferred'` | `'sync'` | commit 策略：`sync` live move；`deferred` mouseup 后 await `onRowDragCommit` |
-| `onRowDragCommit` | `RowDragCommitHandler` | — | deferred 模式：mouseup 后、apply 前调用；返回 `false` 则不写 source |
+| `onRowDragCommit` | `RowDragCommitHandler` | — | deferred 模式：mouseup 后、apply 前调用；返回 `false` 则不写 source。树形持久化见 context.`hierarchyChanges`（parentId + order 语义）；`moves` 仅为 source 平铺下标位移 |
 | `getRowHeight` | `GetRowHeightFn` | — | 行级动态高度（无 DOM） |
 | `rowHeightMin` | `number` | — | 行高下限 px |
 | `rowHeightMax` | `number` | — | 行高上限 px |
@@ -655,19 +1180,23 @@ interface RowSelectionConfig {
 
 #### 树形表格
 
+> 完整消费端指南见 **[树形表格](#树形表格)** 专章（概念、懒加载、拖拽、排查）。下表为 Props 速查。
+
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `tree` | `boolean` | `false` | 启用树形表格（与 `rowGrouping` 互斥） |
-| `getDataPath` | `GetDataPathFn` | — | 树形路径回调（`tree: true` 时必填） |
-| `treeDragScope` | `'siblings' \| 'hierarchy'` | `'siblings'` | 树形拖拽范围 |
-| `setDataPath` | `SetDataPathFn` | — | hierarchy 模式下写回 dataPath |
-| `showTreeColumn` | `boolean` | `true` | 展示 tree 系统列 |
+| `getDataPath` | `GetDataPathFn` | — | 树形路径回调（`tree: true` 时 **必填**） |
+| `groupDefaultExpanded` | `number` | `-1` | 默认展开层级：`0` 全折叠 · `1` 第一层 · `-1` 全部（tree / group 共用） |
+| `treeDragScope` | `'siblings' \| 'hierarchy'` | `'siblings'` | 树形拖拽范围；`hierarchy` 允许跨父改挂（需 `setDataPath`） |
+| `setDataPath` | `SetDataPathFn` | — | `hierarchy` 模式下写回 `dataPath` 到行数据 |
+| `treeHierarchyActions` | `boolean` | `true` | `hierarchy` 时在 tree 列展示 **上移一级 / 下移一级** 菜单 |
+| `showTreeColumn` | `boolean` | `true` | 展示 tree 系统列（colId `__tree__`） |
 | `autoTreeColumnDef` | `Partial<ColumnDef>` | — | 覆盖 tree 系统列 colDef |
-| `treeValueGetter` | `TreeValueGetterFn` | — | 自定义 tree 列展示值 |
-| `treeDisplayType` | `'singleColumn'` | — | 树节点展示列模式 |
-| `treeLazyLoad` | `boolean` | `false` | 启用树形懒加载 |
-| `hasTreeChildren` | `HasTreeChildrenFn` | — | lazy 模式：节点是否可能有未加载子行 |
-| `loadTreeChildren` | `LoadTreeChildrenFn` | — | lazy 模式：首次展开时拉取子数据 |
+| `treeValueGetter` | `TreeValueGetterFn` | — | 自定义 tree 列展示值（缺省为 dataPath 末段） |
+| `treeDisplayType` | `'singleColumn'` | `'singleColumn'` | 树节点展示列模式 |
+| `treeLazyLoad` | `boolean` | `false` | 启用树形懒加载（CSRM · 需 `loadTreeChildren`） |
+| `hasTreeChildren` | `HasTreeChildrenFn` | — | lazy：节点是否可能有未加载子行（控制 chevron） |
+| `loadTreeChildren` | `LoadTreeChildrenFn` | — | lazy：首次展开时拉取子数据 |
 
 #### 单元格批注
 
@@ -1837,6 +2366,8 @@ payload 为 `RowExpansionChangedEvent`：
 
 ### 树形表格
 
+> 事件语义、懒加载时序与排查见 **[树形表格 · 展开与折叠](#展开与折叠)**、**[树形懒加载](#树形懒加载)** 专章。
+
 #### `tree-node-opened`
 
 | 字段 | 类型 | 说明 |
@@ -2163,17 +2694,19 @@ api.setIndexFocus(2, { mode: 'manual', syncToSelectionColumn: false })  // 仅
 
 #### 展开 / 分组 / 树
 
+> tree API 详解见 **[树形表格 · 展开与折叠](#展开与折叠)**。
+
 | 方法 | 说明 |
 |------|------|
-| `expandRow(rowId)` / `collapseRow(rowId)` | 展开/折叠主行 |
+| `expandRow(rowId)` / `collapseRow(rowId)` | 展开/折叠主行（masterDetail） |
 | `isRowExpanded(rowId)` | 主行是否已展开 |
-| `expandAll()` / `collapseAll()` | 全部展开/折叠 |
+| `expandAll()` / `collapseAll()` | 全部展开/折叠（tree：expandAll 不触发 lazy load） |
 | `setRowGroupColumns(colIds)` / `getRowGroupColumns()` | 分组列读写 |
 | `expandGroup(groupId)` / `collapseGroup(groupId)` | 展开/折叠分组节点 |
 | `isGroupExpanded(groupId)` | 分组是否已展开 |
 | `expandNode(rowId)` / `collapseNode(rowId)` | 展开/折叠 tree 节点 |
 | `isNodeExpanded(rowId)` | tree 节点是否已展开 |
-| `getDataPath(rowId)` | 查询行的 dataPath |
+| `getDataPath(rowId)` | 查询行的 dataPath（`string[]`） |
 
 #### 批注 / 框选 / 空态
 
@@ -3373,7 +3906,7 @@ const onRowChanged = (e: RowValueChangedEvent<OrderRow, number>) => {
 const cells: EditingCellPosition<OrderRow, unknown>[] = api.getEditingCells()
 ```
 
-常用导出：`GridReadyEvent`、`CellValueChangedEvent`、`RowClickedEvent`、`FilterModel`、`GridEventMap`、`GridEventHandler`、`SetIndexFocusOptions`、`ClearRowSelectionOptions`、`BusinessRowId`。
+常用导出：`GridReadyEvent`、`CellValueChangedEvent`、`RowClickedEvent`、`FilterModel`、`GridEventMap`、`GridEventHandler`、`SetIndexFocusOptions`、`ClearRowSelectionOptions`、`BusinessRowId`、树形相关 `GetDataPathFn` / `TreeNodeOpenedEvent` 等（见 [类型与校验子路径](#taocompanymagic-gridtypescore)）。
 
 ### 严格模式建议
 
@@ -3444,6 +3977,20 @@ import type {
   // 列设置
   ColumnSettingsResetScope,
   ColumnSettingsMenuIconName,
+  // 树形表格
+  GetDataPathFn,
+  SetDataPathFn,
+  TreeValueGetterFn,
+  HasTreeChildrenFn,
+  LoadTreeChildrenFn,
+  TreeDragScope,
+  TreeTableGridOptions,
+  TreeNodeOpenedEvent,
+  TreeChildrenLoadingEvent,
+  TreeChildrenLoadedEvent,
+  TreeChildrenLoadFailedEvent,
+  TreeTableSource,
+  TREE_COLUMN_ID,
   // 插槽
   StatusBarContext,
   DetailRowSlotParams,

package/dist/components/ColumnSettings/ColumnSettingsMenu.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ColumnSettingsMenu.vue.d.ts","sourceRoot":"","sources":["../../../src/components/ColumnSettings/ColumnSettingsMenu.vue"],"names":[],"mappings":";AA4LA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAA;AAUhF,KAAK,WAAW,GAAG;IACjB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAC;AAsRF,QAAA,IAAI,QAAQ,IAAY,CAAE;AAC1B,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAQhD,QAAA,MAAM,UAAU;;;;;;;;kFAGd,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AACzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}
+{"version":3,"file":"ColumnSettingsMenu.vue.d.ts","sourceRoot":"","sources":["../../../src/components/ColumnSettings/ColumnSettingsMenu.vue"],"names":[],"mappings":";AA0LA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAA;AAUhF,KAAK,WAAW,GAAG;IACjB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAC;AAoRF,QAAA,IAAI,QAAQ,IAAY,CAAE;AAC1B,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,QAAQ,KAAK,GAAG,CAAA;CAAE,CAAC;AAQhD,QAAA,MAAM,UAAU;;;;;;;;kFAGd,CAAC;AACH,QAAA,MAAM,YAAY,EAAS,eAAe,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC,CAAC;wBACtD,OAAO,YAAY;AAAxC,wBAAyC;AACzC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KACV,CAAA;CACD,CAAC"}

package/dist/components/ColumnSettings/ColumnSettingsMenuIcon.vue.d.ts

@@ -2,11 +2,8 @@ import { ColumnSettingsMenuIconName } from './columnSettingsMenuIcons';
 import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
 type __VLS_Props = {
     name: ColumnSettingsMenuIconName;
-    size?: number;
 };
-declare const __VLS_export: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    size: number;
-}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;
 //# sourceMappingURL=ColumnSettingsMenuIcon.vue.d.ts.map

package/dist/components/ColumnSettings/ColumnSettingsMenuIcon.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ColumnSettingsMenuIcon.vue.d.ts","sourceRoot":"","sources":["../../../src/components/ColumnSettings/ColumnSettingsMenuIcon.vue"],"names":[],"mappings":";AAgDA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,2BAA2B,CAAA;AAElC,KAAK,WAAW,GAAG;IACf,IAAI,EAAE,0BAA0B,CAAA;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAC;AA8DJ,QAAA,MAAM,YAAY;UA/DP,MAAM;6EAkEf,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}
+{"version":3,"file":"ColumnSettingsMenuIcon.vue.d.ts","sourceRoot":"","sources":["../../../src/components/ColumnSettings/ColumnSettingsMenuIcon.vue"],"names":[],"mappings":";AAwCA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,2BAA2B,CAAA;AAElC,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,0BAA0B,CAAA;CACjC,CAAC;AAoDF,QAAA,MAAM,YAAY,kSAEhB,CAAC;wBACkB,OAAO,YAAY;AAAxC,wBAAyC"}