简介ag-Grid Community 是一套面向 React、AngularJS、Web Components 等主流前端栈的数据网格开源库适用于后台管理、数据分析、实时监控等需要高效展示和操作大量表格数据的开发场景。它内置高性能虚拟渲染、排序、过滤、分组、分页、列宽调整与冻结、单元格编辑及自定义验证等丰富能力同时支持自定义单元格渲染器、多主题和运行时 API让开发者可以按业务需求自由扩展。资源包共 2000 个文件约 190MB其中以 js 与 ts 源码为核心配合 html、css、php、json 等辅助文件以及 png/svg 图标、mp4 演示和 md 说明文档形成了从源码到应用的完整资源链。已有 1458 人学习下载社区反馈活跃。通过整理好的示例工程和配置代码读者能够快速完成安装初始化掌握列定义、数据绑定、事件响应与 API 调用并对照源码理解虚拟滚动、冻结列、分组等高级特性的实现思路轻松集成到现有项目或进行二次开发。1. 为什么生产环境里的列表页我兜兜转转还是回到 ag-grid-community我接过一个模拟项目X列表页数据才三千行原来的表格组件一拖滚动条就掉帧排序还经常卡到白屏。换了几套方案都顾头不顾尾最后老老实实换成 ag-grid-community。它解决的问题很直接用虚拟滚动把渲染范围压到肉眼可见的几十行排序、过滤、分页这些中后台刚需改成配置就能用省得自己造轮子。它适合数据密集型管理后台、报表查询页面也适合列需求经常变的产品团队。如果你是前端新手下面这套步骤能让你半小时跑通第一版如果你已经在用其它表格库也不要急着跳过第 2 章社区版和商业版的边界比你想的更让人容易返工。2. 先看清楚社区版和商业版分界线免费的这些够你用别等上线前返工ag-grid-community 是 ag-grid 向社区开放的那部分代码遵循宽松的开源协议可以免费商用。需要留意的是官方同时有带 license 的 enterprise 版本。社区版并不是阉割到只能看它已经把前端表格里八成刚需覆盖了但少的那两成往往是你最想做的那种炫酷交互。所以我先帮你把边界画出来免得需求聊到一半才发现功能要额外授权。2.1 社区版自带的能力清单排序、过滤、分页、虚拟滚动、单元格交互我一般把社区版能力归纳成四块数据展示、数据操作、数据更新、界面适配。对于大多数中后台页面这四块够用到项目交付不需要碰 enterprise 配置。能力类型具体功能使用备注数据展示虚拟滚动、固定列、自动列宽、自定义单元格渲染默认开启虚拟滚动数据多时不至于整表渲染数据操作单列/多列排序、文本/数字/日期/集合过滤、客户端分页多列排序需要按住 Shift 点击列头单元格编辑双击编辑、编辑器校验、提交前回调需要列定义里声明 editable: true行选择Checkbox 复选、单选获取选中行数据配合 rowSelection 使用导出CSV 导出纯前端完成不含样式和公式排序、过滤、分页是 ag-grid-community 最常用的三件套。sortable 和 filter 都是列级配置可以在每列单独开也可以用 defaultColDef 一次铺满全表。客户端分页适合几千到两三万行的场景前端只做切页体验很顺。如果数据量再往上走就需要考虑是不是让后端分页了这一点在避坑章节我会详细展开。2.2 商业版独有的能力以及为什么我劝你先留好换版的口子真正需要 license 的典型功能包括行分组与聚合、透视表、主从表、树形数据、服务端行模型、范围选择、Excel 格式导出。社区版没有这些至少我长期使用的版本里没有。难点不在于少功能而在于你一开始把这些交互做成了业务需求后续改版成本就高了。我的建议是第一版代码里尽量让业务层不直接和 ag-grid 的 enterprise API 耦合。具体做法是封装一个自己的 Table 组件只对外暴露 columns、rows、pageSize 这类业务字段内部不管以后换 community 还是 enterprise页面其他代码都不需要大改。这样真到了需要分组的某一天你只需要在封装层打开分组配置而不是满仓库找散落的 grid 调用。2.3 拿什么标准来判断“社区版够不够”一张过滤清单接到需求时先问自己三个问题数据会不会超过一页展示且需要跨页统计需不需要把多列拖拽成组导出文件是否必须 xlsx如果答案都是否社区版基本能扛。超过十万行且要求毫秒级过滤时社区版虚拟滚动能渲染但网络层不可能把全量数据拉到前端这种场景才需要服务端行模型社区版确实覆盖不了。我个人的判断底线是这样的只要业务里出现“行内展开子表”“拖拽字段分组”“导出带格式 Excel”这几种词就默认预算是企业版否则先拿 community 做原型。原型阶段不要用 enterprise 的 API 写死交互否则后面要么加预算要么自己硬造一个不稳定的替代品两者都难受。提示社区版支持 CSV 导出但不支持带格式的 .xlsx 导出。如果你的“导出”只是让用户拿数据CSV 够用如果领导要做格式化月报尽早把 enterprise 列进预算。3. 用 npm 快速跑通 ag-grid-community 的最小表格从安装到数据刷新这一章直接进入可复现步骤。我用 React 做示例因为中后台项目里 React 和 Vue 占大多数如果你用的是原生 JS 或 Vue核心配置概念完全一致只是组件标签写法不同。3.1 安装与引入社区版核心包和样式的最小组合一个 React 项目我会装两个包。第一个是核心库 ag-grid-community第二个是 React 封装层 ag-grid-react。Vue 项目则换成对应的 vue 封装包底层仍然是 ag-grid-community。npm install ag-grid-community ag-grid-react装完之后样式很容易被忽略。ag-grid 的样式分成两层基础样式 ag-grid.css 负责网格本身的布局和虚拟滚动容器主题样式 ag-theme-quartz.css 负责颜色、边框、字体。两个都要引少一个都有问题。import ag-grid-community/styles/ag-grid.css; import ag-grid-community/styles/ag-theme-quartz.css;我见过有人只引了主题结果滚动容器宽度计算异常列头位置错乱。还有一个容易踩的点主题 class 不是写在表格组件上而是写在包裹表格的父 div 上这个 class 会告诉 ag-grid 使用哪个主题变量不写就退化成无样式状态。3.2 最小 demo列定义、行数据、网格容器一个都不能少下面是最小可用示例。它包含了三个必要部分rowData 行数据、columnDefs 列定义、包裹 Grid 的 div 容器。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 BaseGrid() { const [rowData] useState([ { id: 1, name: 订单A, status: SUCCESS, amount: 1000 }, { id: 2, name: 订单B, status: PENDING, amount: 2300 }, ]); const columnDefs useMemo( () [ { field: id, headerName: 单号, width: 80 }, { field: name, headerName: 订单名称 }, { field: status, headerName: 状态 }, { field: amount, headerName: 金额 }, ], [] ); return ( div classNameag-theme-quartz style{{ height: 400, width: 100% }} AgGridReact rowData{rowData} columnDefs{columnDefs} / /div ); }说明一下这段配置的逻辑。columnDefs 里 field 对应 rowData 里的字段名headerName 决定列头显示什么不写 headerName 时默认直接显示 field。外层 div 必须有高度ag-grid 默认会撑满父容器尺寸父容器高度为 0 时表格渲染不出来这是很多新手踩的第一个坑。useMemo 缓存列定义是为了避免每次 render 都生成新数组后面会详细讲。3.3 数据刷新replaceAll、setRowData 与 IMMUTABLE 该选哪个表格跑起来之后下一个问题就是如何更新数据。常见做法有三种整表替换用 setRowData需要局部增删改用 applyTransaction还有一种是开启 IMMUTABLE 更新策略。const gridRef useRef(null); // 整表替换后端每次返回全量新数据 const loadFirstPage async () { const rows await fetchOrders({ page: 1 }); if (gridRef.current?.api?.setGridOption) { gridRef.current.api.setGridOption(rowData, rows); } else { gridRef.current.api.setRowData(rows); } }; // 局部更新只更新变化的那几行 const updateChangedRows (changedRows) { gridRef.current?.api.applyTransaction({ update: changedRows }); };第一段代码里同时写了 setGridOption 和 setRowData是因为 ag-grid 在较新版本里统一推荐 setGridOption 这样的新入口但老项目里 setRowData 还在大量使用。兼容写法不会报错升级成本也低。replaceAll 这个概念实际上等同于把 rowData 重新赋一个新数组所以不要指望它做细粒度更新。真正推荐的局部更新姿势是 applyTransaction。它的入参是 add、remove、update 三个数组分别表示新增、删除、更新的行。它比整表替换高效得多因为 grid 不需要重建整个行模型只处理差量。但它要求每行有稳定唯一的主键并且通过 getRowId 告诉 grid。AgGridReact ref{gridRef} rowData{rowData} columnDefs{columnDefs} getRowId{(params) params.data.id} /getRowId 返回的值必须是业务里唯一的主键。如果拿不到稳定 idapplyTransaction 会更新错行这是这类表格最容易出现的玄学问题。我的习惯是任何列表数据都在前端维护一个唯一 id 字段不依赖数据库自增主键避免跨页合并数据时冲突。3.4 把排序、过滤、分页一次开齐的配置开排序和过滤不需要每个列写一遍用 defaultColDef 统一设置即可。这个配置会应用到所有列除非某个列在自己的列定义里覆盖。const defaultColDef useMemo( () ({ sortable: true, filter: true, resizable: true, }), [] ); AgGridReact columnDefs{columnDefs} rowData{rowData} defaultColDef{defaultColDef} pagination paginationPageSize{20} rowSelectionmultiple /;sortable 控制列头是否可点击排序filter 默认为每一列生成合适的过滤器。数字列会自动匹配数字过滤器文本列自动匹配文本过滤器。如果要指定类型可以写成 filter: agNumberColumnFilter 或 agSetColumnFilter。分页开启后默认每页 100 条我一般会显式设置 paginationPageSize。rowSelection 用于开启多选如果你还需要 checkbox在列定义里加上 checkboxSelection: true。提示filter: true 不等于所有数据都能被正确过滤。日期字段必须用正确的日期格式否则过滤器只能按字符串匹配跨年份的筛选结果会让你怀疑人生。4. 自定义单元格渲染与编辑从“表格只展示”到“表格能操作”真实业务里没有多少表格是纯展示的。状态码要转成中文操作列要放按钮金额要格式化某些列还得允许用户双击编辑。这一章讲清楚三个最常见的自定义点。4.1 用 valueFormatter 把后端返回的状态码转成可读文案后端返回的状态字段往往是 SUCCESS、PENDING、FAILED 这类枚举直接显示给业务方看非常不友好。最简单的做法是 valueFormatter它接收原始值返回你要展示的文本不改动 rowData 本身。const STATUS_TEXT { SUCCESS: 已完成, PENDING: 排队中, FAILED: 失败, }; const columnDefs [ { field: status, headerName: 状态, valueFormatter: (params) STATUS_TEXT[params.value] ?? params.value, }, ];valueFormatter 的第一个参数是 params里面至少包含 value 和 data。value 是当前单元格原始值data 是当前行完整对象。这里用空值合并运算符兜底遇到没匹配上的枚举值就原样输出避免出现一堆 undefined。如果你只要显示文本用它就够了如果要改样式比如“失败”显示成红色就不能靠 formatter而是配置 cellClassRules 或自定义 cellRenderer。4.2 写一个自定义 cellRenderer操作列里的按钮和进度条操作列是 cellRenderer 最常见的场景。这个函数组件接收 ag-grid 注入的 props返回的 DOM 会被放进单元格。const ActionCellRenderer (props) { const onDetail () { const latest props.node.data; console.log(查看详情, latest.id); }; const onEdit () { props.api.startEditingCell({ rowIndex: props.node.rowIndex, colKey: remark, }); }; return ( div style{{ display: flex, gap: 8px }} button onClick{onDetail}详情/button button onClick{onEdit}编辑备注/button /div ); };在列定义里使用它{ field: action, headerName: 操作, cellRenderer: ActionCellRenderer, width: 160, }props 里比较关键的字段是 value、data、node、api。node 是行节点data 是当前行数据。我需要专门提醒一个坑不要在 cellRenderer 创建时把 props.data 直接闭包进事件回调排序、过滤、行复用之后闭包里的引用可能还是旧行。正确做法是在点击事件内部通过 props.node.data 现取这样拿到的永远是最新数据。startEditingCell 可以主动让某个单元格进入编辑状态这里我用来让“编辑备注”按钮直接跳到 remark 列。4.3 cellEditor 的最小实现输入校验与失焦回填如果你需要用户直接在表格里改数字或文本就要写 cellEditor。ag-grid 的编辑器在 React 里建议用类组件实现因为它底层需要实例上的 getValue 方法函数组件没办法稳定暴露这个接口。import { Component } from react; class NumericTextEditor extends Component { constructor(props) { super(props); this.state { value: props.value ?? }; } getValue() { const num Number(this.state.value); return Number.isFinite(num) ? num : this.state.value; } isCancelAfterEnd() { return this.state.value.trim() ; } render() { return ( input autoFocus value{this.state.value} onChange{(e) this.setState({ value: e.target.value })} style{{ width: 100%, boxSizing: border-box }} / ); } }列定义里开启编辑{ field: amount, headerName: 金额, editable: true, cellEditor: NumericTextEditor, }getValue 是提交时被调用的方法返回值会作为新的单元格值写入行数据。这里我做了一层 Number 转换保证数字列拿到的是数字而不是字符串。isCancelAfterEnd 返回 true 表示本次编辑取消我用来处理空输入。编辑器默认 Enter 提交、Esc 取消这是内置行为不需要额外配置。写自定义编辑器时最容易漏的是样式表格单元格里的 input 如果不设宽度会出现内容溢出所以我给 input 设置了 width: 100% 和盒模型修正。5. ag-grid-community 性能与兼容性避坑五条值得写进团队文档的排错记录这个表格库整体稳定但特定场景下的坑比较固定。每一条都是我先看到现象、再定位原因、最后给出解决办法的真实路径希望你不用重走一遍。5.1 现象表格在隐藏 Tab 里初始化切回来全部挤成一列中后台系统特别爱用 Tab 页签我遇到过表格放在非激活 Tab 里初始化切回来整列宽度全部塌缩滚动条也消失。原因是初始化时父容器处于 display: none 状态宽度被浏览器算成 0ag-grid 按照 0 宽度绘制了列布局等 Tab 显示时它并不知道外部尺寸变了。解决方式是在 Tab 切换完成后主动通知 grid 尺寸变化。const handleTabShow () { setTimeout(() { gridRef.current?.api.onGridSizeChanged(); }, 50); };延迟 50ms 是为了等 Tab 动画或样式切换完成确保父容器已经有真实宽度。如果 Tab 是反复切换的那种我建议在初始化时就判断当前 Tab 是否激活不激活就先不渲染表格组件等到激活再渲染从根上避免这个测量问题。5.2 现象后端分页前端点过滤只过滤了当前页这个坑几乎是服务端分页标配。后端按 page 返回数据时前端拿到的只是当前页的几十行此时 ag-grid 社区版默认的过滤和排序都只作用在这几十行上用户以为自己筛了全量实际只筛了当前页结果明显不对。原因很明确社区版没有服务端行模型它不知道后面的数据长什么样。解决办法是把 filterModel 和 sortModel 传给后端让后端在 SQL 层过滤排序。const getRequestParams () { const filterModel gridRef.current.api.getFilterModel(); const sortModel gridRef.current.api.getSortModel(); return { page, pageSize, filterModel: JSON.stringify(filterModel), sortModel: JSON.stringify(sortModel), }; };后端拿到 filterModel 后需要做条件拼接。需要注意的细节是onFilterChanged 和 onSortChanged 事件会在每次过滤排序变化时触发如果直接在里面发请求可能连续打出好几个重复请求。我的做法是加一个防抖定时器等 300ms 内的最后一次变化再请求。5.3 现象自定义操作列按钮点击后拿到的是旧行数据或旧编号表格排序、过滤后行的显示顺序会变。ag-grid 为了性能会复用单元格 DOMcellRenderer 实例可能不会重新创建导致按钮回调里闭包的数据还是最初渲染那一行的数据。典型表现是点第一行的“详情”弹出来的却是另一个人的单号。原因就是事件闭包绑死了旧引用。解决方式分两步。第一事件回调内部永远通过 props.node.data 去取当前数据不要用 props.data 做闭包缓存。// 错误示范闭包锁定了渲染时的旧数据 const onDetail () { console.log(props.data.id); }; // 正确写法点击时再取当前行数据 const onDetail () { console.log(props.node.data.id); };第二如果发现更新行数据后按钮里的文字或样式没有变这通常是 cellRenderer 没有刷新。强制方案是调用gridRef.current.api.redrawRows()它会重建可视区域的行节点代价比 refreshCells 大但能解决顽固旧渲染。5.4 现象保存的筛选模型恢复不生效很多系统需要让用户保存一组筛选条件下次进来一键还原。我用 getFilterModel 保存刷新页面再用 setFilterModel 恢复结果有些列生效有些列没反应像是被静默吞掉了。定位后发现 filterModel 里的 key 是列定义的 field但恢复时必须保证对应列存在并且列类型一致。如果列被隐藏了或者列过滤器和保存时不是同一个类型恢复就会失败。更稳妥的做法是把列状态和筛选模型一起保存恢复时先恢复列状态再设置 filterModel。const saveGridState () { return { filterModel: gridRef.current.api.getFilterModel(), columnState: gridRef.current.columnApi.getColumnState(), }; }; const restoreGridState (state) { gridRef.current.columnApi.applyColumnState({ state: state.columnState }); gridRef.current.api.setFilterModel(state.filterModel); };applyColumnState 会恢复列的顺序、宽度、排序和显隐状态。顺序不能反因为 setFilterModel 依赖过滤器已经存在。这个组合拳同样适用于把状态存到 localStorage 或 URL 参数里。5.5 现象单元格里塞富文本或图片滚动时闪烁、位置飘运营后台的备注列总想放一段带格式的 HTML或者放一张缩略图。我试过直接在 cellRenderer 里返回 img 标签结果滚动时图片重新加载行高也被撑得忽高忽低整个表格像抽风一样。原因是虚拟滚动复用单元格 DOM滚动过程中单元格内容频繁重建图片加载时机不可控行高变化又影响滚动位置。解决思路是把富文本和图片从表格核心区域挪出去。常见做法是把完整内容放在 tooltip 里行内只显示纯文本摘要。{ field: remark, headerName: 备注, tooltipField: remark, tooltipComponent: RichTooltip, }tooltip 在 hover 时再渲染不会参与虚拟滚动的行高计算。如果图片一定要在列表里展示那就固定一个宽高并开启 suppressCellFlash 减少闪烁同时给行设置固定 rowHeight。反正别让单元格高度动态变化这是虚拟滚动最讨厌的情况。6. 最后再补两刀把 ag-grid-community 用成一套可复用模板6.1 用 useMemo 缓存 columnDefs 和 defaultColDefReact 组件每次 render 都会执行函数体如果直接写一个数组变量ag-grid 会认为列定义是新的可能触发不必要的重绘严重时连排序状态都丢。我习惯把所有列相关配置都放进 useMemo。const columnDefs useMemo( () [ { field: name, headerName: 名称 }, { field: status, headerName: 状态 }, ], [] ); const defaultColDef useMemo( () ({ sortable: true, filter: true, resizable: true }), [] );这个习惯成本极低但能省掉大量“为什么表格自己刷新”的排查时间。依赖数组里如果有动态字段比如权限控制才需要把对应变量加进去。6.2 把排序和筛选状态做成“视图切换”业务方常见的诉求是“我要一键只看今日成功订单”。与其教他们手动配置一堆筛选条件不如给表格做一个预置视图按钮。核心代码还是 getFilterModel 与 setFilterModel。const applyTodaySuccessFilter () { const gridApi gridRef.current.api; gridApi.setFilterModel({ createdAt: { type: greaterThan, dateFrom: new Date().toISOString().slice(0, 10), }, status: { values: [SUCCESS] }, }); };注意日期过滤器的 model 结构要求列定义里 filter 是 agDateColumnFilter并且字段名要和 filterModel 的 key 完全一致。我给一个业务配置了五六个这样的快捷按钮全部是同一套逻辑代码极其好维护。配合 5.4 的 saveGridState还可以把每个按钮对应的完整网格状态存到 localStorage刷新页面后一键还原。我现在的习惯是任何新列表页先按第 3 章的最小 demo 搭再往上面加功能凡是涉及行更新的逻辑一律走 applyTransaction不在业务里整行 push。这个习惯帮我避开了绝大多数刷新闪烁和误操作。希望帮到你。本文还有配套的精品资源点击获取