ModaGrid — 数据网格
无头数据网格 — 虚拟滚动·透视·树·Excel导出。
在 React·Vue·Svelte·原生 JS 中行为一致的无头数据网格库。
排序、过滤、搜索、分页、编辑等全部数据逻辑放在纯 TypeScript 核心(GridCore),各框架适配器只是轻量渲染层。框架不同行为也一致。
其他网格收费(Enterprise)的功能——Set 过滤器、分组+聚合、剪贴板、范围选择——以 MIT 免费使用。
实时演示
使用从 CDN 加载的真实核心运行。可试用排序·多重排序·运算符/Set 过滤·搜索·分页·虚拟滚动·单元格/范围/行选择·内联编辑·Undo/Redo·剪贴板·列宽调整/重排/固定/隐藏·行分组与聚合·固定行·合计·状态保存/恢复·行拖拽·行状态跟踪(I/U/D 标记·差异保存),树形数据与服务端无限滚动也可切换。网格下方实时显示可复现当前设置与 API 调用的代码。
双击或输入字符编辑 · 拖拽选区 · ⌘/Ctrl+C·V 复制粘贴 · ⌘/Ctrl+Z·Y 撤销重做 · 方向键/Shift+方向键移动与扩展 · ⠿手柄拖拽行 · 表头右缘调宽 · 拖拽表头调序
各环境包
| 使用环境 | 包 | 备注 |
|---|---|---|
| React | @moda-grid/react | DataGrid组件 + useGridCore钩, renderCell/renderEditor扩展 |
| Vue 3 | @moda-grid/vue | useGrid + DataGrid, 列级自定义单元格·编辑器插槽 |
| Vue 2.7 | @moda-grid/vue2 | 与Vue 3相同Composition API |
| Svelte 5 | @moda-grid/svelte | 基于runes的createGridStore + DataGrid |
| 纯JS / CDN | moda-grid.js | 无需构建,一行<script>,window.ModaGrid |
| 无框架 | @moda-grid/core | 直接使用无头GridCore |
npm 安装
npm i @moda-grid/react # Reactnpm i @moda-grid/vue # Vue 3npm i @moda-grid/vue2 # Vue 2.7npm i @moda-grid/svelte # Svelte 5npm i @moda-grid/core # 仅无头核心CDN 直接使用
https://grid.modaolive.com/moda-grid.jshttps://grid.modaolive.com/style.css三步开始
- 1
安装包
安装适配器如 npm i @moda-grid/react,或用一行 CDN <script> 加载核心。
- 2
列 + 数据
columns 只写 field·header 即可运行。filterable·cellEditor 等按需添加。
- 3
渲染
适配器只需一个 <DataGrid>。直接用核心时用 subscribe + getSnapshot 连接。
// npm i @moda-grid/react
import { DataGrid, useGridCore } from "@moda-grid/react";
import "@moda-grid/react/styles.css";
const columns = [
{ field: "id", header: "ID", width: 60 },
{ field: "name", header: "姓名", filterable: true },
{ field: "role", header: "角色",
renderCell: (value) => <span className={`badge role-${value}`}>{value}</span> },
];
function App() {
const { grid, snapshot } = useGridCore({ columns, data: users });
return (
<>
<input onChange={(e) => grid.setSearch(e.target.value)} />
<button onClick={() => grid.exportToCsv({ filename: "users.csv" })}>
CSV导出
</button>
<DataGrid grid={grid} columns={columns}
height={480} rowHeight={37}
selectionMode="multi-cell" columnController />
</>
);
}所有变更在内部重新计算快照并通知订阅者。快照经过记忆化,可直接用于 React useSyncExternalStore。
按功能使用 — 该用什么
适配器大多用一行 prop·选项开启,只用核心时直接调 API。
查询·浏览
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 排序 | 默认开启 — 点击表头 | toggleSort(field) / setSort(field, "asc") |
| 多重排序 | Shift + 点击表头 | toggleSort(field, true) |
| 列筛选 | ColumnDef.filterable: true + filterType: "text"|"number"|"date" | setFilter(field, { operator, value, valueTo? }) |
| Set 筛选 (Excel 式) | filterType: "set" | setFilter(field, { operator: "set", values: [...] }) |
| 全局搜索 | 连接外部 input | setSearch(text) |
| 分页 | GridOptions.pageSize | setPage(pageIndex, pageSize?) |
选择·编辑
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 单元格选择模式 | selectionMode: "single-cell"|"multi-cell"|"row" | setSelectionMode(mode) |
| 范围跟踪选择 | selectionMode="multi-cell" + rangeTracking: "identity" | 排序·筛选后仍按标识跟踪单元格范围 |
| 活动单元格·范围 | 点击 / 拖动 / 方向键·Shift+方向键 | setActiveCell(r,c) / setCellRange / navigateCell |
| 行选择 + 复选框 | rowCheckboxes prop | toggleRowSelection(id) / toggleAllRows() |
| 内联编辑 | editable + cellEditor: "text"|"number"|"select"|"date"|"custom" | startEditing / updateEditValue / commitEditing / cancelEditing |
| 输入校验 | ColumnDef.validate(value, row) | 失败时 snapshot.editError |
| 撤销·重做 | 自动记录 (undoLimit 默认 100) | undo() / redo() / canUndo() |
| 复制·粘贴 (TSV) | 适配器自动处理 ⌘/Ctrl+C·V | getSelectionTsv() / pasteTsv(tsv) |
| 选中聚合状态栏 | statusBar prop (默认开启) | snapshot.selectionAggregates |
| 查找·替换 | — | findCells / findNext / replaceAll(find, repl) |
| 单元格·表头右键菜单 | contextMenu / headerContextMenu 选项 (预设: defaultContextMenuItems) | openContextMenu / runContextMenuItem / snapshot.contextMenu |
行状态跟踪 (I/U/D)
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 添加行 | — | addRows(rows) / importCsv(csv) → 标记 I |
| 修改跟踪 | 编辑·pasteTsv 时自动标记 | → U 状态 (I 行修改后仍为 I) |
| 删除标记·恢复 | — | deleteRowsByIds(ids) → D / restoreRowsByIds(ids) |
| 状态列显示 | rowStatus prop — 最左侧状态列 | snapshot.rowStates + mg-row-I/U/D CSS 类 |
| 变更保存·取消 | — | validateChanges() → getChanges() → commitChanges() / clearChanges() |
列·行·渲染
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 列宽调整 | resizable (默认开) — 拖表头边缘 | setColumnWidth(field, px) |
| 自动宽度 | 双击边缘 | autoSizeColumn / autoSizeAllColumns |
| 列重排 | reorderable (默认开) — 拖表头 | reorderColumn(from, to) |
| 列固定 | ColumnDef.pinned: "left"|"right" | setColumnPinned(field, pinned) |
| 列显示·隐藏 | columnController prop (列 ▾ 弹层) | setColumnVisible / setAllColumnsVisible |
| 多级分组表头 | ColumnDef.group + GridOptions.columnGroups | snapshot.headerGroups |
| 重置布局 | — | resetColumnLayout() |
| 行拖放 | ColumnDef.rowDrag: true | begin/update/endRowDrag · moveRow |
| 可变高度滚动锚定 | 自动 | 高度变化的行也保持滚动位置 |
| 编辑会话保护 | 自动 | 排序·筛选·重渲染时保持编辑 |
| 固定行 | pinnedTopRows / pinnedBottomRows 选项 | setPinnedTopRows / setPinnedBottomRows |
| 总合计 (tfoot) | ColumnDef.aggregationFn: "sum"|"avg"|"min"|"max"|"count" | snapshot.grandTotals |
| 单元格合并 | ColumnDef.merge: "row"|"col"|"both" | getCellSpan(row, col) → { rowSpan, colSpan, hidden } |
| 状态保存·还原 | — | getState() / applyState(saved) |
| 主题 | --grid-*变量 / .grid-theme-dark | cellClass / rowClass 条件类 |
大数据·层级·导出
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 虚拟滚动 | 适配器: height+rowHeight | virtualScroll + handleScroll(scrollTop) |
| 行分组 + 聚合 | — | setGroupBy(["dept"]) + ColumnDef.aggregationFn |
| 透视表 | pivot prop — 维度+度量 | setPivot({ rows, columns?, values: [{field, agg}] }) / isPivot() |
| 树形数据 | treeData prop | treeData: { childrenKey } 或 { getParentId } |
| 服务端无限滚动 | serverSide prop | serverSide: { dataSource, cacheBlockSize } / refreshServerRows |
| CSV导出 | — | exportToCsv({ filename, visibleColumnsOnly, selectedRowsOnly }) |
| Excel·PDF导出 | — | exportToXlsx({ filename, styled }) / exportToPdf / print() |
常用配方
可直接复制使用的代码片段。
Set筛选 (清单)
列唯一值按清单筛选 — 同Excel UX
// 在列上指定 filterType
{ field: "role", header: t.roleL, filterable: true, filterType: "set" }
grid.getUniqueValues("role"); // ["admin","editor","viewer","guest"]
grid.setFilter("role", { operator: "set", values: ["admin","editor"] });
grid.setFilter("role", null); // 全选 = 清除筛选CSV导出
按当前显示状态(筛选·排序·展开)导出。UTF-8 BOM,Excel不乱码
grid.exportToCsv({
filename: "users.csv",
visibleColumnsOnly: true, // 排除隐藏列 (默认)
selectedRowsOnly: false, // true 时仅导出选中行
});仅变更存服务器 (I/U/D)
标记增·改·删只发变更。rowStatus prop显示状态列
// I = addRows/importCsv · U = 编辑/pasteTsv · D = deleteRowsByIds (I 行立即移除)
grid.addRows([{ id: "new-1", name: t.newEmp }]);
grid.deleteRowsByIds(["3", "7"]); // 标记 D — 提交前保留在界面
grid.restoreRowsByIds(["3"]); // 取消 D 标记
async function save() {
const errors = grid.validateChanges(); // 校验 I/U 行 required/validate
if (errors.length) return console.warn(errors);
await fetch("/api/users", {
method: "POST",
body: JSON.stringify(grid.getChanges()), // { inserted, updated, deleted }
});
grid.commitChanges(); // 删除 D + 清除标记
}
// 仅取消标记(恢复显示)用 grid.clearChanges()状态保存·还原
排序·筛选·搜索·分页·分组·列布局存localStorage
// 保存 — 返回可序列化对象
localStorage.setItem("grid", JSON.stringify(grid.getState()));
// 还原 — 忽略不存在的列,对结构变更安全
grid.applyState(JSON.parse(localStorage.getItem("grid")!));
// 也支持部分应用
grid.applyState({ sortState: saved.sortState });服务端无限滚动
视口触达未载块时getRows自动调用。排序·筛选作服务端参数
const grid = new GridCore({
columns,
data: [], // 服务端模式下忽略
serverSide: {
cacheBlockSize: 50,
dataSource: {
async getRows({ startRow, endRow, sortModel, filterModel }) {
const res = await fetch(`/api/rows?start=${startRow}&end=${endRow}`);
return res.json(); // { rows, lastRowIndex? }
},
},
},
virtualScroll: { rowHeight: 37, viewportHeight: 480 },
});
grid.refreshServerRows(); // 清除缓存 + 重新请求树形数据
父子层级展开/折叠树。支持两种数据形态
// nested — 行内含子数组
new GridCore({ columns, data, treeData: { childrenKey: "children" } });
// flat — 用 parentId 连接 (父级被过滤的行升为根)
new GridCore({ columns, data,
getRowId: (r) => r.id,
treeData: { getParentId: (r) => r.parentId },
});
grid.toggleTreeExpanded(rowId); // 展开/折叠自定义单元格·编辑器 (React)
ColumnDef扩展给列直接指定JSX渲染器与编辑器
{
field: "role",
header: t.roleL,
renderCell: (value) => <span className={`badge role-${value}`}>{value}</span>,
renderEditor: (ctx) => (
<select value={ctx.value} onChange={(e) => ctx.setValue(e.target.value)} />
),
}
// Vue 用 #cell-{field} / #editor-{field} 插槽,Svelte 用 cell/editor snippet分组 + 聚合
按字段分组,aggregationFn列合计·平均显示在分组行
{ field: "age", aggregationFn: "avg" } // 指定聚合对象
grid.setGroupBy(["dept", "role"]); // 多级分组
grid.expandAllGroups(); // 全部展开
grid.collapseAllGroups(); // 全部折叠
// snapshot.grandTotals 自动计算总合计单元格格式·自定义值
显示转换与值提取为列选项
{
field: "salary",
header: t.salaryH,
valueGetter: (row) => row.pay.annual, // 提取嵌套值
formatter: (v) => `${Number(v).toLocaleString()}韩元`, // 显示转换
cellClass: (p) => (p.value > 5000 ? "text-red-500" : ""), // 条件类
}商用表格收费,moda-grid 免费
Set 过滤·分组·聚合·剪贴板·范围选择·透视等功能在 AG Grid 中仅限 Enterprise(付费)。moda-grid 以 MIT 许可全部免费。
源码·文档
github.com/park-taejoon/moda-grid-releases- 开始·平台指南(React/Vue 3/Vue 2.7/Svelte/Vanilla)
- 功能指南 — 排序·筛选·编辑·虚拟滚动·服务端等
- GridCore无头API参考
使用方法
无头数据网格 — 虚拟滚动·透视·树·Excel导出。