@canvas-components/list-table 0.3.17 → 0.3.19

package/README.md

@@ -2,6 +2,52 @@
 
 `@canvas-components/list-table` 是整个项目的纯原生 Canvas 表格核心包，不依赖 React，可直接在 DOM 容器中创建高性能表格实例，也可作为适配层的底层引擎使用。
 
+## 多列排序
+
+参照 AntD 的列配置，设置 `sorter: { multiple: 数值 }` 开启该列的多列排序，数值越大越优先；同优先级按加入排序的先后顺序执行。
+
+```ts
+const columns = [
+  { title: "部门", dataIndex: "dept", sorter: { multiple: 3 } },
+  { title: "绩效", dataIndex: "score", sorter: { multiple: 2 } },
+  { title: "姓名", dataIndex: "name", sorter: { multiple: 1 } },
+];
+```
+
+- 点击排序图标依次切换升序、降序、取消，仅修改当前列；右键“取消排序”同样只清除当前列，“重置排序”清除全部条件。
+- `multiple` 相同时，先点击加入排序的列优先；切换升降序不改变次序，取消后重新加入排在同权重列的最后。缓存恢复保留此顺序，未点击的默认排序按列配置顺序。
+- `sortValueGetter(record)` 用于提取数字或字符串排序值，支持状态权重映射、数值计算等；`sorter.compare(a, b)` 则直接比较两条原始记录，优先于 `sortValueGetter`。按升序返回负数、零或正数，降序由表格自动反转；返回 `0` 或 `NaN` 时继续比较下一列，全部相等保留原始顺序。比较函数需保持纯函数并满足排序一致性。
+- 自定义 `compare` 不会序列化到 Worker，支持闭包，采用可取消的主线程分片排序；同一组排序中的普通列仍可使用 Worker。比较函数抛出异常时进入查询错误处理，不会静默改用默认规则。单次比较函数本身仍需快速返回。
+- 未配置 `multiple` 的列保持单列交互：开始排序时替换其他排序条件。`sorter: true` 开启单列排序，也可继续使用 `allowSort` 控制排序能力。
+- `defaultSortOrder` 可与 `sorter.multiple` 配合设置多列默认排序，父表和嵌套子表独立维护各自的排序条件。
+- 排序状态统一使用数组：`[{ key, order, priority }]`，未排序为 `[]`；`query.onChange` 第三个参数也是数组：`[{ columnKey, field, order, priority }]`。`extra.sorter`、`extra.sorters` 均返回排序状态数组。不转换旧单列缓存数据。
+- 本地同步排序、Worker 排序及无 Worker 分片回退遵循相同优先级；服务端模式由业务端按回调数组执行排序。
+- 基础示例中已配置部门、绩效、姓名三列，可连续点击它们验证组合排序。
+
+```ts
+const scoreColumn = {
+  title: "绩效",
+  dataIndex: "score",
+  sorter: {
+    multiple: 2,
+    compare: (a, b) => a.score - b.score,
+  },
+};
+```
+
+## 图片复制与导出
+
+右键菜单「复制」支持「复制为图片」，「导出」支持「导出图片」，均提供三个范围：
+
+- 所有区域：重新绘制当前已加载、经过排序过滤的全部数据及可见列，包含表头和已开启的汇总行。服务端分页不会额外请求尚未加载的数据。
+- 选中区域：绘制当前单元格、拖拽矩形选区、整行或整列选区，不包含表头和汇总行；没有选区时不可用。
+- 视口区域：截取当前表格画布，保留当前滚动位置及可见效果，不包含分页器、工具栏或右键菜单。
+
+图片格式为 PNG。复制需要浏览器支持图片剪贴板，且通过 HTTPS 或 localhost 访问；下载不依赖剪贴板权限。
+图片包含尚未加载的图片内容时，最多等待 10 秒。跨域资源禁止读取、编码失败或尺寸过大会明确提示，不会静默生成不完整文件。
+为防止内存溢出，输出图片单边不超过 16384 像素，总像素不超过 1600 万（计入缩放及设备像素比）；超过时请缩小选区或使用视口范围。
+「复制」和「导出」仍分别遵循 `contextMenu.features` 的 `copy`、`export` 开关。
+
 ## 功能作用
 
 - 原生 Canvas 表格渲染
