rj-grid 0.2.2 → 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>

package/dist/rj-grid.js

@@ -564,6 +564,9 @@ function useColumnState(sourceColumns) {
       widthMap.set(colIdOf(c), clampWidth(Math.round(cur[i] * factor), c));
     });
   }
+  function clearWidths() {
+    widthMap.clear();
+  }
   function moveColumn(dragId, targetId) {
     if (dragId === targetId)
       return;
@@ -637,6 +640,7 @@ function useColumnState(sourceColumns) {
     setAutoWidth,
     hasSizedWidth,
     sizeToFit,
+    clearWidths,
     moveColumn,
     togglePin,
     toggleHide,
@@ -4058,6 +4062,7 @@ const zhCN = {
   expServerNoPdf: "后端导出不含 PDF（浏览器打印属前端渲染），已改用前端范围",
   expServerMissing: "未接入后端导出：请设置 serverExport 回调",
   expFailed: "导出失败",
+  printCap: "数据量较大：仅打印前 {n} 行（共 {total} 行）。请缩小范围或走后端导出获取全量",
   resetState: "重置列状态",
   groupBanner: "⬇ 将列标题拖到此处进行行分组（或点面板“分组”页签）",
   // 加载 / 空态
@@ -4222,6 +4227,7 @@ const zhCN = {
   querySearch: "查询",
   queryReset: "重置",
   querySaveView: "存为视图",
+  queryRemove: "移除该条件",
   queryInput: "请输入",
   // 行编辑弹窗与内置确认框（查询栏操作按钮）
   rowFormTitle: "编辑行",
@@ -4294,6 +4300,7 @@ const enUS = {
   expServerNoPdf: "Server export has no PDF (browser printing is front-end); fell back to a front-end range",
   expServerMissing: "No server export wired up: provide a serverExport callback",
   expFailed: "Export failed",
+  printCap: "Large data set: printing the first {n} of {total} rows only. Narrow the range or use Server export for the full set",
   resetState: "Reset column state",
   groupBanner: "⬇ Drag column headers here to group rows (or Panel → Group)",
   loading: "Loading…",
@@ -4444,6 +4451,7 @@ const enUS = {
   querySearch: "Search",
   queryReset: "Reset",
   querySaveView: "Save as view",
+  queryRemove: "Remove this condition",
   queryInput: "Enter",
   // Row edit dialog & built-in confirm (query bar action buttons)
   rowFormTitle: "Edit Row",
@@ -4879,7 +4887,9 @@ function parseNLQ(text, columns) {
     return { ...empty, message: "empty" };
   const result = { ok: false, filters: [], clauses: [] };
   let buf = raw;
-  const lim = buf.match(/(?:前|取|返回|最多|top)\s*(\d+)\s*(?:行|条|个|名|件)?/i);
+  const lim = buf.match(
+    /(?:前|取|返回|最多|top|first|limit|show(?:\s+me)?|give\s+me)\s*(?:the\s+)?(\d+)\s*(?:行|条|个|名|件|rows?|records?|items?|results?)?/i
+  );
   if (lim) {
     result.limit = parseInt(lim[1], 10);
     buf = blank(buf, lim.index, lim[0].length);
@@ -4903,6 +4913,7 @@ function parseNLQ(text, columns) {
     if (col) {
       result.groupBy = col.field || col.title || col.colId;
       result.groupColId = col.colId;
+      result.groupTitle = col.title || col.field || col.colId;
       buf = blank(buf, g.start, g.len);
     }
   }
@@ -4911,14 +4922,21 @@ function parseNLQ(text, columns) {
     /sort\s*by\s+([^，,、;；]+)/i,
     /([^，,、;；\s]+?)(?:升序|降序|倒序|从大到小|从小到大)/i,
     // 比较级：X最高/最低/最大/最小/最贵/最便宜/最多/最少（可带尾随「的」一并消费，避免泄漏进相邻筛选值）
-    /([^，,、;；\s]+?)最(?:高|低|大|小|贵|便宜|多|少)的?/i
+    /([^，,、;；\s]+?)最(?:高|低|大|小|贵|便宜|多|少)的?/i,
+    // 英文比较级（后缀式）：X highest / X most expensive / X cheapest（不含裸 most/least，以免吞掉 at most/at least）
+    /([a-z][a-z ]*?)\s+(?:the\s+)?(?:highest|lowest|largest|biggest|smallest|most expensive|least expensive|cheapest)\b/i,
+    // 英文比较级（前缀式）：highest X / cheapest X
+    /\b(?:highest|lowest|largest|biggest|smallest|most expensive|cheapest|least expensive)\s+(?:the\s+)?([a-z][a-z ]*?)(?=$|[，,、;；.]|\s+(?:and|by|of)\b)/i
   ]);
   if (s) {
     const col = resolveColumn(s.name, columns);
     if (col) {
       const dirWord = (s.word || "").toLowerCase();
-      const desc = /降序|倒序|从大到小|desc|最高|最大|最贵|最多/.test(dirWord);
+      const desc = /降序|倒序|从大到小|desc|最高|最大|最贵|最多|highest|largest|biggest|most expensive/.test(
+        dirWord
+      );
       result.sort = { field: col.field || col.colId, dir: desc ? "desc" : "asc" };
+      result.sortTitle = col.title || col.field || col.colId;
       buf = blank(buf, s.start, s.len);
     }
   }
@@ -5154,21 +5172,72 @@ function mergeClauses(clauses, columns) {
   }
   return out;
 }
-function explainNLQ(r) {
+const OP_LABEL = {
+  zh: {
+    eq: "=",
+    ne: "≠",
+    gt: ">",
+    gte: "≥",
+    lt: "<",
+    lte: "≤",
+    contains: "包含",
+    notContains: "不包含",
+    startsWith: "开头是",
+    endsWith: "结尾为",
+    blank: "为空",
+    notBlank: "非空",
+    in: "属于",
+    notIn: "不属于",
+    inRange: "介于"
+  },
+  en: {
+    eq: "=",
+    ne: "≠",
+    gt: ">",
+    gte: "≥",
+    lt: "<",
+    lte: "≤",
+    contains: "contains",
+    notContains: "not contains",
+    startsWith: "starts with",
+    endsWith: "ends with",
+    blank: "is empty",
+    notBlank: "is not empty",
+    in: "is",
+    notIn: "not",
+    inRange: "between"
+  }
+};
+function explainNLQ(r, lang = "zh") {
+  const en = lang === "en";
+  const labels = OP_LABEL[lang];
   const parts = [];
   for (const c of r.clauses) {
-    const val = c.value2 != null ? `${c.value1}~${c.value2}` : c.value1 ?? "";
-    parts.push(`${c.title || c.field || c.colId} ${c.op} ${val}`.trim());
+    const opLabel = labels[c.op] || c.op;
+    const name = c.title || c.field || c.colId;
+    let val;
+    if (c.op === "blank" || c.op === "notBlank")
+      val = "";
+    else if (c.value2 != null)
+      val = `${c.value1}~${c.value2}`;
+    else if (Array.isArray(c.value1))
+      val = c.value1.join(en ? " / " : "、");
+    else
+      val = String(c.value1 ?? "");
+    const glue = en || /^[=<>≤≥≠]/.test(opLabel) ? " " : "";
+    parts.push(`${name} ${opLabel}${glue}${val}`.trim());
   }
   if (r.sort)
-    parts.push(`sort ${r.sort.field} ${r.sort.dir}`);
+    parts.push(
+      en ? `sort by ${r.sortTitle || r.sort.field} ${r.sort.dir}` : `按${r.sortTitle || r.sort.field} ${r.sort.dir === "desc" ? "降序" : "升序"}`
+    );
   if (r.groupBy)
-    parts.push(`group ${r.groupBy}`);
+    parts.push(en ? `group by ${r.groupTitle || r.groupBy}` : `按${r.groupTitle || r.groupBy}分组`);
   if (r.limit)
-    parts.push(`top ${r.limit}`);
+    parts.push(en ? `top ${r.limit}` : `前${r.limit}`);
   if (r.search)
-    parts.push(`search "${r.search}"`);
-  return parts.join(" | ");
+    parts.push(en ? `search "${r.search}"` : `搜索“${r.search}”`);
+  return parts.join(" · ");
 }
 const csvCell = (v) => {
   if (v == null)
@@ -7694,7 +7763,7 @@ const _sfc_main$a = /* @__PURE__ */ defineComponent({
     onMounted(() => {
       const el = menuRef.value;
       if (el)
-        emit("reposition", el.offsetHeight);
+        emit("reposition", el.offsetHeight, el.offsetWidth);
     });
     const hoverIdx = ref(-1);
     function onClick(item) {
@@ -9026,7 +9095,7 @@ const _hoisted_3$4 = ["value", "onChange"];
 const _hoisted_4$3 = ["value"];
 const _hoisted_5$3 = ["value", "placeholder", "onInput"];
 const _hoisted_6$3 = ["value", "placeholder", "onInput"];
-const _hoisted_7$2 = ["onClick"];
+const _hoisted_7$2 = ["title", "onClick"];
 const _hoisted_8$2 = {
   value: "",
   disabled: ""
@@ -9259,7 +9328,7 @@ const _sfc_main$4 = /* @__PURE__ */ defineComponent({
             }, null, 40, _hoisted_6$3)),
             createElementVNode("span", {
               class: "rj-query-del",
-              title: "移除",
+              title: unref(t)("queryRemove"),
               onClick: ($event) => remove(i)
             }, "✕", 8, _hoisted_7$2)
           ]);
@@ -9849,6 +9918,7 @@ function buildPrintHtml(input, opts = {}) {
   const headBg = o.headerDark ? "#4472c4" : "#eef1f6";
   const headColor = o.headerDark ? "#ffffff" : "#1f2329";
   const zebraRule = o.zebra ? "tbody tr:nth-child(even) td{background:#f7f9fc}" : "";
+  const rowBreakRule = input.matrix.length > 300 ? "tr { break-inside: auto; page-break-inside: auto; }" : "tr { page-break-inside: avoid; break-inside: avoid; }";
   const style = `
 @page { ${pageBox} margin: ${o.margins}mm; }
 ${o.pageNumbers ? `@page { @bottom-center { content: ${pageContentCss(o.pageNumberText)}; font-size: 10px; color: #999; } }` : ""}
@@ -9860,7 +9930,7 @@ body { font-family: -apple-system, "Segoe UI", "Microsoft YaHei", Arial, sans-se
 .rj-print-sub { font-size: 12px; color: #666; margin: 0 0 10px; }
 table { border-collapse: collapse; width: 100%; table-layout: ${o.scaleToFit ? "auto" : "fixed"}; font-size: 12px; }
 thead { display: table-header-group; }
-tr { page-break-inside: avoid; break-inside: avoid; }
+${rowBreakRule}
 th, td { border: ${border}; padding: 4px 8px; text-align: left; vertical-align: top; word-break: break-word; }
 thead th { background: ${headBg}; color: ${headColor}; font-weight: 600; text-align: center; }
 ${zebraRule}
@@ -9948,19 +10018,19 @@ const _hoisted_7 = {
 };
 const _hoisted_8 = { key: 0 };
 const _hoisted_9 = ["onClick"];
-const _hoisted_10 = ["title"];
-const _hoisted_11 = ["title"];
-const _hoisted_12 = ["title"];
-const _hoisted_13 = ["title"];
+const _hoisted_10 = ["data-tip", "aria-label"];
+const _hoisted_11 = ["data-tip", "aria-label"];
+const _hoisted_12 = ["data-tip", "aria-label"];
+const _hoisted_13 = ["data-tip", "aria-label"];
 const _hoisted_14 = {
   key: 5,
   class: "rj-export-group"
 };
-const _hoisted_15 = ["title"];
-const _hoisted_16 = ["title"];
-const _hoisted_17 = ["title"];
-const _hoisted_18 = ["title"];
-const _hoisted_19 = ["title"];
+const _hoisted_15 = ["data-tip"];
+const _hoisted_16 = ["data-tip"];
+const _hoisted_17 = ["data-tip"];
+const _hoisted_18 = ["data-tip"];
+const _hoisted_19 = ["data-tip", "aria-label"];
 const _hoisted_20 = { style: { "display": "flex", "flex": "1", "min-height": "0" } };
 const _hoisted_21 = ["role"];
 const _hoisted_22 = ["aria-rowindex", "aria-selected", "data-rk"];
@@ -10112,6 +10182,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     exportRange: { default: "auto" },
     serverExport: {},
     exportFileName: {},
+    printMaxRows: { default: 1e3 },
     exportRawValues: { type: Boolean },
     statusBar: { type: Boolean, default: true },
     statusAggregations: { default: () => ["sum", "avg", "count", "min", "max"] },
@@ -10508,6 +10579,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     const quickPop = ref(null);
     const quickInputRef = ref();
     function toggleQuickPop(ev) {
+      tip.value = null;
       if (quickPop.value) {
         quickPop.value = null;
         return;
@@ -12590,25 +12662,50 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       }));
     });
     const menu = ref(null);
-    function openMenuAt(x, y, items, above) {
+    const tip = ref(null);
+    function onTipOver(e) {
+      var _a2, _b;
+      const host = e.currentTarget;
+      const el = (_b = (_a2 = e.target) == null ? void 0 : _a2.closest) == null ? void 0 : _b.call(_a2, "[data-tip]");
+      if (!el || !host.contains(el))
+        return;
+      const r = el.getBoundingClientRect();
+      tip.value = { text: el.getAttribute("data-tip") || "", x: r.right, y: r.bottom + 6 };
+    }
+    function onTipOut(e) {
+      var _a2, _b;
+      const el = (_b = (_a2 = e.target) == null ? void 0 : _a2.closest) == null ? void 0 : _b.call(_a2, "[data-tip]");
+      const to = e.relatedTarget;
+      if (el && to && el.contains(to))
+        return;
+      tip.value = null;
+    }
+    function openMenuAt(x, y, items, above, estW = 220) {
       if (!items.length)
         return;
+      tip.value = null;
       const est = items.length * 28 + 16;
       const bottom = window.innerHeight - 8;
+      const xc = Math.max(8, Math.min(x, window.innerWidth - estW - 8));
       if (y + est <= bottom) {
-        menu.value = { items, x, y, limit: bottom };
+        menu.value = { items, x: xc, y, limit: bottom };
         return;
       }
       const lim = (above ?? y) - 6;
-      menu.value = { items, x, y: Math.max(8, (above ?? y) - est - 8), limit: lim };
+      menu.value = { items, x: xc, y: Math.max(8, (above ?? y) - est - 8), limit: lim };
     }
-    function onMenuReposition(h2) {
+    function onMenuReposition(h2, w) {
       const m = menu.value;
       if (!m)
         return;
       const lim = m.limit ?? window.innerHeight - 8;
+      const next = { ...m };
       if (m.y + h2 > lim)
-        menu.value = { ...m, y: Math.max(8, lim - h2) };
+        next.y = Math.max(8, lim - h2);
+      if (w && m.x + w > window.innerWidth - 8)
+        next.x = Math.max(8, window.innerWidth - 8 - w);
+      if (next.y !== m.y || next.x !== m.x)
+        menu.value = next;
     }
     function onMenuSelect(item) {
       var _a2;
@@ -12890,7 +12987,9 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           { isSeparator: true },
           { name: t("scopeServer"), action: () => callServerExport(fmt) }
         );
-      openMenuAt(ev.clientX, ev.clientY, items);
+      const el = ev.currentTarget;
+      const r = el.getBoundingClientRect();
+      openMenuAt(r.left, r.bottom + 6, items, r.top);
     }
     function runFormat(fmt, scope) {
       if (fmt === "print")
@@ -13010,7 +13109,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
         return v.join(" ");
       return displayOf(col, v, row, 0);
     }
-    function buildPrintInput(params) {
+    function buildPrintInput(params, limit = 0) {
       const cols = exportColumnsOf(params);
       const columns = cols.map((c) => {
         var _a2;
@@ -13022,26 +13121,32 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       });
       const matrix = [];
       const rowStyles = [];
+      const capped = limit > 0;
+      const full = () => capped && matrix.length >= limit;
       const pushRow = (d, kind) => {
         matrix.push(cols.map((c) => printTextOf(c, d.data)));
         rowStyles.push(kind);
       };
       const scope = scopeOf(params);
       if (scope === "view") {
-        rowModel.processed.value.displayRows.forEach((d) => {
+        for (const d of rowModel.processed.value.displayRows) {
+          if (full())
+            break;
           if (d.type === "group" && !d.isFooter)
             pushRow(d, 1);
           else if (d.type === "row")
             pushRow(d, 0);
-        });
+        }
       } else {
-        pickExportRows(scope, exportRowSource(), false).forEach((r) => {
+        for (const r of pickExportRows(scope, exportRowSource(), false)) {
+          if (full())
+            break;
           matrix.push(cols.map((c) => printTextOf(c, r)));
           rowStyles.push(0);
-        });
+        }
       }
       const srow = rowModel.summaryRow.value;
-      if (scope === "view" && props.showSummary && srow) {
+      if (scope === "view" && props.showSummary && srow && !full()) {
         matrix.push(
           cols.map((c) => {
             const raw = srow[colIdOf(c)] ?? cellRawValue(c, srow);
@@ -13079,8 +13184,22 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       warnIfLoadedOnly(scopeOf(params));
       withExportBusy(() => runPrint(params));
     }
+    function printRowEstimate(scope) {
+      if (scope === "view")
+        return rowModel.processed.value.displayRows.reduce(
+          (n, d) => n + (d.type === "row" || d.type === "group" && !d.isFooter ? 1 : 0),
+          0
+        );
+      return pickExportRows(scope, exportRowSource(), false).length;
+    }
     function runPrint(params) {
-      printHtml(buildPrintInput(params), printOpts(params));
+      const cap = props.printMaxRows;
+      const total = printRowEstimate(scopeOf(params));
+      const limit = cap > 0 && total > cap ? cap : 0;
+      const input = buildPrintInput(params, limit);
+      if (limit)
+        showToast(t("printCap", { n: cap, total }));
+      printHtml(input, printOpts(params));
     }
     const rowGroupPayload = computed(() => {
       void aggRev.value;
@@ -13575,6 +13694,13 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
         scheduleSave();
         dispatchEvent("columnEverythingChanged", {});
       },
+      /** 清除宽度覆盖：把列宽还原到列定义/内容自适应默认值（配合 autoSizeAll 做「自适应↔还原」切换） */
+      resetColumnWidths: () => {
+        colState.clearWidths();
+        applyDefaultAutoWidths();
+        scheduleSave();
+        dispatchEvent("columnEverythingChanged", {});
+      },
       // 主题 / i18n（运行时切换）
       setTheme: (params) => {
         themeState.value = { ...params };
@@ -13816,18 +13942,24 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             onDragover: _cache[21] || (_cache[21] = withModifiers(() => {
             }, ["stop"])),
             onDrop: _cache[22] || (_cache[22] = withModifiers(() => {
-            }, ["stop"]))
+            }, ["stop"])),
+            onPointerover: onTipOver,
+            onPointerout: onTipOut,
+            onFocusin: onTipOver,
+            onFocusout: onTipOut
           }, [
             _ctx.quickFilterEnabled ? (openBlock(), createElementBlock("button", {
               key: 0,
               class: normalizeClass(["rj-btn rj-tool-btn rj-quick-btn", { "is-active": !!unref(rowModel).quickFilter.value }]),
-              title: t("quickBtn"),
+              "data-tip": t("quickBtn"),
+              "aria-label": t("quickBtn"),
               onClick: _cache[9] || (_cache[9] = ($event) => toggleQuickPop($event))
             }, "🔍", 10, _hoisted_10)) : createCommentVNode("", true),
             _ctx.viewable ? (openBlock(), createElementBlock("button", {
               key: 1,
               class: normalizeClass(["rj-btn rj-tool-btn rj-view-btn", { "is-active": !!currentViewId.value }]),
-              title: t("viewBtn"),
+              "data-tip": t("viewBtn"),
+              "aria-label": t("viewBtn"),
               onClick: _cache[10] || (_cache[10] = ($event) => openViewMenu($event))
             }, "◈", 10, _hoisted_11)) : createCommentVNode("", true),
             showExpandCollapse.value ? (openBlock(), createElementBlock(Fragment, { key: 2 }, [
@@ -13847,12 +13979,14 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             }, toDisplayString(t("chart")), 1)) : createCommentVNode("", true),
             createElementVNode("button", {
               class: "rj-btn",
-              title: t("density") + " · " + DENSITY_LABELS.value[densityIdx.value],
+              "data-tip": t("density") + " · " + DENSITY_LABELS.value[densityIdx.value],
+              "aria-label": t("density"),
               onClick: _cache[14] || (_cache[14] = ($event) => densityIdx.value = (densityIdx.value + 1) % 3)
             }, toDisplayString(["▤", "☰", "▥"][densityIdx.value]), 9, _hoisted_12),
             createElementVNode("button", {
               class: "rj-btn",
-              title: dark.value ? t("toLight") : t("toDark"),
+              "data-tip": dark.value ? t("toLight") : t("toDark"),
+              "aria-label": dark.value ? t("toLight") : t("toDark"),
               onClick: _cache[15] || (_cache[15] = ($event) => toggleDark())
             }, toDisplayString(dark.value ? "☀" : "🌙"), 9, _hoisted_13),
             _ctx.toolPanel ? (openBlock(), createElementBlock("button", {
@@ -13863,29 +13997,30 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             _ctx.exportable ? (openBlock(), createElementBlock("div", _hoisted_14, [
               createElementVNode("button", {
                 class: "rj-btn rj-btn-export rj-export-btn",
-                title: t("printTip"),
+                "data-tip": t("printTip"),
                 onClick: _cache[17] || (_cache[17] = ($event) => openRangeMenu($event, "print"))
               }, toDisplayString(t("printBtn")), 9, _hoisted_15),
               createElementVNode("button", {
                 class: "rj-btn rj-btn-export rj-export-btn",
-                title: t("csvTip"),
+                "data-tip": t("csvTip"),
                 onClick: _cache[18] || (_cache[18] = ($event) => openRangeMenu($event, "csv"))
               }, " CSV ", 8, _hoisted_16),
               createElementVNode("button", {
                 class: "rj-btn rj-btn-export rj-export-btn",
-                title: t("pdfTip"),
+                "data-tip": t("pdfTip"),
                 onClick: _cache[19] || (_cache[19] = ($event) => openRangeMenu($event, "pdf"))
               }, " PDF ", 8, _hoisted_17),
               createElementVNode("button", {
                 class: "rj-btn rj-btn-export rj-export-btn",
-                title: t("excelTip"),
+                "data-tip": t("excelTip"),
                 onClick: _cache[20] || (_cache[20] = ($event) => openRangeMenu($event, "excel"))
               }, " Excel ", 8, _hoisted_18)
             ])) : createCommentVNode("", true),
             _ctx.stateKey ? (openBlock(), createElementBlock("button", {
               key: 6,
               class: "rj-btn",
-              title: t("resetState"),
+              "data-tip": t("resetState"),
+              "aria-label": t("resetState"),
               onClick: resetState
             }, "↺", 8, _hoisted_19)) : createCommentVNode("", true)
           ], 32)) : createCommentVNode("", true)
@@ -14452,8 +14587,14 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           onClear: clearAdvancedFilter,
           onClose: _cache[43] || (_cache[43] = ($event) => advDialog.value = null)
         }, null, 8, ["model", "columns", "x", "y"])) : createCommentVNode("", true),
-        menu.value ? (openBlock(), createBlock(_sfc_main$a, {
+        tip.value ? (openBlock(), createElementBlock("div", {
           key: 8,
+          class: "rj-tip",
+          role: "tooltip",
+          style: normalizeStyle({ left: tip.value.x + "px", top: tip.value.y + "px" })
+        }, toDisplayString(tip.value.text), 5)) : createCommentVNode("", true),
+        menu.value ? (openBlock(), createBlock(_sfc_main$a, {
+          key: 9,
           items: menu.value.items,
           x: menu.value.x,
           y: menu.value.y,
@@ -14461,7 +14602,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           onReposition: onMenuReposition
         }, null, 8, ["items", "x", "y"])) : createCommentVNode("", true),
         colMenu.value ? (openBlock(), createBlock(_sfc_main$9, {
-          key: 9,
+          key: 10,
           col: colMenu.value.col,
           "col-id": colMenu.value.colId,
           x: colMenu.value.x,
@@ -14489,13 +14630,13 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           onColDrop
         }, null, 8, ["col", "col-id", "x", "y", "can-sort", "can-filter", "can-group", "sort-dir", "pinned", "filter-type", "filter-model", "unique-values", "columns"])) : createCommentVNode("", true),
         chartOpen.value ? (openBlock(), createBlock(_sfc_main$6, {
-          key: 10,
+          key: 11,
           columns: pipelineCols.value,
           rows: chartRows.value,
           onClose: _cache[44] || (_cache[44] = ($event) => chartOpen.value = false)
         }, null, 8, ["columns", "rows"])) : createCommentVNode("", true),
         rowFormDlg.value ? (openBlock(), createBlock(_sfc_main$3, {
-          key: 11,
+          key: 12,
           fields: rowFormDlg.value.fields,
           rows: rowFormDlg.value.rows,
           mode: rowFormDlg.value.mode,
@@ -14505,13 +14646,13 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           onClose: _cache[45] || (_cache[45] = ($event) => rowFormDlg.value = null)
         }, null, 8, ["fields", "rows", "mode", "title", "width"])) : createCommentVNode("", true),
         confirmDlg.value ? (openBlock(), createBlock(_sfc_main$2, {
-          key: 12,
+          key: 13,
           message: confirmDlg.value.message,
           onOk: onConfirmOk,
           onCancel: _cache[46] || (_cache[46] = ($event) => confirmDlg.value = null)
         }, null, 8, ["message"])) : createCommentVNode("", true),
         dragGhost.value ? (openBlock(), createElementBlock("div", {
-          key: 13,
+          key: 14,
           ref_key: "dragGhostRef",
           ref: dragGhostRef,
           class: "rj-drag-ghost",
@@ -14532,7 +14673,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           !dragGhost.value.cells.length ? (openBlock(), createElementBlock("span", _hoisted_51, toDisplayString(t("dragRow")), 1)) : createCommentVNode("", true)
         ], 4)) : createCommentVNode("", true),
         imgPreview.value ? (openBlock(), createElementBlock("div", {
-          key: 14,
+          key: 15,
           class: "rj-img-viewer",
           role: "dialog",
           "aria-modal": "true",

package/dist/style.css

@@ -10,7 +10,7 @@
   --rj-text-secondary: #909399;
   --rj-primary: #3b76f6;
   --rj-primary-bg: #eaf1fe;
-  --rj-hover-bg: #f2f6fd;
+  --rj-hover-bg: #e6edf9;
   --rj-selected-bg: #e2edfd;
   --rj-range-bg: rgba(59, 118, 246, 0.1);
   --rj-fill-bg: rgba(59, 118, 246, 0.16);
@@ -52,7 +52,7 @@
   --rj-text-secondary: #8a919f;
   --rj-primary: #5c8dfb;
   --rj-primary-bg: #24324d;
-  --rj-hover-bg: #272d3a;
+  --rj-hover-bg: #313a4d;
   --rj-selected-bg: #2a3a5c;
   --rj-mask: rgba(30, 34, 42, 0.75);
   --rj-flash-bg: #5a4c1e;
@@ -509,6 +509,25 @@
   font-weight: 500;
 }
 
+.rj-tip {
+  position: fixed;
+  z-index: 3100;
+  width: max-content;
+  max-width: 240px;
+  padding: 3px 8px;
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 1.4;
+  color: var(--rj-bg);
+  text-align: left;
+  white-space: normal;
+  pointer-events: none;
+  background: var(--rj-text);
+  border-radius: var(--rj-radius);
+  box-shadow: var(--rj-shadow);
+  transform: translateX(-100%);
+}
+
 .rj-pager {
   display: flex;
   align-items: center;

package/dist/types/src/RjContextMenu.vue.d.ts

@@ -5,14 +5,14 @@ declare const _default: import("vue").DefineComponent<import("vue").ExtractPropT
     y: number;
 }>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     select: (item: RjMenuItem) => void;
-    reposition: (h: number) => void;
+    reposition: (h: number, w: number) => void;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
     items: RjMenuItem[];
     x: number;
     y: number;
 }>>> & Readonly<{
     onSelect?: ((item: RjMenuItem) => any) | undefined;
-    onReposition?: ((h: number) => any) | undefined;
+    onReposition?: ((h: number, w: number) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export default _default;
 type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;

package/dist/types/src/RjGrid.vue.d.ts

@@ -96,6 +96,12 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
      */
     serverExport?: ((params: RjServerExportParams) => void | Promise<void>) | undefined;
     exportFileName?: string | undefined;
+    /**
+     * 打印 / PDF 单次最大行数护栏：浏览器打印靠把整表排版进隐藏 iframe，
+     * 上万行会生成十几 MB HTML 并让主线程卡死（页面假死）。超过此上限只打印前 N 行并提示，
+     * 需全量请先筛选 / 用分页 / 走后端导出，或按宿主机器性能调大本值。置 0 或负数则不限。
+     */
+    printMaxRows?: number | undefined;
     /** 导出取值口径：默认导出「所见即所得」的格式化文本（与屏幕一致、单文件内口径统一）；
      *  置 true 则导出原始类型值，让 Excel 里数字仍是数字（对齐 AG Grid useCellValuesForExports） */
     exportRawValues?: boolean | undefined;
@@ -182,6 +188,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
     copyHeadersToClipboard: boolean;
     markDirtyCells: boolean;
     rowHover: boolean;
+    printMaxRows: number;
     queryable: boolean;
     viewable: boolean;
     queryFields: () => never[];
@@ -303,6 +310,12 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
      */
     serverExport?: ((params: RjServerExportParams) => void | Promise<void>) | undefined;
     exportFileName?: string | undefined;
+    /**
+     * 打印 / PDF 单次最大行数护栏：浏览器打印靠把整表排版进隐藏 iframe，
+     * 上万行会生成十几 MB HTML 并让主线程卡死（页面假死）。超过此上限只打印前 N 行并提示，
+     * 需全量请先筛选 / 用分页 / 走后端导出，或按宿主机器性能调大本值。置 0 或负数则不限。
+     */
+    printMaxRows?: number | undefined;
     /** 导出取值口径：默认导出「所见即所得」的格式化文本（与屏幕一致、单文件内口径统一）；
      *  置 true 则导出原始类型值，让 Excel 里数字仍是数字（对齐 AG Grid useCellValuesForExports） */
     exportRawValues?: boolean | undefined;
@@ -389,6 +402,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
     copyHeadersToClipboard: boolean;
     markDirtyCells: boolean;
     rowHover: boolean;
+    printMaxRows: number;
     queryable: boolean;
     viewable: boolean;
     queryFields: () => never[];
@@ -472,6 +486,7 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
     detailHeight: number;
     fullWidthHeight: number;
     exportRange: "auto" | RjExportScopeResolved;
+    printMaxRows: number;
     statusBar: boolean;
     statusAggregations: ("sum" | "avg" | "min" | "max" | "count")[];
     undoRedoCellEditing: boolean;
@@ -594,6 +609,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
             autoSizeColumn: (colId: string) => void;
             autoSizeAll: () => void;
             sizeColumnsToFit: () => void;
+            /** 清除宽度覆盖：把列宽还原到列定义/内容自适应默认值（配合 autoSizeAll 做「自适应↔还原」切换） */
+            resetColumnWidths: () => void;
             setTheme: (params: RjThemeParams) => void;
             getTheme: () => {
                 preset?: "legacy" | "alpine" | "quartz" | "material" | undefined;
@@ -728,6 +745,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
             autoSizeColumn: (colId: string) => void;
             autoSizeAll: () => void;
             sizeColumnsToFit: () => void;
+            /** 清除宽度覆盖：把列宽还原到列定义/内容自适应默认值（配合 autoSizeAll 做「自适应↔还原」切换） */
+            resetColumnWidths: () => void;
             setTheme: (params: RjThemeParams) => void;
             getTheme: () => {
                 preset?: "legacy" | "alpine" | "quartz" | "material" | undefined;
@@ -866,6 +885,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
             autoSizeColumn: (colId: string) => void;
             autoSizeAll: () => void;
             sizeColumnsToFit: () => void;
+            /** 清除宽度覆盖：把列宽还原到列定义/内容自适应默认值（配合 autoSizeAll 做「自适应↔还原」切换） */
+            resetColumnWidths: () => void;
             setTheme: (params: RjThemeParams) => void;
             getTheme: () => {
                 preset?: "legacy" | "alpine" | "quartz" | "material" | undefined;
@@ -1001,6 +1022,8 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
             autoSizeColumn: (colId: string) => void;
             autoSizeAll: () => void;
             sizeColumnsToFit: () => void;
+            /** 清除宽度覆盖：把列宽还原到列定义/内容自适应默认值（配合 autoSizeAll 做「自适应↔还原」切换） */
+            resetColumnWidths: () => void;
             setTheme: (params: RjThemeParams) => void;
             getTheme: () => {
                 preset?: "legacy" | "alpine" | "quartz" | "material" | undefined;

package/dist/types/src/nlq.d.ts

@@ -1,4 +1,5 @@
 import type { RjFilterModel, RjSortState } from './types';
+import type { RjLang } from './locale';
 export type RjNlqFilterType = 'text' | 'number' | 'date' | 'select';
 /** 参与解析的列描述（由网格从列定义构建） */
 export interface RjNlqColumn {
@@ -39,13 +40,20 @@ export interface RjNlqResult {
         model: RjFilterModel;
     }[];
     sort?: RjSortState;
+    /** 排序列展示名（title，供 explainNLQ 本地化回显） */
+    sortTitle?: string;
     groupBy?: string;
     groupColId?: string;
+    /** 分组列展示名（title，供 explainNLQ 本地化回显） */
+    groupTitle?: string;
     limit?: number;
     search?: string;
     clauses: RjNlqClause[];
 }
 /** 解析自然语言查询 */
 export declare function parseNLQ(text: string, columns: RjNlqColumn[]): RjNlqResult;
-/** 生成人类可读的解析摘要（供 UI 回显，key 交由上层 i18n；此处给结构串） */
-export declare function explainNLQ(r: RjNlqResult): string;
+/**
+ * 生成人类可读的解析摘要（供 UI 回显）。传 lang 则随语言本地化：
+ * 中文如「数量 > 100 · 按金额 降序 · 前5 · 搜索“轴承”」，英文如「qty > 100 · sort by amount desc · top 5 · search "bolt"」。
+ */
+export declare function explainNLQ(r: RjNlqResult, lang?: RjLang): string;

package/dist/types/src/types.d.ts

@@ -630,6 +630,8 @@ export interface RjGridApi extends ComponentPublicInstance {
     autoSizeAll: () => void;
     /** 列宽：按视口宽度等比缩放普通区列（对标 sizeColumnsToFit） */
     sizeColumnsToFit: () => void;
+    /** 清除全部列宽覆盖，还原到列定义/内容自适应默认宽（与 autoSizeAll 配合做自适应↔还原切换） */
+    resetColumnWidths: () => void;
     /** 主题引擎（对标 AG Grid Theming）：运行时替换预设/明暗/强调色等 */
     setTheme: (params: RjThemeParams) => void;
     /** 读取当前生效的主题参数 */

package/dist/types/src/useColumnState.d.ts

@@ -60,6 +60,7 @@ export declare function useColumnState(sourceColumns: () => RjColumn[]): {
     setAutoWidth: (colId: string, width: number) => void;
     hasSizedWidth: (colId: string) => boolean;
     sizeToFit: () => void;
+    clearWidths: () => void;
     moveColumn: (dragId: string, targetId: string) => void;
     togglePin: (colId: string, pin: 'left' | 'right' | null) => void;
     toggleHide: (colId: string, hide?: boolean) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rj-grid",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "零第三方依赖的自研 Vue3 虚拟表格：虚拟滚动 / 冻结列 / 行拖拽 / 分组透视 / 公式 / SSRM / 主题 i18n / 自然语言查询",
   "type": "module",
   "license": "MIT",
@@ -46,6 +46,7 @@
     }
   },
   "scripts": {
+    "start": "vite --config vite.playground.config.ts",
     "dev": "vite --config vite.playground.config.ts",
     "build:play": "vite build --config vite.playground.config.ts",
     "preview:play": "vite preview --config vite.playground.config.ts",
@@ -55,6 +56,8 @@
     "lint": "eslint --fix --ext .ts,.vue index.ts src __tests__ playground && stylelint \"src/styles/*.scss\"",
     "ts": "node --max_old_space_size=8192 ./node_modules/vue-tsc/bin/vue-tsc.js --noEmit -p tsconfig.json",
     "size": "node ./node_modules/vite/bin/vite.js build --config vite.size.config.ts && node build/rjSizeReport.mjs",
+    "publish:github": "node scripts/publish-github.mjs",
+    "publish:github:push": "node scripts/publish-github.mjs --push",
     "prepublishOnly": "pnpm build && pnpm test"
   },
   "keywords": [