rj-grid 0.2.1 → 0.2.3

package/README.md

@@ -1,98 +1,328 @@
-# rj-grid
-
-自研**零第三方依赖**的企业级数据网格（Vue 3 + TypeScript），功能规格对标 AG Grid：虚拟滚动、冻结列、行/列拖拽、分组透视、树形、编辑与撤销、公式引擎、SSRM 服务端行模型、主题与 i18n、打印/CSV/Excel 导出、离线自然语言查询（NLQ）。gzip 约 93 KB（不含 vue / echarts）。
-
-本仓库是该组件的**独立维护仓**：源码、单测、构建链、演示 playground、使用手册都在这里；产物已发布到**公共 npm（包名 `rj-grid`）**，宿主项目（如 join-cloud-vue3）按版本号安装，不参与组件开发。
-
-## 仓库布局
-
-| 路径 | 作用 |
-|---|---|
-| `index.ts` | 包入口（值导出 `RjGrid` + NLQ / 查询条件内核 + 全部公共类型） |
-| `src/` | 组件与引擎源码（`src/types.ts` 是类型权威） |
-| `__tests__/` | 346 个单测用例，入口 `__tests__/run.ts` |
-| `build/rjDistCheck.mjs` | 产物体检五守卫（构建末尾自动跑） |
-| `build/rjSizeReport.mjs` | 体积报告 |
-| `vite.lib.config.ts` | 库构建：ESM 单文件 + 单 `style.css`，external `vue`/`echarts`，不出 sourcemap |
-| `vite.playground.config.ts` | 演示页 dev/build，`rj-grid` 别名指本地 `index.ts` |
-| `playground/` | 8 标签演示页（独立起服，不依赖宿主） |
-| `docs/RjGrid使用手册.md` | 完整使用手册（能力、API、坑与边界） |
-| `dist/` | 发布产物，**随库入库**（见「发布纪律」） |
-
-## 快速上手（维护者）
-
-```powershell
-pnpm install
-
-pnpm test      # 单测 346 passed
-pnpm ts        # vue-tsc --noEmit（自有 tsconfig，无宿主基线噪声）
-pnpm lint      # eslint + stylelint
-pnpm build     # vite lib → vue-tsc 产 d.ts → 产物体检五守卫
-pnpm size      # 体积报告（可选）
-
-pnpm dev       # playground 演示页（默认 :5173，alias 走本地源码）
-```
-
-发布新版本：改完源码 → `npm version patch|minor|major`（自动 bump + commit + tag）→ `git push --follow-tags` → `npm publish`（`prepublishOnly` 会自动 `pnpm build && pnpm test`，杜绝发出旧 dist）。
-
-## 宿主接入（npm 版本号）
-
-```jsonc
-// 宿主 package.json —— 从公共 npm 按语义化版本安装
-"dependencies": {
-  "rj-grid": "^0.1.0"
-}
-```
-
-```powershell
-pnpm add rj-grid           # 或 npm i rj-grid
-```
-
-> 仍保留 git URL 方式（离线内网 / 需锁 commit 时）：`"rj-grid": "git+https://gitee.com/rjding/rj-grid.git#v0.1.0"`。
-
-从 npm 安装时目录名规范（`node_modules/rj-grid`），样式可**直接**引：`import 'rj-grid/style.css'`。仅当走 git URL 时才需下面的 CSS 垫片——pnpm 会把 git 依赖装进带 `#<commit>` 的目录名，vite 输出的资源 URL 含裸 `#`，浏览器把 `#` 之后当片段丢掉 → dev 下 404：
-
-```css
-/* 宿主 src/styles/rjgrid/index.css */
-@import 'rj-grid/style.css';
-```
-
-```ts
-// 宿主 src/main.ts
-import '@/styles/rjgrid/index.css'
-```
-
-组件侧必须是**值导入**（`RjGrid` 不走宿主的自动组件注册，只写 type 导入会在运行期报 `Failed to resolve component: rj-grid`）：
-
-```ts
-import { RjGrid } from 'rj-grid'
-```
-
-peer 依赖：`vue ^3.4.0` 必装；`echarts >=5.0.0` 可选（仅「集成图表」用到，包内 `await import('echarts')` 动态加载）。注意宿主没装 echarts 时 `vite build` 会因 rollup 解析不到该动态 import 而失败——要么装上，要么宿主加 `build.rollupOptions.external: ['echarts']`；组件自身有降级，图表对话框会显示一行提示而非崩页。
-
-## 升级与回滚
-
-```powershell
-pnpm update rj-grid          # 在 ^0.1.0 范围内升到最新
-pnpm add rj-grid@latest      # 跨范围拉最新
-```
-
-npm 安装的 lockfile 记录精确版本与 `integrity`，CI / 他人 `pnpm install --frozen-lockfile` 可复现。回滚只需把版本钉回旧号（如 `"rj-grid": "0.1.0"`）。本地联调可临时用 `"link:../rjGrid"`，调完换回版本号并重装。
-
-## 为什么 dist 入库
-
-发布走 `prepublishOnly`（`pnpm build && pnpm test`）：`npm publish` 打的是**构建后磁盘上的 `dist/`**（按 `files` 字段 `["dist","README.md"]` 裁剪），所以公共 npm 消费方无需依赖仓库里的 dist。dist 仍入库只是为了兼容 **git URL 安装**那条路径（git 依赖不会在宿主机跑 `prepare` 重建）；保留 dist 入库能同时喂饱两条路。
-
-`build/rjDistCheck.mjs` 的五道守卫同时在把关：外部 import 只允许 `vue`/`echarts`；CSS 不引宿主资源；d.ts 不断链；dist 不得混入 `.vue/.ts/.scss` 源码；**不得带 sourcemap**——vite 的 `.map` 内嵌 `sourcesContent`（原始源码），一发包等于源码同步外流，因此 `vite.lib.config.ts` 里 `sourcemap: false` 是源码保护而非可选项。
-
-## 私有仓注意
-
-已发布到**公共 npm**，按版本号安装无需任何 git 凭据。仅当某宿主仍走 git URL 且仓库为 gitee 私有仓时，安装机才需具备克隆凭据（HTTPS 走 credential manager 里的 gitee 账号或部署密钥），CI 需预置，否则会卡在 git 认证。
-
-## 文档
-
-完整能力、API 与已知边界见 [docs/RjGrid使用手册.md](docs/RjGrid使用手册.md)；`playground` 的 8 个标签既是能力地图也是回归入口。
-
-## 赞助
-码农不易，^V^
-![小小支援，大大的爱](docs/88888.png)
+<p align="center">
+  <img src="docs/images/01-overview.png" alt="rj-grid 综合功能总览" width="100%" />
+</p>
+
+<h1 align="center">rj-grid</h1>
+
+<p align="center">
+  <b>零第三方依赖的企业级 Vue 3 数据网格 —— 对标 AG Grid 的全功能，MIT 免费、gzip 约 93 KB。</b><br/>
+  虚拟滚动 · 冻结列 · 分组透视 · 树形 · 编辑撤销 · 公式引擎 · SSRM 服务端行模型 · 主题 & i18n · 打印/CSV/Excel/PDF · 离线自然语言查询（NLQ）
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/rj-grid"><img src="https://img.shields.io/npm/v/rj-grid.svg?logo=npm&color=cb3837" alt="npm version"/></a>
+  <a href="https://github.com/rjding/rjGrid"><img src="https://img.shields.io/github/stars/rjding/rjGrid?logo=github&color=181717" alt="GitHub stars"/></a>
+  <a href="https://gitee.com/rjding/rj-grid"><img src="https://img.shields.io/badge/Gitee-rj--grid-orange?logo=gitee&logoColor=white" alt="Gitee mirror"/></a>
+  <a href="https://github.com/rjding/rjGrid/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License MIT"/></a>
+  <a href="https://gitee.com/rjding/rj-grid"><img src="https://img.shields.io/badge/third--party%20deps-0-blue.svg" alt="Zero dependencies"/></a>
+  <img src="https://img.shields.io/badge/gzip-~93KB-lightgrey.svg" alt="Bundle size"/>
+  <a href="https://vuejs.org/"><img src="https://img.shields.io/badge/vue-3.x-brightgreen.svg?logo=vuedotjs" alt="Vue 3"/></a>
+  <img src="https://img.shields.io/badge/tests-346%20passed-yellowgreen.svg" alt="Tests"/>
+  <img src="https://img.shields.io/badge/types-TypeScript-blue.svg?logo=typescript" alt="TypeScript"/>
+</p>
+
+<p align="center">
+  <a href="#-快速开始">快速开始</a> ·
+  <a href="#-能力演示">能力演示</a> ·
+  <a href="#-与-ag-grid-对比">与 AG Grid 对比</a> ·
+  <a href="docs/RjGrid使用手册.md">完整手册</a> ·
+  <a href="https://github.com/rjding/rjGrid">GitHub</a> ·
+  <a href="https://gitee.com/rjding/rj-grid">Gitee</a> ·
+  <a href="README_EN.md">English</a>
+</p>
+
+---
+
+## 💡 为什么选 rj-grid
+
+想象一下：一个 `<rj-grid>` 标签，就能替换掉你项目里那些「几万行就卡死、想加个分组又得换库」的表格——而**不额外引入任何第三方依赖**，也不用给商业表格库交授权费。
+
+- **真·零依赖**：运行时只需 `vue`，连可选的图表都是按需 `import('echarts')`。不捆绑、不污染你的 lockfile。
+- **小得离谱**：gzip 约 93 KB，却装下了别人几个库加起来的功能量。
+- **10 万行丝滑**：行列双向虚拟滚动，实测 100,000 行 × 12 列秒开（生成仅约 12 ms）。
+- **对标 AG Grid 全功能**：树形 / 分组 / 透视 / SSRM / 公式 / 主题 / i18n / 导出 / NLQ 一应俱全。
+- **TypeScript 原生**：完整的类型推导与 `.d.ts`，编辑器全程提示，不是「先跑起来再说」的糙活。
+- **免费商用**：MIT 协议，个人和企业都能放心用。
+
+---
+
+## ✨ 特性一览
+
+| 分类 | 你会得到的能力 |
+|---|---|
+| 渲染 | 行列虚拟滚动（10 万行流畅）、冻结列、多级表头、密度三档、钉行、全宽行 |
+| 数据 | 客户端 / 分页 / 无限滚动 / **SSRM 服务端行模型**（按需块缓存）四种模式 |
+| 分组 | 树形任意深度、拖拽分组、多级分组 + 组页脚聚合、列透视（含高基数护栏） |
+| 编辑 | 8 类编辑器、校验、撤销/重做、批量事务回填、内置新增/编辑行弹窗 |
+| 公式 | 零依赖 Excel 风格公式：`=B2*C2`、`SUM/COUNTIF/SUMIF`、区域引用、循环引用检测 |
+| 筛选 | 列头漏斗 / 浮动筛选行 / 快速搜索 / 高级过滤（跨列 AND/OR 表达式树）四路叠加 |
+| 外观 | 主题引擎（4 预设 × 明暗 × 强调色 × 自定义 CSS 变量）、i18n（中/英 + 文案覆盖）、图标替换 |
+| 输出 | 打印 / CSV / Excel / PDF，支持选中行 / 当前视图 / 后端导出三种范围 |
+| AI | 纯离线确定性 **NLQ**，中英双语随 i18n 切换：中文用「数量大于50 按单价降序」、英文用 `qty > 50 sort by price desc`，回显随语言 |
+| 状态 | `stateKey` 自动持久化 + `getState/setState` 编程式存取，刷新不丢视图 |
+
+---
+
+## 🚀 快速开始
+
+> 三步，两分钟，跑起来。
+
+**① 安装**
+
+```bash
+npm install rj-grid
+# 或 pnpm add rj-grid / yarn add rj-grid
+```
+
+**② 引入组件与样式**
+
+```ts
+// main.ts —— 样式全局引一次即可
+import 'rj-grid/style.css'
+```
+
+**③ 直接使用**
+
+```vue
+<template>
+  <rj-grid :columns="cols" :rows="rows" row-key="id" :height="480" show-toolbar />
+</template>
+
+<script setup lang="ts">
+import { RjGrid } from 'rj-grid'        // ⚠️ 必须「值导入」，不能只写 type
+import type { RjColumn, RjRowData } from 'rj-grid'
+
+const cols: RjColumn[] = [
+  { field: 'name',  title: '名称', width: 160, filter: 'text' },
+  { field: 'qty',   title: '数量', type: 'num',   aggFunc: 'sum' },
+  { field: 'price', title: '单价', type: 'money', aggFunc: 'avg' }
+]
+const rows: RjRowData[] = [
+  { id: 1, name: '轴承', qty: 100, price: 12.5 },
+  { id: 2, name: '电机', qty: 30,  price: 480 }
+]
+</script>
+```
+
+`show-toolbar` 一开，冻结列、分组、筛选、导出、列显隐全部自带，无需再写一行代码。想解锁更多能力，加个属性即可 —— 每个特性的完整参数见 [📖 使用手册](docs/RjGrid使用手册.md)。
+
+---
+
+## 🎬 能力演示
+
+真实产品截图/动图，全部来自 `playground` 演示页：
+
+<table>
+  <tr>
+    <td width="50%">
+      <b>🎨 主题引擎 · 4 预设 × 明暗 × 多语言</b><br/>
+      <img src="docs/images/theme-cycle.gif" alt="主题切换动画" width="100%"/>
+    </td>
+    <td width="50%">
+      <b>🤖 离线自然语言查询（NLQ）</b><br/>
+      输入一句话，自动完成「筛选 + 排序 + 分组」。<br/>
+      <img src="docs/images/nlq-query.gif" alt="NLQ 查询动画" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <b>🌲 树形层级 · 一键展开 / 折叠</b><br/>
+      <img src="docs/images/tree-expand.gif" alt="树形展开折叠动画" width="100%"/>
+    </td>
+    <td>
+      <b>🔍 快速过滤 · 跨全列即时匹配高亮</b><br/>
+      <img src="docs/images/quick-filter.gif" alt="快速过滤动画" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <b>🧮 公式引擎 · Excel 风格零依赖</b><br/>
+      <img src="docs/images/15-formula.png" alt="公式列" width="100%"/>
+    </td>
+    <td>
+      <b>📦 内置行编辑 / 新增弹窗 · 由列定义自动生成表单</b><br/>
+      <img src="docs/images/08-row-form.png" alt="行弹窗" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <b>📊 分组聚合 + 组页脚</b><br/>
+      <img src="docs/images/12-group.png" alt="分组聚合" width="100%"/>
+    </td>
+    <td>
+      <b>⚡ 10 万行虚拟滚动 · 生成仅约 12 ms</b><br/>
+      <img src="docs/images/10-perf-100k.png" alt="大数据性能" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <b>↕️ 行拖动 · 拖手柄重排行序</b><br/>
+      <img src="docs/images/row-drag.gif" alt="行拖动动画" width="100%"/>
+    </td>
+    <td>
+      <b>⇄ 列拖动 · 列菜单「列」页签拖拽换序（列序实时改变）</b><br/>
+      <img src="docs/images/col-drag.gif" alt="列拖动动画" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td colspan="2">
+      <b>➕ 动态添加查询字段 · queryable 一行代码获得可配置查询栏</b><br/>
+      <img src="docs/images/query-field.gif" alt="动态查询字段动画" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%">
+      <b>🔎 服务端查询 + 分页 · 条件栏与页器同行</b><br/>
+      <img src="docs/images/13-server-pagination.png" alt="服务端查询分页" width="100%"/>
+    </td>
+    <td width="50%">
+      <b>☰ 密度三档 · 一屏看更多 / 宽松易读自由切</b><br/>
+      <img src="docs/images/21-density.png" alt="显示密度切换" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%">
+      <b>💾 保存视图 · 一键存当前查询/列布局/排序为快照</b><br/>
+      <img src="docs/images/save-view.gif" alt="保存视图动画" width="100%"/>
+    </td>
+    <td width="50%">
+      <b>▦ 工具面板 · 列显隐/分组/透视拖拽管理</b><br/>
+      <img src="docs/images/panel.gif" alt="工具面板动画" width="100%"/>
+    </td>
+  </tr>
+  <tr>
+    <td colspan="2">
+      <b>🖨 打印 / 导出 · 前端（选中行/当前视图）+ 后端导出三档可选</b><br/>
+      <img src="docs/images/print-export.gif" alt="打印导出范围动画" width="100%"/>
+    </td>
+  </tr>
+</table>
+
+---
+
+## 🔍 与 AG Grid 对比
+
+| 维度 | rj-grid | AG Grid |
+|---|---|---|
+| 授权 / 费用 | ✅ MIT 完全免费 | ⚠️ 企业级特性需商业授权 |
+| 第三方运行时依赖 | ✅ 仅 `vue` | ⚠️ 自带框架与模块体系 |
+| gzip 体积 | ✅ 约 93 KB | 显著更大 |
+| Vue 3 原生 | ✅ 值导入即用，非二次封装 | 提供 Vue 封装层 |
+| 离线自然语言查询 | ✅ 内置纯确定性 NLQ | ❌ 无 |
+| 虚拟滚动 / 分组 / 透视 / SSRM / 公式 / 主题 / 导出 | ✅ 全部内置 | ✅ 部分在付费版 |
+
+> rj-grid 的定位不是「山寨 AG Grid」，而是给 Vue 项目一个**免费、轻量、开箱即用**的高质量选择。
+
+---
+
+## 🧩 数据模式（按需选择）
+
+```vue
+<!-- 客户端：全量入 rows，排序/筛选/分组全在浏览器，虚拟滚动扛 10 万行 -->
+<rj-grid :columns="cols" :rows="rows" row-key="id" />
+
+<!-- 分页：后端分页，loadData 自动携带排序/筛选/页码，分页器位置由 pager-position 决定 -->
+<rj-grid :columns="cols" data-mode="pagination" :load-data="loadData" :page-size="20" />
+
+<!-- 无限滚动：滚动到底按块续取，无页码 -->
+<rj-grid :columns="cols" data-mode="infinite" :load-data="loadData" />
+
+<!-- SSRM 服务端行模型：分组/大数据块缓存，按需分块加载 -->
+<rj-grid :columns="cols" data-mode="serverSide" :load-data="loadData" server-side-grouping />
+```
+
+```ts
+import type { RjLoadServerParams } from 'rj-grid'
+// params 自动带 start/end/page/pageSize/sort/filters/quickFilterText/rowGroup…，平铺给后端即可
+async function loadData(p: RjLoadServerParams) {
+  const res = await api.queryPage(p)
+  return { rows: res.list, total: res.total, success: true }
+}
+```
+
+各模式的完整配置与回调签名见 [手册 §6 数据模式](docs/RjGrid使用手册.md)。
+
+---
+
+## 🛠 兼容性与技术栈
+
+- **框架**：Vue `^3.4.0`（唯一必装 peer 依赖）
+- **可选**：`echarts >= 5.0.0`（仅「集成图表」对话框用到，未安装时优雅降级不崩页）
+- **语言**：TypeScript 全量类型，`.d.ts` 随包发布
+- **样式**：单一 `rj-grid/style.css`，主题走 CSS 变量，可按需覆盖
+- **构建**：Vite 库模式 ESM 单文件，`sideEffects` 仅 CSS，Tree-shaking 友好
+
+---
+
+## 🖥 本地运行演示页
+
+演示页（`playground/`）独立起服、不依赖宿主项目，8 个标签就是能力地图：
+
+```bash
+git clone https://github.com/rjding/rjGrid.git   # 国内可用镜像：git clone https://gitee.com/rjding/rj-grid.git
+cd rjGrid
+pnpm install
+pnpm dev          # 默认 http://localhost:5173
+```
+
+> ① 综合功能 ② 大数据性能 ③ 树形/分组/透视 ④ 服务端模式 ⑤ SSRM 块缓存 ⑥ 公式引擎 ⑦ 主题 & 国际化 ⑧ AI 自然语言查询
+
+---
+
+<details>
+<summary><b>📚 维护者信息（仓库结构 / 开发命令 / 发布纪律）</b></summary>
+
+### 仓库布局
+
+| 路径 | 作用 |
+|---|---|
+| `index.ts` | 包入口（值导出 `RjGrid` + NLQ / 查询条件内核 + 全部公共类型） |
+| `src/` | 组件与引擎源码（`src/types.ts` 是类型权威） |
+| `__tests__/` | 346 个单测用例，入口 `__tests__/run.ts` |
+| `build/rjDistCheck.mjs` | 产物体检五守卫（构建末尾自动跑） |
+| `vite.lib.config.ts` | 库构建：ESM 单文件 + 单 `style.css`，external `vue`/`echarts`，不出 sourcemap |
+| `playground/` | 8 标签演示页 |
+| `docs/RjGrid使用手册.md` | 完整使用手册（能力、API、坑与边界） |
+| `dist/` | 发布产物，随库入库 |
+
+### 开发命令
+
+```bash
+pnpm test      # 单测 346 passed
+pnpm ts        # vue-tsc --noEmit
+pnpm lint      # eslint + stylelint
+pnpm build     # vite lib → vue-tsc 产 d.ts → 产物体检五守卫
+pnpm size      # 体积报告
+pnpm dev       # playground 演示页
+```
+
+### 发布新版本
+
+改完源码 → `npm version patch|minor|major`（自动 bump + commit + tag）→ `git push --follow-tags` → `npm publish`（`prepublishOnly` 会自动 `pnpm build && pnpm test`，杜绝发出旧 dist）。
+
+### 宿主接入补充
+
+- 从 npm 安装目录名规范（`node_modules/rj-grid`），样式可直接 `import 'rj-grid/style.css'`。
+- 组件侧必须**值导入** `import { RjGrid } from 'rj-grid'`，只写 type 导入会在运行期报 `Failed to resolve component: rj-grid`。
+- 走 git URL 时 pnpm 会把依赖装进带 `#<commit>` 的目录名，vite 资源 URL 含裸 `#` 会被当片段丢掉 → dev 下 404，此时用 CSS `@import` 垫片（详见手册 §15.4）。
+- `dist` 入库仅为兼容 git URL 安装路径；`sourcemap: false` 是源码保护而非可选项，产物五守卫同时在把关。
+
+</details>
+
+---
+
+## 🤝 贡献
+
+欢迎 Issue 与 PR：提 bug、要特性、补文档都行。改动请附带相应单测，保证 `pnpm test && pnpm ts && pnpm lint && pnpm build` 全绿。
+
+## 📄 许可证
+
+[MIT](LICENSE) — 个人与企业均可免费使用、修改与再分发。
+
+## ☕ 支持作者
+
+如果 rj-grid 帮到了你，欢迎点个 ⭐ Star，或请作者喝杯咖啡：
+
+<p align="center">
+  <img src="docs/88888.png" alt="小小支援，大大的爱" width="240"/>
+</p>