简介面向使用 JavaScript、React、AngularJS 与 Web Components 的前端开发者这是一份 ag-Grid Community 开源数据网格库的源码与示例素材包适合需要处理海量数据表格、自定义单元格渲染、排序过滤分组、分页和编辑校验等场景的中级开发人员参考对复杂表格交互与大数据量展示有较完整的覆盖。压缩包内共 2000 个文件以 js、ts、html、css、json 等前端源码和配置为主并包含 png、svg、gif 等界面与说明素材以及少量 php、java 辅助文件整体约 190.14MB目录素材较丰富便于按模块查阅与对照。已有 1464 人学习或下载。读者可据此了解网格初始化、列定义、运行时 API、事件系统和主题定制等实现方式也能结合示例页面与样式资源对照组件行为适合作为搭建后台数据表格、研究虚拟化渲染和框架集成方案的参考资料并帮助理解常见配置项的用途。1. 一张只有表头、下面是空白的表格ag-grid-community 装错的第一步在哪去年冬天有个中后台项目本地npm run dev跑得好好的表格能滚、能排序、能筛打进测试环境之后表头还在下面一片空白控制台干干净净什么报错都没有。查了半天原因是构建时把样式表 tree-shake 掉了一半加上列定义里的模块没注册。ag-grid-community 这个前端开源表格库接入面很广React、Vue、Angular、原生 JS 都能用正因为“都能用”装错的路子也格外多样式漏引、模块没注册、框架封装包和核心包主版本号对不上症状各不相同但最终表现都是“表格不显示”。它适合数据量上万、需要虚拟滚动、列固定、行分组、服务端分页的中后台表格页如果只是渲染十几行静态数据引它纯属给自己加负担。下面的顺序是先看清要装哪几个包、环境底线在哪再跑起来一张最小的表然后拆配置最后把我装坏过的几次和验收方法摊开。2. 环境与包结构Node、包管理器、适配包怎么选2.1 Node 版本与包管理器的底线ag-grid-community 本身是纯前端库没有原生模块理论上不挑 Node但它的构建产物和类型声明是按现代语法打的Node 太老会在安装阶段就报Unexpected token或者解析exports字段失败。我一般要求 Node 用当前 LTS 大版本先确认一下node -v # 建议 LTS 大版本非 LTS 的奇数额度容易在构建链路出问题 npm -v包管理器更值得说。npm 和 yarn 走的是扁平化node_modules一般不会出问题pnpm 是软链接 严格依赖隔离而 ag-grid 的新版把功能拆成了多个子包框架适配包和核心包之间靠 peer 依赖互相找隔离一严就容易出现“装是装了但运行时找不到模块”。踩过这个坑之后我在用 pnpm 的项目根目录固定放一个.npmrc# 把 ag-grid 相关的包提到根 node_modules绕开软链接隔离 public-hoist-pattern[]*ag-grid* # 实在搞不定时的保底方案代价是失去严格隔离的好处 shamefully-hoisttruepublic-hoist-pattern只对匹配到的包做提升比shamefully-hoist温和优先用前者。改完.npmrc必须删掉node_modules和 lockfile 重装因为提升关系是在安装期算出来的改配置不重装不生效。2.2 社区版和企业版的分包差异先看清依赖树装之前先明确一件事ag-grid 有社区版和企业版两套包。社区版就是你项目标题里那个ag-grid-communityMIT 授权覆盖排序、筛选、分页、虚拟滚动、列固定、CSV 导出这些常规能力企业版是另一个包名行分组、透视表、服务端行模型、Excel 导出那些要它。新手最容易犯的错是“照着某篇教程装了企业版包名”本地能跑上线被授权校验卡住。先看一眼依赖树确认自己装的是哪一挂# 列出当前工程里所有和 ag-grid 相关的包及其版本 npm ls ag-grid-community ag-grid-enterprise --depth1再看新版的分包结构。拆包之后的版本核心逻辑在ag-grid-community/core每一项功能单独成包比如客户端行模型、文本筛选、分页各自一个。你在业务代码里通常只import顶层包名但打包器解析到的是这些子包。这就带来两个直接后果一是“我明明装了却报模块不存在”多半是子包版本没对齐二是“按需引入”从建议变成了必须做的事全量引入会让首屏包体积明显变大。判断自己装的是拆包前还是拆包后最直接的办法是看node_modules/ag-grid-community/这个目录存不存在。包名作用是否必需ag-grid-community社区版入口包业务代码主要 import 它必需ag-grid-community/core拆包后的核心实现通常不直接 import随主包带出ag-grid-react/ag-grid-vue3/ag-grid-angular框架声明式封装用对应框架时必需ag-grid-enterprise企业能力包有授权校验社区版场景不要装2.3 框架适配包怎么挑版本为什么必须对齐选包只看一条你的渲染层用什么。原生 JS 或不用框架的页面只装ag-grid-community一个就够React 项目装ag-grid-communityag-grid-reactVue 3 装ag-grid-communityag-grid-vue3Vue 2 用的是另一个包名别混Angular 装ag-grid-communityag-grid-angular后者会声明angular/core的 peer 依赖版本跨度太大安装期就警告。# React 项目核心包 框架封装包一起装 npm i ag-grid-community ag-grid-react # Vue 3 项目 npm i ag-grid-community ag-grid-vue3这里有个血泪经验两个包的主版本号必须一致。框架封装包内部是按核心包的 API 写的核心包大版本一升createGrid之类的入口签名可能变封装包还按老签名调表现就是组件挂载了、DOM 里也有容器就是不渲染内容控制台最多给你一句不痛不痒的 warn。装完立刻核对# 两个包的主版本号应当相同 npm ls ag-grid-community ag-grid-react如果版本已经漂了别手动去改node_modules直接把两个包按同一个主版本重装或者在package.json里用同一个^主版本前缀锁住避免以后某次npm update又漂回去。3. 从空目录到一张能滚动的表格ag-grid-community 安装全程3.1 建工程与安装命令为了排除已有项目的干扰先在一个空目录里跑通最小例子。下面用 Vite 起一个 React 工程是最快能看到效果的方式# 建目录并初始化 mkdir grid-demo cd grid-demo npm init -y # 起一个 Vite React 的最小工程跟着提示选 react 模板 npm create vitelatest . -- --template react # 装依赖 npm install # 装表格库 npm i ag-grid-community ag-grid-react # 启动 npm run devnpm create vitelatest . -- --template react里的.表示在当前目录创建双横线后面的参数透传给脚手架--template react决定模板。如果目录里已经有package.json脚手架会问你是否覆盖选不覆盖、只补文件即可。项目已经有构建体系的话跳过前三步只执行npm i ag-grid-community ag-grid-react。装完先别急着写业务跑一次npm run dev确认工程本身是能起的。这一点很多人省掉结果后面表格不显示分不清是插件的问题还是工程的问题。3.2 样式表引入两个文件一个都不能少ag-grid 的样式拆成两份一份是结构样式负责行列布局、滚动容器、虚拟滚动的定位另一份是主题样式负责颜色、字号、边框这些观感。少引第一份表格会塌成一堆没有高度的 div少引第二份能显示但没有任何配色白底黑字挤在一起。// 入口文件里引入顺序不能反先结构后主题 import ag-grid-community/styles/ag-grid.css; import ag-grid-community/styles/ag-theme-quartz.css;路径这点要留个心新版包内样式在styles/下老版多在dist/styles/下且主题名不一样——新版主推quartz老版常见的是alpine、balham、material。引入的时候别凭记忆写路径去node_modules/ag-grid-community/里看一眼实际目录目录叫什么就写什么。提示主题 CSS 文件和你挂在容器上的类名必须成对。引了 quartz 的 css 却写classNameag-theme-alpine框架不会报错你只会看到一张完全没有主题效果的表格排查起来很浪费时间。3.3 最小可运行表格列定义与行数据React 封装包用起来是声明式的核心就两个 propsrowData和columnDefs。import { useMemo, useState } from react; import { AgGridReact } from ag-grid-react; import ag-grid-community/styles/ag-grid.css; import ag-grid-community/styles/ag-theme-quartz.css; export default function DemoTable() { // 行数据字段名要和列定义里的 field 对上 const [rowData] useState([ { id: 1, name: 示例行一, score: 92 }, { id: 2, name: 示例行二, score: 78 }, ]); // 列定义用 useMemo 固定引用否则每次渲染都会生成新数组触发列重建 const columnDefs useMemo(() [ { field: id, headerName: 编号, width: 90, sortable: true }, { field: name, headerName: 名称, flex: 1, minWidth: 160 }, { field: score, headerName: 分数, width: 120, filter: agNumberColumnFilter }, ], []); // 容器必须有确定高度否则虚拟滚动算不出可视区 return ( div classNameag-theme-quartz style{{ width: 100%, height: 480 }} AgGridReact rowData{rowData} columnDefs{columnDefs} / /div ); }三处值得说。field是取值路径写user.name这种嵌套路径也行写错了单元格就是空的但不报错flex: 1让这一列吃掉剩余宽度和固定width的列混用是做自适应表格的常规做法外层容器的高度是硬要求ag-grid 靠测量容器高度来决定渲染多少行容器高度为 0 或者auto结果就是只画表头。不用框架的页面写法不一样新版导出的是工厂函数import { createGrid, ModuleRegistry, ClientSideRowModelModule } from ag-grid-community; import ag-grid-community/styles/ag-grid.css; import ag-grid-community/styles/ag-theme-quartz.css; // 拆包后的版本必须先注册模块不然创建出来是个空壳 ModuleRegistry.registerModules([ClientSideRowModelModule]); const gridOptions { columnDefs: [ { field: id, headerName: 编号, width: 90 }, { field: name, headerName: 名称, flex: 1 }, ], rowData: [ { id: 1, name: 示例行一 }, { id: 2, name: 示例行二 }, ], defaultColDef: { sortable: true, resizable: true }, // 全局默认列行为 }; createGrid(document.getElementById(myGrid), gridOptions);如果你手上的版本没有导出createGrid那大概是拆包前的老版本入口是new Grid(容器, 配置)这种构造式写法。判断方法很土但有效在浏览器控制台里对这个模块打印一下看导出了哪个。别在两个写法之间反复猜。3.4 启动后先看这四处npm run dev起来之后别急着往下写业务先按顺序看四件事表头有没有渲染出来、两行数据在不在、拖动列宽有没有反应、在容器里滚动鼠标滚轮有没有出现纵向滚动条。这四件事分别对应样式结构、列定义映射、交互模块、虚拟滚动容器任何一项挂了问题范围立刻缩小一半。控制台如果有Module X is not registered这类告警别忽略那是模块注册没做全的直接提示。4. 配置拆解列定义、模块注册、主题变量三处4.1 列定义里真正影响体验的字段columnDefs是配置量最大的地方但常用的就那么十几个。下面这张表是我每次接新项目都会过一遍的字段作用注意点field取值路径支持a.b.c嵌套写错不报错只是空headerName表头文案不写则用field原样展示width/flex/minWidth宽度策略flex与固定width可混用minWidth防挤没sortable/resizable排序、拖宽建议放defaultColDef统一开filter筛选器类型需注册对应筛选模块否则筛选图标不出现valueGetter派生列取值用于拼接字段或格式化前的原始值cellRenderer自定义单元格返回组件或渲染函数注意别在里面做重计算pinned左右固定列取值left/right移动端慎用checkboxSelection行选择框配合rowSelection使用我更倾向把公共行为放进defaultColDef列上只写差异项const defaultColDef { sortable: true, // 所有列默认可排序 resizable: true, // 所有列默认可拖宽 filter: true, // 所有列默认开启筛选 minWidth: 100, // 防止窄屏下把列压到看不见 flex: 0, // 默认不吃剩余宽度交给具体列控制 };这样做的直接收益是列定义短改动集中。副作用是filter: true会给每一列都开筛选列多的时候顶部图标很密视觉上乱通常我会在具体列上按需覆盖成false。4.2 模块注册按需引入与全量引入的取舍拆包后的版本把功能切成模块不注册就等于没这个能力。新手最常见的困惑是“我明明写了filter: true筛选图标怎么不出现”答案就是筛选模块没注册。按需注册写法如下import { ModuleRegistry, ClientSideRowModelModule, // 客户端行模型最基础的一个 TextFilterModule, // 文本筛选 NumberFilterModule, // 数字筛选 PaginationModule, // 分页 CsvExportModule, // CSV 导出 } from ag-grid-community; // 一次性注册必须在创建表格之前执行 ModuleRegistry.registerModules([ ClientSideRowModelModule, TextFilterModule, NumberFilterModule, PaginationModule, CsvExportModule, ]);这段代码通常放在应用入口全局执行一次就够不要放在组件内部否则组件每次挂载都重复注册。取舍上按需注册包体积小但每加一个新功能都得回来补一行漏了就是“功能静默失效”全量引入省心代价是首屏体积变大中后台项目里这一项往往能接受对外网首屏敏感的项目就得按需。我的习惯是先按需等模块列表涨到十来项、维护成本明显上来再评估切全量。ClientSideRowModelModule是最容易漏的一个因为其它模块都注册了、表格也能出来唯独数据不显示看起来像是数据结构的问题实际是行模型没注册。4.3 主题与样式覆盖优先用 CSS 变量主题不要直接去改 ag-grid 的类名比如强行覆盖.ag-header-cell的样式。它的 DOM 结构在版本之间会变写死的选择器升级就碎。正确做法是覆盖 CSS 变量主题包暴露了一批--ag-前缀的变量/* 挂在主题容器上只影响这一块表格 */ .ag-theme-quartz { --ag-font-size: 13px; /* 全局字号行高会跟着算 */ --ag-header-background-color: #f5f7fa; /* 表头底色 */ --ag-row-hover-color: #eef4ff; /* 行悬停色 */ --ag-border-color: #e3e6eb; /* 分隔线颜色 */ --ag-cell-horizontal-padding: 12px; /* 单元格左右内边距 */ }这套变量是主题契约的一部分比覆盖类名稳。如果某个效果变量覆盖不到再考虑写类名覆盖并且在选择器上加容器前缀限定作用域避免污染全局。注意样式覆盖文件要在主题 CSS 之后引入。构建工具按引入顺序合并样式顺序反了会被主题默认值盖掉表现是“我写了但没生效”。4.4 大数据量下的行模型与分页配置社区版可用的行模型主要是客户端行模型和无限滚动行模型。客户端行模型一次性拿到全量数据靠虚拟滚动只渲染可视区几万行以内都扛得住数据量再往上、或者数据本身要按需拉取就换成无限滚动按块请求。服务端行模型属于企业版能力社区版场景不要往那个方向设计。const gridOptions { rowModelType: clientSide, // 社区版常用大数据按需拉取可换 infinite pagination: true, paginationPageSize: 50, // 每页行数 paginationPageSizeSelector: [20, 50, 100], rowBuffer: 10, // 可视区外多渲染的行数调大可减少快速滚动白屏 cacheBlockSize: 100, // 无限滚动模型下每块请求的行数 suppressColumnVirtualisation: false, // 列很多时保持列虚拟化开启 };rowBuffer是快速滚动时最值得调的一个参数默认值偏保守机器一般、用户又爱甩滚轮的项目里调到 10 到 20 之间白屏感会明显减轻代价是初始渲染多一些行。paginationPageSize别设太大一页 500 行翻页时会明显卡一下50 到 100 是比较稳的区间。5. 避坑与排查五条装坏之后的救法5.1 只有表头没有数据行现象表头正常渲染列名也对容器下面一片白控制台没有红色报错最多一条黄色的模块告警。原因拆包版本下ClientSideRowModelModule没有注册或者注册代码写在创建表格之后。行模型负责把rowData转成可视行缺了它表格有列无行。解决在应用入口、创建表格之前注册这个模块然后重启 dev server。如果注册了还是不显示下一步查容器高度是不是 0——打开元素面板看表格容器实际高度高度塌了同样只画表头。5.2 样式错乱图标变成方块现象表格能显示但排序箭头、筛选漏斗、展开三角全是方块或空白方框行高也不对。原因结构样式表ag-grid.css引了、主题表没引或者主题类名和引的主题文件不匹配另一种情况是项目里有全局样式把font-family强设成了不含图标的字体图标字体被顶掉。解决确认结构和主题两份 CSS 都引了、顺序是先结构后主题、容器上的ag-theme-xxx类名和引入的主题文件名一致。三步都对还是方块就去查全局样式里的font-family通配规则把它限定到具体容器上。5.3 打包体积异常增大现象只加了一张表格页构建产物比之前大了好几百 KB首屏加载明显变慢。原因一是全量引入模块把所有功能都打进包里二是框架封装包和核心包的版本没对齐导致核心包被打进两份三是直接import了企业版包把用不到的能力一起带进来。解决先跑一次构建分析看 ag-grid 相关包实际占了多少、有没有重复确认依赖树里只有一个主版本然后按需注册模块把筛选、导出这些非首屏必需的能力评估是否延后加载。# 用 npm 自带的依赖树排查重复的 ag-grid 包 npm ls ag-grid-community ag-grid-react ag-grid-enterprise如果输出里同一个包出现了两个不同主版本说明锁文件里有残留删node_modules和 lockfile 重装。5.4 服务端渲染时报 document is not defined现象本地浏览器跑正常一上服务端渲染就报document is not defined构建阶段中断。原因ag-grid 要在浏览器里测量容器尺寸、创建 DOM模块顶层也有对window、document的访问。服务端没有这些对象导入即崩。解决把表格组件改成只在客户端加载用动态导入避开服务端求值同时确认注册模块的代码也放在客户端侧执行不要放在服务端入口的顶层。// 仅在客户端动态加载表格组件避免服务端求值时报 document 未定义 import dynamic from next/dynamic; const DemoTable dynamic(() import(./DemoTable), { ssr: false, loading: () div style{{ height: 480 }}加载中/div, });5.5 列宽拖动、筛选点了没反应现象表格能滚能选但拖动列边框没有反馈点筛选图标下拉不出来排序点击也没变化。原因对应的功能模块没注册。拆包之后排序、筛选、列宽调整这些交互都各自绑定模块defaultColDef里写sortable: true只是声明意图没有模块提供实现就静默失效。解决按实际用到的交互补注册对应模块改完重启如果用的是自定义筛选组件还要确认该组件本身的模块依赖也注册全了。补完之后回到 3.4 那四处检查重新过一遍。6. 装完怎么验证一张验收表和我的三步自检装完不等于装对。我判断一套 ag-grid-community 环境是否真的可交付不看页面能不能截个图而是跑一遍下面这张表。每一项都能在浏览器里两分钟内点完任何一项没过都说明还有一处配置没落地。验收项操作通过标准结构样式打开页面表头、数据行、边框齐全无元素塌陷主题生效比对设计稿主色表头底色、悬停色与设计一致行模型看数据行行数与rowData一致不是只有表头虚拟滚动灌 5000 行后快速滚动不白屏滚动条长度合理排序点表头两次升降序切换图标同步变化筛选点筛选图标下拉能弹出输入后行数变化列宽拖列边框宽度变化相邻列跟随包体积跑一次构建分析没有重复的 ag-grid 主版本三步自检我固定这么走。第一步是空数据起步把rowData设成空数组看表头能不能正常出来、列名对不对、空态提示有没有。空数据阶段就能暴露样式和列定义的问题比灌了数据再排查干净得多。第二步灌入五千行假数据专门看滚动快速上下甩滚轮看有没有大块白屏、有没有行卡住不刷新这直接反映rowBuffer和虚拟滚动配置是否合适。第三步打开构建分析确认包体积没有异常尤其是有没有两个不同主版本的 ag-grid 同时被打进去——这个后悔药大家都不想在线上吃。还有个小技巧新建一个只含表格的空白页作为独立路由不要一上来就塞进业务页面里。业务页面的全局样式、布局 flex、祖先容器高度都会干扰表格的表现独立页能跑通再去业务页接线出问题时你可以立刻判断是插件的事还是页面布局的事。从那以后我每次接 ag-grid不管是新项目起盘还是往老项目里塞都强制走一遍这三步——空数据看结构、灌数据看滚动、跑构建看体积。这套流程花不了二十分钟省下来的排查时间大概率是它的好几倍。希望帮到你。本文还有配套的精品资源点击获取