# jqtable

**Repository Path**: aprilyu/jqtable

## Basic Information

- **Project Name**: jqtable
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-11
- **Last Updated**: 2026-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jqtable

一个不依赖任何 CSS 框架的 jQuery 数据表格。目标是把 Bootstrap Table 的能力补齐，同时把样式和渲染层重做一遍。

- **零 UI 框架依赖**：不需要 Bootstrap，自带完整 design token，暗色模式一键切换
- **两种产物**：`jqtable.umd.js`（`<script>` 直接引入）+ `jqtable.es.js`（`import`）
- **TypeScript 源码**：类型声明随包产出，IDE 里能直接看到选项提示
- **渲染模型**：原生 `<table>` + `position: sticky`，保留语义、打印和复制粘贴能力

当前版本 **v0.5.0**，已完成 P0 范围，可以直接接入业务页面。

## 快速开始

### 方式一：`<script>` 引入（老项目）

```html
<link rel="stylesheet" href="dist/jqtable.css">
<script src="jquery.min.js"></script>
<script src="dist/jqtable.umd.js"></script>

<div id="grid"></div>
<script>
  var table = $('#grid').jqtable({
    url: '/api/orders',
    rowKey: 'id',
    paging: { mode: 'server', pageSize: 20 },
    columns: [
      { field: 'no', title: '订单号', width: 150, sortable: true },
      { field: 'customer', title: '客户名称', width: 200 },
      { field: 'amount', title: '金额', width: 140, align: 'right',
        formatter: function (v) { return '¥' + v.toFixed(2); } }
    ]
  });
</script>
```

### 方式二：ESM

```js
import $ from 'jquery';
import JQTable from 'jqtable';
import 'jqtable/dist/jqtable.css';

const table = new JQTable(document.getElementById('grid'), { columns: [...] });
```

本地开发时直接打开 `demo/index.html` 就能看到六个场景（需先 `npm run build`）。

## 已实现

| 分类 | 能力 |
|---|---|
| 数据 | 本地数组 / 远程接口（jQuery.ajax、fetch、自定义函数）、`queryParams` / `responseHandler` 改写 |
| 分页 | 客户端 + 服务端，`page` / `pageSize` 契约，页长切换、跳页、省略号页码 |
| 排序 | 单列 / 多列（`shift` 点击），客户端与服务端两种模式 |
| 筛选 | 关键字搜索（防抖 200ms）、`setFilter` 自定义谓词，服务端模式下作为请求参数 |
| 选择 | 复选框、全选/半选、跨页保持、选中数联动工具栏按钮 |
| 固定列 | 左右任意列固定，横向滚动时才出现投影 |
| 树形 | `parentId` 推导层级、可展开折叠、默认展开层级、搜索时保留祖先 |
| 分组 | 按字段分组、小计与总计、可折叠 |
| 详情展开 | 展开行内容完全由业务 `render` / `html` 注入，插件只给容器；支持手风琴、重载保留、固定列下的面板定位 |
| 列设置 | 显隐、拖拽换序、拖拽调宽，localStorage 持久化 |
| 宽度 | `fillWidth` 三种策略（等比铺满 / 剩余给末列 / 留白），列宽算准再写死，全屏不留白 |
| 导出 | CSV（带 BOM，防 Excel 公式注入） |
| 状态 | 首次加载骨架屏 / 刷新时保留旧数据只显示顶部进度条 / 空态与失败态结构一致，默认都只有一行标题（说明、按钮、错误详情按需打开） |
| 工具栏 | 左右分区：左侧业务按钮（含下拉菜单、随选中禁用），右侧内置能力；左侧也支持直接把页面里已有的 DOM 用选择器搬进来 |
| 外观 | 三档密度、明暗主题、斑马纹开关、设计 token 可覆盖 |
| 质量 | 数据管道 / 列宽计算 / 工具 / 选项归一化共 158 个单测（Vitest） |

**本次不做**（已确认砍掉）：行内编辑、卡片模式、打印样式、可编辑单元格。

## 目录

```
src/
  core/         引擎：类型、选项、数据管道、列宽计算、渲染、工具、图标、文案
  features/     特性：工具栏、列设置、导出
  styles/       设计 token + 全部样式（qt- 前缀命名空间）
  index.ts      入口（导出类 + 注册 jQuery 插件）
  plugin.ts     $.fn.jqtable 绑定
demo/           六个场景的可运行示例
tests/          纯函数层单测（数据管道 / 列宽计算 / 工具 / 选项）
server/         联调用的 mock API（零依赖，支持分页/排序/搜索/增删改/延迟与失败注入）
docs/           架构 / API / 开发指南
prototype/      最初的纯静态样式原型（设计参照，不参与构建）
```

## 命令

```bash
npm install         # 安装依赖
npm run dev         # Vite 开发服务器（默认打开 demo/index.html）
npm run build       # 产出 dist/：UMD + ESM + CSS + d.ts
npm run typecheck   # 只做类型检查
npm test            # 单元测试（纯函数层，150 个用例）
```

联调真实接口（可选，后端在 `server/`，零依赖不用安装）：

```bash
cd server && node index.js     # 打开 http://127.0.0.1:3000/ 是联调台
```

联调台和 `demo/index.html` 是分开的两个页面：demo 用纯本地数据展示表格本身，联调台的每个数字都来自真实 HTTP 请求，并带一个请求日志面板，能直接看到「点了排序，前端到底发了什么参数」。

`npm run build` 之后，`demo/index.html` 可以直接双击用 `file://` 打开，不需要起服务。

## 文档

- [架构设计](docs/ARCHITECTURE.md)：分层、数据管道、固定列算法、踩坑记录
- [API 手册](docs/API.md)：全部选项、方法、事件、服务端契约
- [开发指南](docs/DEV.md)：换一台电脑怎么继续做、改哪里、回归清单
- [迁移指南](docs/MIGRATION-OrderInfo.md)：把现有 OrderInfo 页从 Bootstrap Table 换过来的逐项对照

## 浏览器要求

Chrome / Edge 88+、Firefox 78+、Safari 14+。依赖 `position: sticky`、CSS 自定义属性、`ResizeObserver`、`Pointer Events`。

## License

MIT