# SuperList **Repository Path**: chenxu8888/super-list ## Basic Information - **Project Name**: SuperList - **Description**: 在后端分页前提下,可保存所有页行选择状态的list控件 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-18 - **Last Updated**: 2026-11-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SuperList 一个零依赖的 Web 数据表格(列表)控件演示:原生 JavaScript 实现前端组件,后端为纯 Node.js `http` 的 Mock 服务。支持后端分页、全结果集排序、冻结列、表头拖拽重排(可跨锁定边界)、列宽调整、单元格合并、跨页选择记忆、行内可编辑单元格、多语言(含 RTL)与设置持久化。 ## 功能特性 ## 相关文档 - 缺陷登记与横向展开(含 BUG-9/BUG-10 成因模式、横向展开表与统一修复规范):[BUGS.md](./BUGS.md) ## 功能特性 - **后端分页 + 全结果集排序**:排序在服务端对全量数据生效后再分页。 - **冻结列**:前 N 列锁定在左侧,横向滚动只发生在非锁定区;表头在两侧都固定在顶部。 - **表头拖拽重排**:拖动表头即可调整列顺序;把表头拖入「锁定区」即变为锁定列,拖出到「非锁定区」即变为非锁定列(选择框/行号两列固定不可拖且始终锁定)。 - **列宽调整**:拖动表头右边缘改变列宽。 - **排序**:点击表头在升/降序间切换,带排序指示。 - **表头筛选(Excel 式)**:每个数据列表头带漏斗按钮,下拉面板支持候选值勾选、搜索、(全选)、确定/取消/清除;候选值与行数由后端按「其他列的筛选结果」实时算出。筛选由后端重新取数(不是前端过滤),已设定的条件会保留在表头(按钮高亮 + hover 提示),随时可再打开修改;多个列之间是 AND,同一列内多值是 OR。 - **单元格合并**:按字段的连续相同值竖向合并(`rowspan`)。 - **跨页选择记忆 + 全选规则**:以「意图规则」提交(全选+排除 / 部分选择),由后端按当前数据解析,插入/删除行后依然一致。 - **提交行内容**:除规则外,随提交带上选中行的指定字段值(如 `name` / `birthDate` / `lastLogin` / `amount`),后端可直接拿到行内容;未加载过的行会先通过 `/api/ids` + `/api/rows` 补全。 - **行内可编辑单元格**(演示):`date` / `datetime` / `number` / `button` / `link`。 - **行编辑(操作列)**:点「行编辑」把整行除「选择框、行号、主键列」以外的所有列变成输入框;该行若处于合并单元格中会自动拆开单独编辑;再次点击(按钮变为「行保存」)时与后端下发的原值逐字段比对,**只提交真正被修改的字段**,保存后按新值重新计算合并。 - **操作列排版**:操作列默认放在**冻结区的第 7 列**(选择框 / 展开 / 行号 / 姓名 / 大区 / 部门 / 操作),横向滚动时按钮始终可见;空闲态分**上下两行**(上行:行编辑;下行:复制新增 + 行删除),按钮尺寸约为原来的一半,列宽 180px 且**可拖拽调宽**(`resizable`)。**按下行编辑后只剩「保存 / 取消」**,保存或取消后恢复初始按钮。 - **工具栏分工**:主表**顶部**只有「保存 / 新增行 / 刷新」(筛选时附带「清除筛选」和右上角语言选择);**每页条数 / 上一页 / 页码 / 下一页 / 状态都在底部工具条**,主表底部不再出现提交按钮。「保存」= **保存全部改动**(主表及所有级联子表的新增/修改,默认选中所有新增行,便于批量保存),不再使用旧的「提交选择」入口。子表只有一条工具条,按同样规则只放分页区与「新增行」。 - **主从表(Master-Detail)**:选择列后追加展开列。有子表数据的行显示 ▶,点击展开(变 ▼)后在该行下方挂载一个**完整的子表 SuperList**(自带翻页/排序/表头筛选/选择提交/行编辑/复制新增/行删除);无子表数据的行显示 `+`,点击后展开并追加一行处于编辑态的空白子行。展开时会拆开该行涉及的合并单元格,收起后自动重新合并。 - **子表层级无限制**:子表实例自身同样带 `child` 配置,因此可以一层层继续展开(组件不设层级上限)。演示数据提供 **0 级 / 1 级 / 2 级子表**三种情况(另有少量 3 层),箭头右侧在 **2 层及以上时显示层数徽标 `(2)`**;删除带多层子表的行会提示将删除整棵子树,后端按层级递归级联删除。 - **级联删除**:主表行删除前弹窗确认(提示将连带删除 N 条子表数据),确认后由后端一次性删除主行及其全部子行。 - **展开区的视觉层级**(参照 AG Grid full-width detail row 的思路):子表是一张**左右内缩、圆角带阴影的卡片**,**内联铺在展开行下方、横跨整个表格宽度**——从最左侧(展开按钮那一列)开始,一直覆盖到滚动区右边缘。实现上,点击展开按钮后主表从该行被拆成**上下两个行组**:两个行组都保留原有的**冻结列(锁定列)**效果,中间空出的整宽区域专门放子表卡片,**该区域没有主表的冻结列效果**;主表当前行下方的所有数据行整体下移让位,卡片随主表自身的竖向滚动条一起滚动,因此不会被主表可视高度裁切。卡片与表格左右各拉开 14px(`childInset`);展开态的主行保持淡蓝底 + 首列强调条,标题写明「「姓名」的子表数据」;高度**按内容自适应**(子表只有 1~2 行时不会留下大片空白)。 - **子表自带冻结列与横向滚动条**:子表卡片内部的子表格同样带有**自己的冻结列效果和自己的横向滚动条**,该滚动条**只联动子表自身的数据**,不会带动主表横向滚动;在子表里再点展开按钮,孙表也按同样方式布局(子表行区同样被拆成上下两半,中间放全宽孙表卡片)。多层嵌套规则完全一致。 - **顶部 + 底部镜像工具栏**:滚动到底部也能直接操作。 - **分页按需出现**:只有数据**超过一页**时才显示「上一页 / 下一页 / 页码」;单页时工具栏只留行数信息与每页条数(子表同理)。 - **子表与主表视觉分层**:子表的**元素尺寸与主表完全一致**(行高、字号、按钮、工具条都不缩放),只换**配色**——表头淡色底、斑马纹、靛蓝主色(第 1 层)/ 青色(第 2 层)/ 琥珀(第 3 层),子表卡片顶部还有一条同色强调条;颜色越深层级越深,绝不会和主表的蓝色混在一起。若确实想让子表更紧凑,可在 `child` 里显式传 `dense: true`(行高 26px)。 - **子表只保留一个顶部工具条**:子表格**不再渲染底部工具条**,也不显示「保存」和**语言下拉列表**(这两样只有主表有;子表语言自动跟随主表切换);行数只在卡片标题「「xxx」的子表数据 共 N 行」出现一次,子表工具条在单页时连页码也一并隐藏,多页时只显示「第 x / y 页」+ 翻页器,并在页码区域放「新增行」按钮(标签与主表一致)。布局规则与主表一致:分页类控件在工具条里,动作类按钮(保存)只在主表顶部。 - **嵌套高度自适应**:展开子表时卡片按内容伸缩(算式包含卡片自身的标题栏/内边距/边框 + 子表的工具条/表头/所有数据行,并留少量余量,因此**当前页所有行都能完整显示**,不会被裁掉);**在子表里再展开子表,父卡片会随之增高**(额度 = 自身预算 + 已展开子卡片高度),子表数据减少或收起子卡片时父卡片同步缩回,不会出现“装不下”或大片空白。 - **数据区高度自动伸缩 + 滚动条精确联动**:主表数据区高度**按内容计算**——一页 10 行(或更少)且没有展开子表时,数据区正好等于这些行的高度,**不出现竖向滚动条**;点开子表后数据区**自动增高**把卡片完整展示出来(只要还没超过挂载容器能给的高度),此时依然没有滚动条;当展开的卡片越来越多、行 + 卡片总高超过挂载高度时,数据区就停在那个高度上并出现**竖向滚动条**,滚动范围与内容一一对应(不裁切、底部不留空白);收起任一子表时数据区同步缩回、滚动条随之变小或消失,空间精确回收。计算方式:JS 量出控制项中除数据区以外的高度(工具条 + 表头行 + 边框内边距),用挂载容器可用高度减去它得到数据区的 max-height(见 `fitViewport()`)。子表卡片本身仍按自身内容适配,不参与这套视口计算。 - **多语言**:中文 / 繁體中文 / 日本語 / English / Français / 한국어 / Latina / العربية,右上角切换,阿拉伯语自动 RTL。 - **设置持久化**:每页行数、排序、语言、列顺序、列宽(仅当前浏览器的 localStorage,不随服务端同步)、锁定列数记忆到 `localStorage`,刷新后恢复。 - **窗口自适应**:CSS 驱动,随浏览器窗口自动适配。 - **扁平化 UI**:基于 CSS 变量的统一配色,无重阴影。 - **可销毁**:`destroy()` 移除全局监听并卸载 DOM。 ## 技术栈 - 前端:原生 JavaScript(`class SuperList`),无框架、无构建、无前端依赖。 - 后端:Node.js 内置 `http`,零第三方依赖。 ## 目录结构 ``` superlist/ ├── server.js # Mock 后端 + 静态文件服务(零依赖) ├── package.json └── public/ ├── index.html # 演示页(列配置 + 挂载) ├── superlist.js # SuperList 组件(class) ├── superlist.css # 扁平化样式 └── i18n.js # 多语言配置(window.SuperListI18n) ``` ## 快速开始 无需安装依赖,只需 Node.js: ```bash npm start # 或 node server.js ``` 然后打开 。 自定义端口: ```bash PORT=8080 node server.js ``` > 修改前端文件后强刷浏览器(Ctrl/Cmd + Shift + R)即可;静态资源响应带 `Cache-Control: no-cache`。 ## 使用方式 ```js new SuperList({ mount: '#superlist', // CSS 选择器或 DOM 元素(必填) apiUrl: '/api/list', // 列表接口 selectionSubmitUrl: '/api/selection',// 选择提交接口 pageSize: 20, // 每页行数(默认 20,上限 1000) frozenCount: 5, // 锁定列数(含选择框/行号;最小 2) mergeFields: ['category'], // 需要竖向合并的字段 filterValuesUrl: '/api/filter-values', // 表头筛选候选值接口 primaryKeys: ['name', 'department'], // 主键列:行编辑时保持只读(默认无) deleteFields: ['name', 'category', 'department'], // 行删除时随 id 一起提交的标识字段(默认取 primaryKeys) rowSaveUrl: '/api/row/save', // 行编辑提交(仅变更字段,提交前做字段校验) rowCreateUrl: '/api/row/create', // 复制新增提交 rowDeleteUrl: '/api/row/delete', // 行删除(主表行级联删除子表) childHeight: 320, // 子表卡片最大高度(实际高度按内容自适应收缩) childInset: 14, // 子表卡片左右内缩(px) childDepthField: 'childLevels', // 行上表示"下方还有几层子表"的字段(>=2 时显示徽标) child: { // 可选:配置后每行出现展开列 apiUrl: '/api/children', // 子表列表 GET ?parentId=&page=&pageSize=... idsUrl: '/api/child-ids', // 子表「全选」用的 id 列表 rowsUrl: '/api/rows', selectionSubmitUrl: '/api/selection', submitFields: ['name', 'birthDate', 'lastLogin', 'amount'], primaryKeys: ['department'], // 子表只读主键列 mergeFields: ['category'], // 子表也可合并 pageSize: 5, frozenCount: 5, // 冻结到操作列为止 // dense: true, // 可选:子表也走紧凑行高(默认不传 = 与主表同尺寸) columns: [ ... ] // 子表列(与主表列类型完全一致) }, submitFields: ['name', 'birthDate', 'lastLogin', 'amount'], // 随选择一起提交到后端的行字段 idsUrl: '/api/ids', // 全量 id(「全选」模式下补全行内容用) rowsUrl: '/api/rows', // 按 id 取行内容 storageKey: 'superlist:#superlist', // 持久化命名空间(默认 superlist:) columns: [ /* 见下 */ ] }); ``` ### 列定义 ```js { key: 'name', // 数据字段名 title: '姓名', // 表头文字(无 titleKey 时使用) titleKey: 'col.name', // 表头多语言键(优先) width: 120, // 列宽(px) sortable: true, // 是否可排序 resizable: true, // 是否可拖拽调宽 type: 'data', // data|select|rownum|date|datetime|number|button|link labelKey: 'col.actionLabel', // button/link 单元格文字的多语言键 href: '#' // link 类型专用 // —— 字段校验规则(仅对被修改过的值生效)—— required: true, // 不能为空 min: 0, max: 100, // 数值/数字列取值区间 maxLength: 12, // 最大字符数 pattern: '^[^@\\s]+@[^@\\s]+\\.[a-zA-Z]{2,}$', // 正则 patternMessage: '邮箱格式应为 name@example.com' // 自定义错误原因 } ``` - `type` 可选:`data`(默认)、`date`、`datetime`、`number`(行内可编辑)、`button`、`link`(交互单元格)。`select`/`rownum` 由组件内部生成,位于最前且始终锁定。 - `filterable: false` 可关闭某列的表头筛选(无 `key` 的列默认不可筛选)。 - 内置默认规则随列的取值类型自动生效:`number` 必须是数字、`date` 必须是 `YYYY-MM-DD` 且为真实日期、`datetime` 必须是 `YYYY-MM-DD HH:mm`;演示里主表给 `city`(required + maxLength)、`score`(0~100)、`email`(邮箱正则),子表给 `age`(18~65)等加了额外规则。 - 指标列可复用同一个 `titleKey`(如 `col.metric`),由组件注入序号占位符 `{n}`。 ### 功能开关:配置了就启用,没配置就不出现 SuperList 的每一项后端能力都对应一个 URL 配置项。**给了 URL 才有对应 UI,不给就整个功能不渲染**,不需要为了“关掉某个功能”去改代码: | 能力 | 配置项 | 未配置时的表现 | | --- | --- | --- | | 列表数据 / 分页 / 排序 | `apiUrl` | (必需,无法关闭) | | 表头筛选(漏斗按钮) | `filterValuesUrl` | 表头不出现漏斗按钮 | | 跨页选择 + 提交 | `selectionSubmitUrl` | 工具栏不出现「提交到后端」;**子表一律不显示该按钮**(只有主表有) | | 行编辑 / 行保存 | `rowSaveUrl` | 操作列不出现「行编辑 / 保存」 | | 复制新增 | `rowCreateUrl` | 不出现「复制新增」 | | 新增行(工具条按钮) | `rowCreateUrl` | 不出现「新增行」按钮 | | 行删除 | `rowDeleteUrl` | 不出现「行删除」 | | 主从表(展开列) | `child` | 不出现展开列;`child` 内没配 `rowCreateUrl` 时,无子数据的行不出现 `+` | | 多语言选择器 | `langs` | 只传一种语言时选择器自动隐藏 | > 行操作列是“整列按需存在”的:三个行 URL 都没配时,`type: 'button'` 的列会从列模型里去掉,不会留下一个空白列。 ### 其它可调配置 | 配置项 | 默认 | 说明 | | --- | --- | --- | | `pageSize` | `20` | 初始每页行数 | | `pageSizeOptions` | `[10, 20, 50, 100]` | 「每页条数」下拉的候选项 | | `frozenCount` | `3` | 冻结列数(含选择框/行号,最小 2) | | `dense` | `false` | 紧凑密度(行高 26px、更小字号/按钮)。**子表默认不开启**,与主表同尺寸;需要时在 `child` 里显式传 `dense: true` | | `lang` | `langs[0]` | 初始语言 | | `messages` | 内置五国语 | 自定义 / 覆盖文案(见 Sample 7) | | `storageKey` | `superlist:` | 持久化命名空间;**改名 = 重置用户记住的列顺序/列宽/页大小** | | `childHeight` / `childInset` | `300` / `12` | 子表卡片展开瞬间的占位高度 / 左右内缩。卡片高度随后按内容精确适配(当前页所有行完整可见);内容超过主表可视区时由**主表竖向滚动条**滚动查看;更深层级的子表默认继承该值 | | `childDepthField` | `childLevels` | 行上“下方还有几层子表”的字段名(≥2 显示徽标) | | `onChildCount(n)` | — | 子表行数变化回调(同步主行 ▶/+ 之外的自有状态) | | `onLayoutChange()` | — | 本表内容高度变化回调(嵌套展开/收起、增删行、翻页) | ### 实例方法 / 可覆写钩子 - `setLang(code)`:切换语言(同步更新表头、按钮/链接、工具栏、状态,并处理 RTL)。 - `destroy()`:移除全局监听、清理拖动残留、卸载 DOM。 - `getSelectionRule()`:读取当前选择规则(`{ mode, selectedIds | excludedIds }`),方便自己做提交。 - `t(key, vars)`:取当前语言文案;新增语言时最常用的扩展点。 - `loadData()`:重新拉取当前页(翻页/筛选/保存后都会调用)。 - 子类化即可定制的渲染钩子:`makeRowActions()`(行操作按钮)、`makeExpander()`(展开箭头)、`makeBodyCell()`(单元格内容)、`makeHeadCell()`(表头)、`validateValue()`(字段校验规则)、`makeToolbar()`(工具栏)。用法见 Sample 3~6。 ## 配置还是改代码?(评估结论) **原则:能用一个值说清楚的,就做成配置;需要写逻辑的,就改成代码,并且把改的位置固定下来。** | 需求 | 推荐做法 | 理由 | | --- | --- | --- | | 数据源、分页、排序、冻结列、列宽/顺序 | ✅ 配置 | 本来就是数据驱动的 | | 开关某类功能(提交/编辑/筛选/子表) | ✅ 配置(给不给 URL) | 比加一堆布尔开关更直观 | | 字段校验规则 | ✅ 配置(列级 `required/min/max/maxLength/pattern`) | 声明式,一眼看懂 | | 校验提示文案、新增语言 | ✅ 配置(`messages`)或直接改 `i18n.js` | 少量文案改文件更痛快 | | 新增/删除行操作按钮(如“审批”“导出”) | ✏️ 改代码:覆写 `makeRowActions()` | 按钮的点击逻辑必须写代码,配置只会更绕 | | 自定义单元格(进度条、头像、标签、彩色状态) | ✏️ 改代码:覆写 `makeBodyCell()` | 属于展示逻辑,配置表达不了 | | 跨字段校验(如“结束日期 ≥ 开始日期”)、异步唯一性校验 | ✏️ 改代码:覆写 `validateValue()` | 单列配置描述不了字段间关系 | | 工具栏加按钮、改提交 payload 结构 | ✏️ 改代码:`makeToolbar()` / `submitSelection()` | 与业务接口强相关 | | 每页行数上限(防呆) | ✏️ 改代码:构造函数顶部 `MAX_PAGE_SIZE` | 一次性安全阀,没必要暴露 | | 配色、圆角、间距、行高 | ✏️ 改 CSS:`superlist.css` 里的 CSS 变量 | 主题属于样式层,改变量比改 JS 配置自然 | ## Sample ### 1. 最小只读列表(无编辑、无提交、无筛选、无子表) ```js new SuperList({ mount: '#list', apiUrl: '/api/list', pageSize: 20, columns: [ { key: 'name', title: '姓名', width: 120, sortable: true }, { key: 'city', title: '城市', width: 100 } ] }); // 结果:只有排序 + 分页(超过一页才出现翻页器),没有任何操作按钮。 ``` ### 2. 只读列表 + 跨页选择提交(能勾选、能提交,但不能改数据) ```js new SuperList({ mount: '#list', apiUrl: '/api/list', selectionSubmitUrl: '/api/selection', // 给了它才有「提交到后端」 submitFields: ['name', 'email'], idsUrl: '/api/ids', // 「全选」模式需要 rowsUrl: '/api/rows', // 未加载过的行补内容 columns: [ { key: 'name', title: '姓名', width: 120, sortable: true }, { key: 'email', title: '邮箱', width: 220 } ] }); ``` ### 3. 增一个业务按钮(覆写 `makeRowActions`) ```js class MyList extends SuperList { makeRowActions(editing, rid) { const wrap = super.makeRowActions(editing, rid); // 保留 行编辑/保存/取消/复制新增/行删除 if (editing) return wrap; const btn = document.createElement('button'); btn.type = 'button'; btn.className = 'sl-cell-btn sl-cell-btn--ghost'; btn.textContent = '审批'; btn.addEventListener('click', async () => { await fetch('/api/approve', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: rid }) }); this.loadData(); }); wrap.lastElementChild.appendChild(btn); // 放到第二行(复制新增 / 行删除 那一行) return wrap; } } new MyList({ mount: '#list', apiUrl: '/api/list', rowSaveUrl: '/api/row/save', columns: [/* ... */] }); ``` ### 4. 自定义单元格(状态徽标 + 进度条) ```js class MyList extends SuperList { // 签名与组件内部一致:makeBodyCell(c, i, row, idx, globalIndex, rid) makeBodyCell(c, i, row, idx, globalIndex, rid) { if (c.key === 'status') { const td = document.createElement('td'); const tag = document.createElement('span'); tag.className = 'sl-cell-btn sl-cell-btn--ghost'; tag.textContent = row.status === 'active' ? '启用' : '停用'; td.appendChild(tag); return td; } if (c.key === 'score') { const td = document.createElement('td'); const bar = document.createElement('div'); bar.style.cssText = 'height:6px;border-radius:3px;background:#e5e7eb;overflow:hidden'; const inner = document.createElement('div'); inner.style.cssText = 'height:100%;width:' + row.score + '%;background:#1677ff'; bar.appendChild(inner); td.appendChild(bar); return td; } return super.makeBodyCell(c, i, row, idx, globalIndex, rid); // 其它列走默认渲染 } } ``` ### 5. 跨字段校验(覆写 `validateValue`) ```js class MyList extends SuperList { validateValue(c, value, baseline, row) { const msg = super.validateValue(c, value, baseline, row); // 保留列级规则 if (msg) return msg; if (c.key === 'endDate' && row.startDate && String(value) < String(row.startDate)) { return '结束日期不能早于开始日期'; } return ''; } } // 触发点:行保存 / 顶部「保存」(批量保存全部改动);翻页不再校验。错误依旧显示在字段下方。 ``` ### 6. 主从表(含无限层级) ```js const childCfg = { apiUrl: '/api/children', // GET ?parentId=&page=&pageSize=&sortField=&sortOrder=&filters= idsUrl: '/api/child-ids', rowsUrl: '/api/rows', selectionSubmitUrl: '/api/selection', rowSaveUrl: '/api/row/save', rowCreateUrl: '/api/row/create', rowDeleteUrl: '/api/row/delete', submitFields: ['name', 'amount'], primaryKeys: ['department'], pageSize: 5, frozenCount: 5, // dense: true, // 可选:子表也走紧凑行高;默认不传 = 与主表同尺寸,只换配色 columns: [ { key: 'name', title: '子项', width: 140 }, { type: 'button', title: '操作', width: 180 } ] }; const level1 = Object.assign({}, childCfg); level1.child = Object.assign({}, childCfg); // 子表还能再展开 level1.child.child = Object.assign({}, childCfg); // 演示到第 3 层为止 level1.child.child.child = null; new SuperList({ mount: '#list', apiUrl: '/api/list', selectionSubmitUrl: '/api/selection', rowSaveUrl: '/api/row/save', rowCreateUrl: '/api/row/create', rowDeleteUrl: '/api/row/delete', childHeight: 320, childInset: 14, child: level1, columns: [ { key: 'name', title: '姓名', width: 120 }, { type: 'button', title: '操作', width: 180 } ] }); // 行上的 childCount / childLevels 决定 ▶ / + / ▶(2):箭头右侧的 (n) 表示下面还有 n 层。 ``` ### 7. 自定义文案 / 新增一种语言 ```js // 方式一:只覆盖几条文案(其余沿用内置五国语) new SuperList({ mount: '#list', apiUrl: '/api/list', lang: 'zh', messages: { zh: { submit: '提交所选', rowEdit: '编辑此行' } // 只写要改的键 }, columns: [/* ... */] }); // 方式二:新增语言(记得把选择器也放开) new SuperList({ mount: '#list', apiUrl: '/api/list', langs: [ { code: 'zh', name: '中文' }, { code: 'fr', name: 'Français' } ], messages: { zh: { /* ... */ }, fr: { submit: 'Envoyer', prev: 'Précédent', next: 'Suivant' /* ... */ } }, columns: [/* ... */] }); ``` ### 8. 换主题(改 CSS 变量,不动 JS) ```css /* superlist.css 顶部已经是一套变量,直接覆盖即可 */ :root { --primary: #7c3aed; /* 主色:按钮、链接、选中态 */ --primary-hover: #8b5cf6; --border: #e5e7eb; --surface: #ffffff; --surface-muted: #f6f7fb; --text: #1f2937; --radius: 6px; } /* 子表层级配色同理:.superlist.sl-child / .sl-child--d2 / .sl-child--d3 */ ``` ### 9. 每页条数候选项 ```js new SuperList({ mount: '#list', apiUrl: '/api/list', pageSize: 25, pageSizeOptions: [25, 50, 100], // 下拉只出现这三项 columns: [/* ... */] }); ``` ## 后端接口 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/list?page=&pageSize=&sortField=&sortOrder=&filters=` | 返回 `{ total, page, pageSize, rows }` | | GET | `/api/filter-values?field=&filters=` | 某列的候选值 `{ values: [{ value, count }] }` | | GET | `/api/ids?filters=` | 返回过滤后的结果行 id `{ ids: [...] }` | | POST | `/api/rows` | 按 id 取行内容 `{ ids, fields }` → `{ rows: [{ id, ...fields }] }` | | POST | `/api/row/save` | 保存单行的**变更字段** `{ id, changes }` → `{ ok, id, row }` | | POST | `/api/row/create` | 新增一行 `{ afterId, row, parentId? }` → `{ ok, id, parentId, row }`(插在 `afterId` 之后;带 `parentId` 则作为子表行) | | POST | `/api/row/delete` | 删除一行并级联删除其子行 `{ id }` → `{ ok, deleted, children }` | | GET | `/api/children` | 子表分页列表 `?parentId=&page=&pageSize=&sortField=&sortOrder=&filters=` → 结构与 `/api/list` 相同 | | GET | `/api/child-ids` | 某个主表行的全部子行 id `?parentId=` → `{ ids: [...] }` | | GET | `/api/filter-values` | 额外支持 `parentId`,用于子表的筛选候选值 | | POST | `/api/selection` | 提交选择规则 + 行内容,返回 `{ ok, mode, count, rowsReceived }` | | GET | `/api/selection` | 返回最近一次提交(含 `rows`) | 选择规则 + 行内容(POST body): ```json { "mode": "all", "excludedIds": [1, 2, 3], "fields": ["name", "birthDate", "lastLogin", "amount"], "rows": [ { "id": 1, "name": "李敏", "birthDate": "1991-02-02", "lastLogin": "2024-02-02T01:03", "amount": 137 } ] } // 或 { "mode": "partial", "selectedIds": [4, 5, 6], "fields": [...], "rows": [...] } ``` 筛选条件 `filters`(URL 参数为 JSON,列间 AND、列内 OR): ```json [{ "field": "category", "values": ["华东"] }, { "field": "department", "values": ["研发", "市场"] }] ``` `/api/filter-values` 计算候选值时会忽略**该列自身**的筛选(只应用其他列),与 Excel 一致,方便在已有结果上继续放宽或收紧;`/api/list` 与 `/api/ids` 都会应用全部筛选。 后端按「当前数据」解析规则并仅返回数量,不会把全量 id 回传客户端;`rows` 为前端随规则一并提交的行内容(`fields` 由前端 `submitFields` 决定),后端会打印前 3 行便于验证。 ## 多语言(i18n) 翻译字典集中在 `public/i18n.js`: ```js window.SuperListI18n = { zh: { 'col.name': '姓名', /* ... */ }, en: { 'col.name': 'Name', /* ... */ } // ... }; ``` - 组件通过 `t(key, vars)` 取词,缺失时回退:当前语言 → 中文 → key 本身。 - **新增语言**:在 `i18n.js` 增加一个语言对象,并在 `superlist.js` 构造函数的 `this.langs` 数组中追加 `{ code, name }`(`name` 用该语言母语书写)。 ## 主从表 数据模型:后端只有一张行表,主行 `parentId === null` 且带 `childCount`(当前子行数),子行 `parentId` 指向主行。因此两级共用同一套行编辑/新增/删除接口,只有列表查询按 `parentId` 区分作用域(`/api/list` 主表、`/api/children` 子表)。 - 展开列位于选择列之后:有子行显示 ▶,无子行显示 `+`。 - 子表区域由占位行(两个 pane 各一行)在行下方预留高度,真正的子表实例以浮层渲染,**横跨锁定区与滚动区**,滚动时与所在行吸附对齐。 - 卡片高度按内容自适应;子表内部再展开子表时,父卡片会向上“长高”(自身预算 + 已展开子卡片高度),数据变少或收起时同步缩回。 - 分页控件(上一页/下一页/页码)仅在 `total > pageSize` 时渲染;子表用 `sl-child` 变体配色(按层级换主色 + 斑马纹 + 淡色表头)。 - 展开 → 该行的合并单元格自动拆开;收起 → 按现有值重新合并。 - 翻页 / 排序 / 筛选后,已不在当前页的行会自动收起,避免浮层错位。 - 主行删除先弹确认(含子行数),再由后端执行级联删除;子表内新增/删除行会把最新行数回写到主行 ▶/`+` 形态。 ## 交互说明 - **排序**:点击表头。 - **筛选**:点击表头漏斗按钮 → 勾选值(可搜索)→ 确定;`Esc` 或点击外部关闭(等价于取消);表头按钮高亮表示已筛选,工具栏「清除筛选 (n)」一键清空全部。 - **行编辑**:点「行编辑」→ 该行所有非主键列变成输入框,操作列同时变成**「保存 / 取消」两个按钮** → 点「保存」提交(带校验,失败则停在编辑态);点「取消」放弃改动并恢复成「行编辑 / 复制新增 / 行删除」。未做任何修改时点「保存」只会退出编辑态,不会请求后端。主键列不可编辑;**新增/复制产生的未保存行默认勾选、可手动取消**,保存后获得真实 id 并继续参与选择规则。 - **行保存的提交内容**:请求体同时带两部分——`changes` 只包含**值真正发生过变化的字段**(局部更新用),`row` 是**当前整行的完整快照**(主键列和未修改字段都在,内部字段以下划线开头的已剔除),后端按需取用。新增行(复制新增 / 工具条新增行)本来就是整行提交。 - **行删除的提交内容**:`{ id, keys }`,其中 `keys` 是 `deleteFields`(默认取 `primaryKeys`)这些标识字段的当前值,例如 `{ id: 12, keys: { name: '李敏', category: '华东', department: '市场' } }`,后端可据此复核后再删。 - **复制新增**:点「复制新增」→ 下方出现相同数据的一行且已是编辑态 → 改值 →「保存」写入后端。整行属于新内容,提交前会对整行做校验。 - **新增行(工具条)**:主表顶部「保存」按钮**右边**有「新增行」;子表在**页码区域**有「新增行」(标签一致)。点击后把一行空白行**追加到整个数据集的最末尾(最后一页之后)**,并自动跳转到那一页、直接进入编辑态;翻看其它页时该行寄存(不显示),回到最后一页又出现。填完点「行保存」即写入后端(未保存的新增行会一直保留,直到手动删除或刷新页面)。按钮只有在配置了 `rowCreateUrl` 时才出现。**新增行默认被勾选参与「保存」的批量提交,可手动取消勾选。** - **新增行导致翻页**:本地新增的行也会计入总行数,因此**分页器的页码会随之变化,并自动跳到放得下新行的那一页——即整个数据集的最后一页**(新行固定追加在最后一页最后一条服务端数据之后;若最后一页原本就是满的,则新开一页,新行独占该页);同时**键盘焦点自动落到新行的第一个可输入格**(主表与子表行为一致)。复制新增同理。 - **未保存的新增行**:多行「复制新增」/「+ 追加子行」产生的未保存行,**在保存其中某一行、翻页、或执行其他行级操作后依然留在原位置**(保存在内存里,锚点行在当前页时按插入位置挂回;锚点行不在当前页时先“寄存”,回到那一页再出现),直到你手动「行删除」或刷新页面;刷新页面后按预期清空。 - **字段校验**:改错值后字段下方立即出现红色原因(输入时就校验);带着错误点「行保存」不会产生请求,原因写在状态条里。 - **翻页不再校验**:翻页 / 换页大小**直接跳到目标页,不做任何字段校验**,也不会因为字段有错而阻断翻页。字段校验只在顶部「保存」(批量保存全部改动)和「行保存」按下时触发——带着错误点这两个按钮才不会产生请求(错误写在状态条里)。 - **提交前校验**:点「提交到后端」先校验所有被勾选且有改动的记录,失败时弹出 div 清单(行号 / 字段 / 内容 / 错误原因),全部改正后再提交。 - **展开子表**:点展开列的 ▶;无子表的行显示 `+`,点击后展开并追加一行处于编辑态的空白子行。子表是完整列表:可独立翻页、排序、表头筛选、行编辑/复制新增/行删除,但**只有一个顶部工具条、没有「保存」按钮**(保存只在主表;子表语言跟随主表);行数在卡片标题显示一次,单页时连页码也不显示。标题写明所属主行,`↻` 刷新、`▴` 收起。再点 ▼ 也收起,收起后合并单元格自动复原。子表卡片高度按行数自适应;子表内新增/删除行后主表行的行数与按钮形态同步。 - **多层子表**:子表行同样可以展开自己的子表,层级不限;箭头右侧 `(n)` 表示该行下还有 n 层(仅 2 层及以上显示)。演示数据包含:无子表(`+`)、仅一层(`▶`)、两层(`▶(2)`)以及少量三层(`▶(3)`)。 - **行删除**:点「行删除」→ 有子表的行弹窗提示将级联删除(多层子表会提示删除整棵子树)→ 确认后后端级联删除该行及其全部下级。 - **字段属性校验(提交前门禁)**:**只校验被修改过的字段**(与后端下发原值比对),类型/长度/范围/正则任一不通过就在该字段内容下方显示红色原因,并阻止本次请求。触发点有两个:① 行保存(含复制新增/追加子行的新建,整行新建会校验整行必填);② 顶部「保存」按钮(批量保存全部改动,校验主表及所有级联子表的脏行,含未保存新增行)。**翻页不再触发表单校验,也不会阻断翻页**;错误信息存于实例中,改回来后即时消失(输入时即单字段复校验)。 - **错误清单弹窗(div 方式)**:点「提交到后端」若校验失败,弹出遮罩层而非原生 alert,表格列出 **行号 / 字段 / 内容 / 错误原因**(Esc、点遮罩、关闭按钮均可关闭)。 - **调宽**:拖动表头右边缘。 - **重排 / 改锁定**:拖动表头到目标位置;拖入锁定区即锁定,拖出即解锁;拖动中按 `Esc` 取消。 - **选择**:勾选行复选框;表头复选框为全选/全不选(跨页规则)。 - **底部工具栏**:与顶部一致,便于滚动到底部后操作。 ## 持久化 以下设置保存在 `localStorage`(键为 `storageKey`):`pageSize`、`sortField`、`sortOrder`、`lang`、`colOrder`、`colWidths`、`frozenCount`。 ## 说明 - 数据为演示用确定性 Mock(见 `server.js` 的 `genData`),非真实业务数据。 - 项目 `private: true`,仅作演示/学习用途。