@canvas-components/list-table 0.3.18 → 0.3.20

package/README.md

@@ -2,6 +2,74 @@
 
 `@canvas-components/list-table` 是整个项目的纯原生 Canvas 表格核心包，不依赖 React，可直接在 DOM 容器中创建高性能表格实例，也可作为适配层的底层引擎使用。
 
+## 双击表头边界自动列宽
+
+双击表头可拖拽的右边界，按内容自动计算当前列宽；双击左边界则调整左侧相邻列，与拖拽边界归属一致。支持左右固定列及最后一列，沿用右键菜单的内容测量、最小/最大宽度限制与列宽缓存设置。禁用列宽调整的边界和空白选择列等特殊列不响应。
+
+## 内置图标
+
+`{ type: "icon", icon: "EditOutlined", size: 20 }` 可绘制原生图标，完整提供官方 848 个图标（线框、实心、双色），另有 58 个内置短名称图标，包含表头同款排序、过滤、固定图标。
+图标路径统一维护于 `src/rendering/icons/`，供单元格、评分、时间轴和附件功能复用。
+详见 [图标目录与配置](./docs/icons.md)。
+
+## 时间轴单元格
+
+`render` 返回 `{ type: "timeline", items: [{ title: "09:00", content: "订单创建", color: "green" }] }`
+即可绘制原生纵向时间轴；支持自动换行、自动行高、交替布局和倒序。
+详见 [时间轴配置](./docs/timeline.md)。
+
+## 上传单元格
+
+设置 `formItemProps: { valueType: "upload", upload: { action: "/api/upload", multiple: true } }`
+即可使用原生上传编辑器。图片回显缩略图，其他文件显示类型图标和文件名，不依赖 React 组件。
+详见 [上传配置与接口说明](./docs/upload.md)。
+
+## 多列排序
+
+参照 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 +103,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 +305,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"]`                                                | 内建单元格类型                                |
@@ -246,6 +354,10 @@ const options = {
 
 ### XLSX Worker 导出
 
+导出默认先确认文件名称，输入框默认填入配置的名称，后缀单独显示且不可修改。表格选项 `exportOptions: { fileName: "报表", promptFileName: false }` 可跳过弹窗；单次 `exportXlsx({ promptFileName: false })` 可覆盖默认行为。原生接入通过 `ui.onExportNameRequest` 自定义弹窗，未提供时使用浏览器输入框。
+
+当前显示汇总行时，XLSX 默认在全部数据末尾追加汇总行（子表格独立判断）；显式设置 `includeSummary: false` 可排除汇总行，`true` 可强制追加。汇总按导出的全量数据与当前列配置计算。
+
 `exportXlsx()` 默认对 1 万行及以上数据尝试 Worker；现有调用无需修改。表格加载提示会显示已处理行数与文件生成阶段。取值和 `render` 回调仍在主线程执行，工作表构建、文件编码交给 Worker。
 
 ```ts
@@ -370,3 +482,82 @@ 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` 节点；暂不包含异步加载及自定义字段映射。
+- 文档站“单元格编辑”示例新增“所属地区（级联）”列。
+
+多选配置参考 [Ant Design Cascader](https://ant.design/components/cascader-cn/)：
+
+```ts
+formItemProps: {
+  valueType: 'cascader',
+  options: regionOptions,
+  multiple: true,
+  showCheckedStrategy: 'SHOW_PARENT', // 或 'SHOW_CHILD'
+  showSearch: true,
+}
+// 多选值是二维路径数组，例如：[['zj', 'hz', 0], ['js', 'nj', 1]]
+```
+
+- `multiple` 默认 `false`；开启后复选框切换当前节点及其可用后代，父级支持半选。点击分支文案仅展开，点击末级文案可勾选。
+- `showCheckedStrategy` 默认 `SHOW_PARENT`，全部可用子级选中时回填父级路径；`SHOW_CHILD` 回填全部已选末级路径。该策略同时作用于变更回调、输入框和单元格文本。
+- 多选路径以 `；` 分隔回显，`displayRender` 逐条处理路径。禁用节点不参与父子联动，已有禁用值不会被其他分支操作误删。
+- 多选勾选及清空不会退出编辑；失焦或 Tab 提交，Escape 取消。方向键导航，Enter / 空格切换当前选项（搜索输入中的空格仍用于输入）。`changeOnSelect` 仅影响单选。
+- 示例新增“级联单选（任意级）”“级联多选（父级回填）”“级联多选（末级回填）”列。
+
+### 树选择编辑（TreeSelect）
+
+使用 `formItemProps.valueType: 'tree-select'`，配置参考 [Ant Design TreeSelect](https://ant.design/components/tree-select/)。父表和嵌套子表使用同一套编辑配置。
+
+```ts
+{
+  title: '所属部门', dataIndex: 'departments', editable: true, width: 280,
+  formItemProps: {
+    valueType: 'tree-select',
+    multiple: true, // 不传则单选
+    showSearch: true,
+    allowClear: true,
+    treeDefaultExpandAll: true,
+    treeData: [{ title: '组织架构', value: 'root', selectable: false, children: [
+      { title: '生产中心', value: 'production', children: [
+        { title: '织造车间', value: 0 },
+        { title: '检验车间', value: 'inspection' },
+      ] },
+      { title: '停用部门', value: 'disabled', disabled: true },
+    ] }],
+  },
+}
+// 单选值：0；多选值：[0, 'inspection']，不是 Cascader 的路径数组。
+```
+
+- `treeData` 使用 `title/value/children`，`value` 必须在树内唯一；数字 `0` 与字符串 `'0'` 严格区分。`disabled` 禁止选择当前节点，`selectable: false` 用于只能展开的分组。
+- `multiple` 默认 `false`；多选独立切换各个节点，不进行父子联动。单元格和输入框回显节点标题，多选使用 `；` 分隔，显式 `format` 可覆盖单元格显示。
+- `showSearch` 单选默认关闭、多选默认开启，按标题搜索并保留祖先上下文；搜索不修改原展开状态。
+- `treeDefaultExpandAll` 默认 `false`；也可使用 `treeDefaultExpandedKeys` 指定默认展开节点，依据节点的 `key`（省略时使用 `value`）。已选节点的祖先自动展开。
+- 单选选择后提交；多选连续选择不提交，失焦或 Tab 提交。清空单选为 `null`、多选为 `[]`，保持焦点和弹层，可继续选择；Escape 取消编辑。
+- 上下方向键导航，左右方向键展开/收起，Enter 或空格选择。搜索输入中的空格用于输入。
+- 本次实现基础单选与独立多选，不包含 `treeCheckable`、`treeCheckStrictly`、异步加载、`labelInValue` 和自定义字段映射。
+- “单元格编辑”示例新增“树选择（单选）”“树选择（多选）”列。组件内部索引和值处理放在组件目录，不增加公共工具包接口。