AG Grid

AG Grid 数据网格资源与 Vue 集成示例，说明行合并、模块、主题和数据加载模型的边界。

#frontend #resource #growing #tool

AG Grid 使用手册

本页介绍 AG Grid 并保留 Vue 3 集成与旧项目经验。它不表示当前 Thought Forest 使用该组件；示例以支持 enableCellSpan 的版本为前提，实际项目应统一各 AG Grid 包版本。

一、基础概念

AG Grid：一个企业级的网格（data grid）组件，支持 Vue / React / Angular / Plain JS。功能包括虚拟渲染（高性能）、列/行分组、行/列合并（row spanning / cell spanning）、服务器端模型、排序、筛选、聚合、可编辑单元格等。
虚拟渲染（Virtualization）：只渲染视口内可见的 DOM 节点，滚动时增量渲染/重用节点，减少 DOM 数量；性能仍受列数、渲染器、数据操作和设备影响，不能保证任意十万行场景都流畅。
Row Spanning（行合并）：AG Grid 将单元格抽象为可以跨多个可见行的单元格（通过 enableCellSpan + colDef.spanRows 或 spanRows: true 实现）。与传统 <table> 的 rowspan 不同，AG Grid 在它的渲染层面通过 CSS/DOM 控制合并行为（更灵活，能和虚拟渲染配合）。
模块化：当前模块化集成需区分 community / enterprise 功能。使用前 ModuleRegistry.registerModules(...) 注册所需模块，或者注册 AllCommunityModule 以快速启用社区版全部功能。

二、使用指南（Vue 3 + ag-grid-vue3）

1) 安装

使用 pnpm/npm/yarn 安装：

pnpm add ag-grid-vue3 ag-grid-community
# 或者： npm i ag-grid-vue3 ag-grid-community

2) 注册模块（必须）

在使用组件之前注册模块（推荐全部社区模块）：

// 在组件文件或全局入口中注册一次
import { ModuleRegistry, AllCommunityModule } from 'ag-grid-community'
ModuleRegistry.registerModules([AllCommunityModule])

3) 最小示例（组件内）

<template>
  <div style="height:520px; width:100%">
    <AgGridVue
      style="height:100%; width:100%"
      :columnDefs="columnDefs"
      :rowData="rowData"
      :defaultColDef="defaultColDef"
      :enableCellSpan="true"
      :getRowId="getRowId"
      :theme="themeQuartz"
    />
  </div>
</template>

<script setup lang="ts">
import { AgGridVue } from 'ag-grid-vue3'
import { ref } from 'vue'
import { themeQuartz, type ColDef, type GetRowIdParams } from 'ag-grid-community'

interface Row { uniqueKey: string; skill: string; contentTitle: string }

const columnDefs = ref<ColDef<Row>[]>([
  { field: 'skill', spanRows: true },
  { field: 'contentTitle', tooltipField: 'contentTitle' }
])
const defaultColDef = { resizable: true }
const rowData = ref<Row[]>([
  { uniqueKey: 's1-c1', skill: 'Vue', contentTitle: '响应式' },
  { uniqueKey: 's1-c2', skill: 'Vue', contentTitle: '组件' }
])

const getRowId = (params: GetRowIdParams<Row>) => params.data.uniqueKey
</script>

示例使用 v33 起的 Theming API。旧 CSS 主题需按版本显式配置 theme: "legacy" 并加载对应 CSS，不能只保留 ag-theme-alpine 类名就与新主题混用。

4) 启用合并（示例说明）

在 columnDefs 中对需要合并的列加 spanRows: true。
启用 enableCellSpan=true；它是初始化选项。需要 CellSpanModule，使用支持该功能版本的 AllCommunityModule 时可一并注册。
默认合并相邻叶子行中相等的值，不表示跨不相邻行自动聚合；排序、筛选后的显示关系应实际检查。
getRowId 用于行标识（当你生成 uniqueKey 避免重复 ID 时非常重要）。

5) 虚拟滚动与服务器端分页

AG Grid 默认已经实现 DOM 虚拟化（视图虚拟化）。
若使用服务器端分页/虚拟化，请使用 AG Grid 的 Server-Side Row Model 或 Infinite Row Model（按需加载）：
- infinite 是社区版可用的按块加载模型；serverSide 属于 Enterprise，需要对应模块与许可。
- 提供 datasource，AG Grid 会在滚动接近底部时请求新页数据。

三、实战经验（项目中遇到的关键点）

数据唯一键（getRowId）
- 如果后端 contentId 存在重复（例如一个 content 在多个 skill 下出现），需要构造 uniqueKey（例如 ${skillId}-${contentId}），并在 getRowId 返回它，避免 AG Grid 的 “No unique row id” 或行 key 冲突。
模块注册错误
- 常见报错：No AG Grid modules are registered!。解决方法是确保在使用 AgGridVue 之前执行 ModuleRegistry.registerModules(...)。
与 CSS 的互动
- AG Grid 使用自己的单元格 DOM（div.ag-cell），可以通过 .ag-cell / .ag-header-cell 调整对齐、行高、字体等（示例项目已把 cell 设置为 display:flex; align-items:center 以实现垂直居中）。
Row Spanning 与虚拟渲染
- 合并、行模型、排序和虚拟渲染的组合有版本与功能限制，不能仅凭支持虚拟滚动就推断任意合并方式都可用。
Tooltip 与文本截断
- 使用 tooltipField 或 tooltipValueGetter 来显示完整文本（即使单元格被 text-overflow: ellipsis 截断）。
性能建议
- 尽量在后端做过滤/分页/排序，减少前端数据量。
- Server-Side Row Model 将加载与部分运算交给服务器，但仍需正确的数据源与查询实现，不自动保证性能。
- 减少复杂 cell renderer（尽量用简单的 DOM/模板），复杂渲染放到懒渲染或外部弹窗。

四、经验总结（要点）

AG Grid 适合需要高性能、复杂表格交互（大数据、行/列合并、服务器端模型）的场景。
如果你的合并需求仅是静态或每 N 行固定合并，轻量级组件（Element Plus 的 table）可能更简单；但如果要求与虚拟滚动/增量渲染配合，AG Grid 是更稳健的选择。
集成注意事项：模块注册、唯一行 ID、尽量把重逻辑放服务器端。

五、信息参考

AG Grid 官方文档（Row Spanning）: https://www.ag-grid.com/vue-data-grid/row-spanning/
AG Grid Vue 介绍: https://www.ag-grid.com/vue-data-grid/
AG Grid 社区模块注册: https://www.ag-grid.com/javascript-data-grid/modules/
项目中实现要点示例：src/views/edp/learningcontentsnapshot/LearningContentTable.vue

验证

在目标 Vue 项目中确认模块与主题加载成功，两条示例数据显示为两行且 Vue 单元格跨行；再检查排序、过滤后合并是否符合业务语义。行 ID 必须稳定且唯一，简单拼接 ID 时要确保分隔符不会造成碰撞。

旧记录的项目路径 src/views/edp/learningcontentsnapshot/LearningContentTable.vue 保留为历史定位线索；该文件不在本知识库中，不能把其中样式或脚本当作当前仓库实现。