ModaGrid — 数据网格

无头数据网格 — 虚拟滚动·透视·树·Excel导出。

在 React·Vue·Svelte·原生 JS 中行为一致的无头数据网格库。

排序、过滤、搜索、分页、编辑等全部数据逻辑放在纯 TypeScript 核心(GridCore),各框架适配器只是轻量渲染层。框架不同行为也一致。

其他网格收费(Enterprise)的功能——Set 过滤器、分组+聚合、剪贴板、范围选择——以 MIT 免费使用。

免费 (MIT)React · Vue 3 · Vue 2.7 · Svelte 5 · Vanilla无头核心TypeScript

实时演示

使用从 CDN 加载的真实核心运行。可试用排序·多重排序·运算符/Set 过滤·搜索·分页·虚拟滚动·单元格/范围/行选择·内联编辑·Undo/Redo·剪贴板·列宽调整/重排/固定/隐藏·行分组与聚合·固定行·合计·状态保存/恢复·行拖拽·行状态跟踪(I/U/D 标记·差异保存),树形数据与服务端无限滚动也可切换。网格下方实时显示可复现当前设置与 API 调用的代码。

双击或输入字符编辑 · 拖拽选区 · ⌘/Ctrl+C·V 复制粘贴 · ⌘/Ctrl+Z·Y 撤销重做 · 方向键/Shift+方向键移动与扩展 · ⠿手柄拖拽行 · 表头右缘调宽 · 拖拽表头调序

正在从 CDN 加载 moda-grid 核心…

各环境包

使用环境包备注
React@moda-grid/reactDataGrid组件 + useGridCore钩, renderCell/renderEditor扩展
Vue 3@moda-grid/vueuseGrid + DataGrid, 列级自定义单元格·编辑器插槽
Vue 2.7@moda-grid/vue2与Vue 3相同Composition API
Svelte 5@moda-grid/svelte基于runes的createGridStore + DataGrid
纯JS / CDNmoda-grid.js无需构建,一行<script>,window.ModaGrid
无框架@moda-grid/core直接使用无头GridCore

npm 安装

npm i @moda-grid/react # React
npm i @moda-grid/vue # Vue 3
npm i @moda-grid/vue2 # Vue 2.7
npm i @moda-grid/svelte # Svelte 5
npm i @moda-grid/core # 仅无头核心

CDN 直接使用

https://grid.modaolive.com/moda-grid.js
https://grid.modaolive.com/style.css

三步开始

  1. 1

    安装包

    安装适配器如 npm i @moda-grid/react,或用一行 CDN <script> 加载核心。

  2. 2

    列 + 数据

    columns 只写 field·header 即可运行。filterable·cellEditor 等按需添加。

  3. 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: [...] })
全局搜索连接外部 inputsetSearch(text)
分页GridOptions.pageSizesetPage(pageIndex, pageSize?)

选择·编辑

功能启用方式 (选项/prop/输入)核心API
单元格选择模式selectionMode: "single-cell"|"multi-cell"|"row"setSelectionMode(mode)
范围跟踪选择selectionMode="multi-cell" + rangeTracking: "identity"排序·筛选后仍按标识跟踪单元格范围
活动单元格·范围点击 / 拖动 / 方向键·Shift+方向键setActiveCell(r,c) / setCellRange / navigateCell
行选择 + 复选框rowCheckboxes proptoggleRowSelection(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·VgetSelectionTsv() / 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.columnGroupssnapshot.headerGroups
重置布局—resetColumnLayout()
行拖放ColumnDef.rowDrag: truebegin/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-darkcellClass / rowClass 条件类

大数据·层级·导出

功能启用方式 (选项/prop/输入)核心API
虚拟滚动适配器: height+rowHeightvirtualScroll + handleScroll(scrollTop)
行分组 + 聚合—setGroupBy(["dept"]) + ColumnDef.aggregationFn
透视表pivot prop — 维度+度量setPivot({ rows, columns?, values: [{field, agg}] }) / isPivot()
树形数据treeData proptreeData: { childrenKey } 或 { getParentId }
服务端无限滚动serverSide propserverSide: { 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导出。

data grid

相关工具