@canvas-components/list-table 0.3.19 → 0.3.20

package/README.md

@@ -2,6 +2,28 @@
 
 `@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: 数值 }` 开启该列的多列排序，数值越大越优先；同优先级按加入排序的先后顺序执行。
@@ -332,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
@@ -459,7 +485,7 @@ scrollbar: {
 
 ### 级联选择编辑（Cascader）
 
-`formItemProps.valueType: "cascader"` 使用多列展开的单路径选择器，配置方式参考 Ant Design Cascader。父表和嵌套子表使用相同配置；React 适配包提供编辑界面，原生包仅提供配置与路径格式化，不引入 React。
+`formItemProps.valueType: "cascader"` 使用多列展开的单选/多选级联选择器，配置方式参考 Ant Design Cascader。父表和嵌套子表使用相同配置；React 适配包提供编辑界面，原生包仅提供配置与路径格式化，不引入 React。
 
 ```ts
 {
@@ -480,5 +506,58 @@ scrollbar: {
 - `showSearch` 默认 `false`，开启后按完整路径搜索；`expandTrigger` 支持 `click`（默认）或 `hover`。
 - `changeOnSelect` 默认 `false`；开启后点击中间级更新编辑草稿，失焦或 Tab 提交，选择末级立即提交。
 - 方向键在级联菜单中导航，Enter 选择，Escape 取消本次编辑，Tab 切换编辑单元格。
-- 当前支持单路径选择、标准 `label/value/children` 节点，不包含多选、异步加载及自定义字段映射。
+- 支持单选末级、单选任意级、多选父级回填和多选末级回填。使用标准 `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` 和自定义字段映射。
+- “单元格编辑”示例新增“树选择（单选）”“树选择（多选）”列。组件内部索引和值处理放在组件目录，不增加公共工具包接口。