AgGrid学习笔记

Feature	AG Grid Community(社区版)	AG Grid Enterprise(企业版)
Filtering	✅	✅ (Advanced)
Sorting	✅	✅
Cell Editing	✅	✅
CSV Export	✅	✅
Drag & Drop	✅	✅
Themes and Styling	✅	✅
Selection	✅	✅
Accessibility	✅	✅
Infinite Scrolling	✅	✅
Pagination	✅	✅
Server-Side Data	✅	✅ (Advanced)
Custom Components	✅	✅
Integrated Charting	❌	✅
Range Selection	❌	✅
Row Grouping and Aggregation	❌	✅
Pivoting	❌	✅
Excel Export	❌	✅
Clipboard Operations	❌	✅
Master/Detail	❌	✅
Tree Data	❌	✅
Column Menu	❌	✅
Context Menu	❌	✅
Tool Panels	❌	✅
Support	❌	✅

一、下载

1.npm命令下载(推荐)

命令行：npm install --save ag-grid-community

文件结构：

在ag-grid-community下的dist文件夹中有相关js文件

2.从 GitHub 下载源码(不推荐)

AgGrid 在 GitHub 上开源了社区版代码，可以直接下载：

访问仓库 ： https://github.com/ag-grid/ag-grid

下载步骤：

点击绿色的 Code 按钮
选择 Download ZIP ，文件大小在310M，Git官网下载较慢，可以使用码云(代码托管的工具)快速下载压缩包
解压后需要打包项目，使用 dist/ 目录下的文件

版本选择 ：可通过 Releases 标签选择特定版本（如 v33.3.2）： https://github.com/ag-grid/ag-grid/releases

3.从 CDN 手动下载

如果不想使用 npm 或 GitHub，也可以从 CDN 复制所需文件：

访问 CDN 链接 ： https://cdn.jsdelivr.net/npm/[email protected]/
下载所需文件：
- JS 文件：ag-grid-community.min.js
- CSS 文件：styles/ag-theme-alpine.css 等
- 语言包：i18n/zh-CN.js

二、引用

JavaScript应用

这里我引入的是ag-grid-community.min.js，无需加载其他css样式类，应用默认的alpine主题样式，若想自定义主题样式可引入ag-grid-community.min.noStyle.js文件，

代码示例：

html 复制代码

<html lang="en">
     <head>
         <script src="./distV33.3.2/ag-grid-community.min.js"></script>
     </head>
     <body>
         <div id="myGrid" style="height: 500px"></div>
     </body>
     <script>
         const gridOptions = {};
 
         const myGridElement = document.querySelector('#myGrid');
         agGrid.createGrid(myGridElement, gridOptions);
     </script>
 </html>

三、启用列过滤配置

defaultColDef属性---默认列配置，若启用其中的某项列定义所有展示列都起作用，若想控制某列不启用，需要在columnDefs中单独定义

javascript 复制代码

  defaultColDef: { 
       resizable: true,//是否可以调整列大小，就是拖动改变列大小
       filter: true,  //所有列开启刷选器
       floatingFilter: true, // 直接显示刷选器
       editable: true, //单元表格是否可编辑
 },

四、列配置常用属性

ag-gird的列有如下常用属性：

名称	说明
headerName	显示的列名称，和数据没有关系显示给用户看的
field	字段，headerName对于的数据字段，如上面代码"姓名"列对应的数据字段是name
pinned	列固定（冻结列）的位置，，支持left right,把列固定在左边或者右边
valueFormatter	自定义过滤函数,比如数据库status字段存储了0或1数字，想前端网页把 0 显示为正常 1显示为删除，即可使用该属性 function nameFormatter(item) { if(item.value0) return "正常"; if(item.value1) return "删除"; return "itxst"; }
filter （如下图0001）	过滤器刷选器，定义了过滤器后用户就可以在列头部的输入框对数据进行刷选查找默认提供了以下几种过滤器 agNumberColumnFilter 数字过滤器 agTextColumnFilter 文本过滤器 agDateColumnFilter 日期过滤器
width, minWidth, maxWidth	width, minWidth, maxWidth设置任意一个属性来控制列的宽度，设置了最大宽度时，当拖动到设置宽度时拖动不能在进行，minWidth同理
hide	true隐藏 false显示
sort	前端排序方式 asc 顺序 desc倒序。默认asc
sortable	设置true 用户点击列的表头可以进行排序。默认true
resizable	true可以拖动改变列的大小，false不允许用户拖动改变列大小。默认true
valueGetter	值格式化 function(params){}

五、valueFormatter和 valueGetter区别

valueFormatter 和 valueGetter 是两个用于自定义单元格内容的重要属性，但它们的用途和实现方式有本质区别：

核心区别