@@ -35,6 +81,44 @@ const initialPageSize =
 
 该读取方法也由 `@canvas-components/react-list-table` 导出。
 
+## 本地配置缓存
+
+汇总行右键“汇总方式”中提供“展示汇总方式前缀”，默认勾选。取消后仅显示结果值（如 `173`），勾选时显示 `求和: 173` 等前缀；主表、子表和复制文本使用同一展示规则。列配置可使用 `summary: { type: "sum", showTypePrefix: false }`，该开关随汇总配置缓存，自定义汇总标题不受影响。
+
+配置稳定且唯一的 `storageKey` 后，可在右键通用“缓存到本地”分组中分别设置：列设置、排序、筛选、汇总、对齐、格式（数字、日期、货币等）、表格密度、缩放，以及当前列条件格式，默认全部开启。“列显示”和“条件格式”子菜单不重复提供缓存开关。通用分组中的“列设置”与标题栏“列设置”标题右侧的 Checkbox 共用状态，控制列宽、显隐、固定和顺序；未配置 `storageKey` 时禁用并提示。
+
+关闭某类缓存不会撤销当前页面的操作，只清除该类持久化内容，刷新后使用传入配置；其他类别不受影响。各缓存开关自身也会保存。冻结行、复制、导出等没有对应持久化数据，不提供缓存开关。
+
+可用 `cacheColumnSettings: false` 设置列设置缓存默认关闭；其他类别通过 `cachePreferences` 配置，如 `{ sort: false, filter: false, summary: false, alignment: false, dataFormat: false, density: false, zoom: false }`。未指定默认开启，已保存的用户选择优先。原生实例支持 `setColumnSettingsCache(enabled)`；自定义右键功能列表可通过 `cache` 控制分类缓存分组。
+
+## 按列条件格式
+
+规则通过 `backgroundColor` 和 `textColor` 分别设置背景色与文本颜色，编辑弹窗使用现有颜色选择器并实时预览。文本颜色覆盖当前单元格文字片段的颜色，选中和悬停时仍生效；不修改其他列、表头或汇总行。不提供旧规则文本颜色迁移逻辑。
+
+通用“缓存到本地”分组中的“当前列条件格式”按列控制规则是否持久化，默认开启。关闭后保留当前页面的规则效果，但保存时移除该列已缓存的规则；刷新后只使用代码中配置的初始规则。可通过列属性 `cacheConditionalFormats: false` 设置默认关闭。
+
+单条规则支持新增、删除多个条件，相邻条件之间分别选择“且 / 或”，且优先于或。所有条件比较当前列原始值，命中后使用该规则的样式。例如 `{ id: "score", conditions: [{ operator: "gte", value: 80 }, { relation: "and", operator: "lt", value: 90 }], backgroundColor: "#fff1b8", textColor: "#874d00" }`。每项 `relation` 表示与上一条件的连接关系，首项忽略；删除条件时保留剩余条件携带的关系。未指定时兼容旧的 `conditionRelation`，默认“且”。`conditions` 优先于旧的单条件字段；未配置时兼容原有 `operator/value/endValue`，空条件列表不命中。
+
+右键业务叶子列表头 → **条件格式**，二级菜单以“颜色块 + 规则名称”展示当前列规则，未命名时显示“规则 1”等默认名称，悬停可查看完整名称和条件摘要；并提供“新增规则”“重置条件格式”。点击规则打开编辑弹窗，可修改条件、背景色或删除规则；取消不会改动表格。
+
+规则仅作用于当前列的数据单元格，不修改其他列、表头或汇总行。规则从上到下匹配，首条命中优先。条件背景优先于选中和悬停背景，保留选区边框；校验错误提示仍优先于条件背景。只对绘制中的单元格计算，不预扫描全量数据。
+
+```ts
+const columns = [{
+  key: 'amount',
+  dataIndex: 'amount',
+  title: '金额',
+  conditionalFormats: [
+    { id: 'high', name: '高金额', operator: 'gte', value: 1000, backgroundColor: '#fff1b8', textColor: '#874d00' },
+    { id: 'negative', name: '负数', operator: 'lt', value: 0, backgroundColor: '#ffccc7', textColor: '#a8071a' },
+  ],
+}];
+```
+
+支持 `eq` / `neq`（原始值转文本后比较）、`gt` / `gte` / `lt` / `lte`（数值比较）、`between`（包含上下界，结束值使用 `endValue`）、`contains`（区分大小写）、`empty` / `notEmpty`。空值及非数值不参与数值比较。
+
+配置 `storageKey` 后规则随列设置保存；“重置条件格式”只清空当前列规则，不清除其他样式或其他列规则。自定义右键菜单功能列表时，可通过 `conditionalFormat` 控制该入口。核心包通过 `HeaderContextMenuConfig.conditionalFormats` 和 `onChangeConditionalFormats` 向 UI 适配层提供配置。
+
 ## 分区 CSS 样式
 
 原生 `ListTable` 和 `ReactListTable` 均支持 `styles`。Canvas 区域通过 CSS 属性映射到绘制参数，不创建单元格 DOM，不注入全局样式。
