zan-grid

面向 Vue 3 的企业级前端表格组件。

功能特性

• 纯前端行模型（不依赖服务端数据源）
• 排序 + 类型化列筛选（文本/数字/日期）+ 快速筛选
• 列拖拽重排 + setColumnOrder() API
• 真正的固定列（左/右粘性渲染）
• 列宽拖拽调整（表头边缘）+ setColumnWidth() API
• 海量数据虚拟行 + 虚拟列渲染
• 分页 + 行选择
• 单元格编辑（内置编辑器或自定义 cellEditor）
• 通过 cellRenderer 自定义单元格渲染
• 撤销/重做（Ctrl/Cmd+Z、Ctrl/Cmd+Y、Ctrl/Cmd+Shift+Z）
• 批量编辑会话（提交/回滚）
• 公式计算（支持 [field] 引用的简易表达式语法）
• CSV / Excel 导出
• 网格 API：setRows/getRows/updateRow/removeRow/addRow 等

批量编辑 API

• startBatchEdit()
• stopBatchEdit(commit?: boolean)
• commitBatchEdit()
• rollbackBatchEdit()
• getBatchEditChanges()

编辑历史 API

• undoLastEdit()
• redoLastEdit()

说明：同一行内的多字段更新会被视作一次撤销/重做操作。

列顺序 API

• setColumnOrder(orderedFields: string[])
• setColumnWidth(field: string, width: number)

使用方式

import { Grid } from 'zan-grid'
import 'zan-grid/style'

筛选模型

setFilterModel() / filterChange 使用 { field, type, value } 数组。

// 文本包含
{ field: 'name', type: 'text', value: 'alice' }

// 集合包含（精确匹配）
{ field: 'country', type: 'set', value: ['CN', 'US'] }

// 数字/日期运算符
{ field: 'score', type: 'number', value: { operator: 'eq', value: 88 } }
{ field: 'score', type: 'number', value: { operator: 'gt', value: 88 } }
{ field: 'score', type: 'number', value: { operator: 'lt', value: 88 } }
{ field: 'score', type: 'number', value: { operator: 'between', from: 80, to: 95 } }

{ field: 'createdAt', type: 'date', value: { operator: 'eq', value: '2026-01-10' } }
{ field: 'createdAt', type: 'date', value: { operator: 'gt', value: '2026-01-10' } }
{ field: 'createdAt', type: 'date', value: { operator: 'lt', value: '2026-01-10' } }
{ field: 'createdAt', type: 'date', value: { operator: 'between', from: '2026-01-01', to: '2026-01-31' } }

说明：

• between 为闭区间（from <= value <= to）。
• 日期比较使用标准化 YYYY-MM-DD 键值。
• 为兼容旧版，仍支持历史结构（number: value: 40、{ min, max }；date: value: 'YYYY-MM-DD'、{ from, to }）。
• 在表头集合筛选（Set Filter，服务端模式）中，已加载/全量 来源切换只影响候选值生成，不影响筛选值格式。

服务端去重值（可选）

在服务端行模型中，集合筛选（Set Filter）的 全量 来源可使用数据源级去重 API：

const datasource = {
  async getRows(params) {
    // ...
  },
  async getSetFilterValues({ field, filterModel, quickFilterText }) {
    // 返回：
    // - string / number / null 值，或
    // - { value, count } 对象
    return [
      { value: 'CN', count: 1200 },
      { value: 'US', count: 980 }
    ]
  }
}

说明：

• 组件在调用 getSetFilterValues 前会移除当前字段自身的 set 条件，避免自筛选死锁。
• 若未实现 getSetFilterValues，全量 会回退为基于当前已加载块计算。
• 侧边栏 数字/日期 筛选支持 = / > / < / between，与表头菜单一致。

开发命令

• npm run dev
• npm run test
• npm run build
• npm run acceptance:smoke