属性	用途	执行时机	返回值类型	常见场景
`valueGetter`	计算或获取单元格的值（数据来源）	数据加载 / 刷新时	任意原始数据类型	动态计算值、跨字段组合
`valueFormatter`	格式化单元格的显示文本（视觉呈现）	单元格渲染时	字符串	日期格式化、货币符号、百分比

详细对比

1. `valueGetter` 的用法

功能：从数据源或其他计算中获取单元格的值。

示例

javascript 复制代码

 {
     field: 'fullName',
     valueGetter: (params) => {
         // 组合 firstName 和 lastName 字段
         return `${params.data.firstName} ${params.data.lastName}`;
     }
 }

参数：
复制代码
```
 params
```
对象包含：
- params.data：整行数据
- params.getValue('field')：获取其他字段值
- params.node：行节点信息

2. `valueFormatter` 的用法

功能：将已有的值格式化为特定的显示文本。

示例：

javascript 复制代码

 {
     field: 'price',
     valueFormatter: (params) => {
         // 格式化货币（添加美元符号）
         return `$${params.value.toFixed(2)}`;
     }
 }

参数：
复制代码
```
 params
```
对象包含：
- params.value：当前单元格的值
- params.data：整行数据

典型应用场景

场景 1：计算年龄（`valueGetter`）

javascript

javascript 复制代码

 {
     field: 'age',
     valueGetter: (params) => {
         const birthDate = new Date(params.data.birthDate);
         const today = new Date();
         return today.getFullYear() - birthDate.getFullYear();
     }
 }

场景 2：格式化日期（`valueFormatter`）

javascript

javascript 复制代码

{
     field: 'createDate',
     valueFormatter: (params) => {
         const date = new Date(params.value);
         return date.toLocaleDateString('zh-CN'); // 转为中文日期格式
     }
 }

场景 3：组合使用

javascript

javascript 复制代码

 {
     field: 'totalPrice',
     valueGetter: (params) => params.data.price * params.data.quantity, // 计算总价
     valueFormatter: (params) => `¥${params.value.toFixed(2)}` // 格式化为人民币
 }

性能考虑

valueGetter：每次数据刷新时都会执行，避免复杂计算。
valueFormatter：仅在渲染时执行，适合格式化操作。

总结

用 valueGetter 生成值：当需要从多个数据源计算或组合值时使用。
用 valueFormatter 美化显示：当需要将已有值转换为特定格式的字符串时使用。

两者结合可以实现强大的单元格内容定制，例如先通过 valueGetter 计算折扣价格，再用 valueFormatter 添加货币符号和折扣标记。

六、启用复选框

1.V32.2+之前的版本用法

columnDefs中配置列属性，

rowSelection设置为'multiple'，若不设置则无法多选，且表头不会渲染全选的复选框

代码示例:

javascript 复制代码

 {
   headerName: '',//选择列头部显示的文字，可以为空
   checkboxSelection: true,//设置为ture显示为复选框
   headerCheckboxSelection: true, //表头是否也显示复选框，全选反选用
   // pinned: 'left', //固定再左边
   filter: false,
   sortable: false,
   width: 40 //列的宽度
 },
 rowSelection: 'multiple', // 多选模式 single
 rowMultiSelectWithClick: false, // 单击行选中

2.V32.2+之后的版本用法

不在列定义内设置是否启用复选框，rowSelection由字符串类型改为对象

javascript 复制代码

const gridOptions = {
         // v32.2+由字符串类型改为对象，可在对象中设置相应的属性
    rowSelection: {
         mode: "multiRow", // 可选 "singleRow" 或 "multiRow" 模式
         checkboxes: true, // v32.2+版本由checkboxSelection改为checkboxes 设置为ture显示为复选框
         // v32.2+版本由headerCheckboxSelection改为headerCheckbox，表头是否也显示复选框，全选反选用
         headerCheckbox: true, 
         // v32.2+版本由rowMultiSelectWithClick改为enableSelectionWithoutKeys   是否启用键盘修饰键选择
         enableSelectionWithoutKeys: true, 
         // v32.2+版本由suppressRowClickSelection改为enableClickSelection  是否允许单击行选中 同jqGrid的multiboxonly
         enableClickSelection: false, 
    },
 };

enableSelectionWithoutKeys是一个用于控制行选择行为的配置选项。它允许用户在不使用键盘修饰键（如 Ctrl、Shift）的情况下进行多行选择，使选择体验更接近传统表格或列表的操作方式。单选模式无效

配置	操作方式
默认（未启用）	1. 点击一行：单选 2. 按住 Ctrl/Command 点击：多选（累加选择）
`enableSelectionWithoutKeys: true`	1. 点击一行：单选 2. 直接点击其他行：多选（自动累加，无需按键）

两个版本的用法再高版本中做了兼容，但是当使用的是V32.2+的版本时，会在控制台给出警告，建议使用高版本的推荐用法。