@@ -199,6 +283,8 @@ const options = {
 | `resizable`                 | `boolean`                                                                     | 单列是否允许调整宽度                          |
 | `draggable`                 | `boolean`                                                                     | 单列是否允许拖拽                              |
 | `allowSort`                 | `boolean`                                                                     | 是否开启排序                                  |
+| `sorter`                    | `ListTableSorter<RecordType>`                                                  | `multiple` 指定优先级，`compare(a, b)` 自定义比较 |
+| `defaultSortOrder`          | `"ascend" \| "descend"`                                                      | 默认排序方向，可配合 `sorter.multiple`         |
 | `allowFilter`               | `boolean`                                                                     | 是否开启过滤                                  |
 | `filterOptions`             | `ListTableFilterOption[]`                                                     | 精确过滤选项                                  |
 | `cellType`                  | `ListTableCellContent["type"]`                                                | 内建单元格类型                                |
@@ -370,3 +456,29 @@ scrollbar: {
 - `visible: false`：同时隐藏两轴，优先于单轴设置。隐藏后释放对应槽位，仍可通过滚轮或程序滚动。
 
 配置仅作用于当前 Canvas 表格，不修改全局浏览器滚动条样式。
+
+### 级联选择编辑（Cascader）
+
+`formItemProps.valueType: "cascader"` 使用多列展开的单路径选择器，配置方式参考 Ant Design Cascader。父表和嵌套子表使用相同配置；React 适配包提供编辑界面，原生包仅提供配置与路径格式化，不引入 React。
+
+```ts
+{
+  title: '所属地区', dataIndex: 'region', editable: true, width: 240,
+  formItemProps: {
+    valueType: 'cascader', showSearch: true, allowClear: true,
+    expandTrigger: 'click', changeOnSelect: false,
+    options: [{ label: '浙江', value: 'zj', children: [
+      { label: '杭州', value: 0, children: [{ label: '西湖区', value: 'xh' }] },
+      { label: '停用地区', value: 'disabled', disabled: true },
+    ] }],
+  },
+}
+// 行数据：{ region: ['zj', 0, 'xh'] }
+```
+
+- 值为 `(string | number)[]`，清空将编辑草稿更新为 `[]`，保持编辑状态，可继续选择、失焦提交或按 Escape 取消。默认显示完整标签路径，以 ` / ` 分隔；可用 `displayRender(labels, selectedOptions)` 定制。显式 `format` 优先级更高。
+- `showSearch` 默认 `false`，开启后按完整路径搜索；`expandTrigger` 支持 `click`（默认）或 `hover`。
+- `changeOnSelect` 默认 `false`；开启后点击中间级更新编辑草稿，失焦或 Tab 提交，选择末级立即提交。
+- 方向键在级联菜单中导航，Enter 选择，Escape 取消本次编辑，Tab 切换编辑单元格。
+- 当前支持单路径选择、标准 `label/value/children` 节点，不包含多选、异步加载及自定义字段映射。
+- 文档站“单元格编辑”示例新增“所属地区（级联）”列。