@canvas-components/list-table 0.3.11 → 0.3.13

package/README.md

@@ -80,12 +80,29 @@ table.mount();
 | `carouselScroll`   | `ListTableCarouselScrollOptions`                                                       | 自动轮播滚动配置               |
 | `stretchColumns`   | `boolean`                                                                              | 列总宽不足时是否拉伸补齐       |
 | `resizable`        | `boolean`                                                                              | 是否开启列宽拖拽               |
-| `storageKey`       | `string`                                                                               | 列配置、查询、缩放和密度持久化键 |
+| `storageKey`       | `string`                                                                               | 列配置、查询、缩放和密度持久化键 |
 | `draggable`        | `boolean`                                                                              | 是否开启列拖拽排序             |
 | `tableId`          | `string`                                                                               | 表格唯一标识                   |
 | `rowDrag`          | `ListTableRowDragOptions`                                                              | 行拖拽配置                     |
 | `debug`            | `ListTableDebugOptions`                                                                | 调试配置                       |
 
+### 分批加载与服务端汇总
+
+数据仍在异步生成或分批加载时，设置表格顶层属性 `loading: true`。此时汇总行及标题正常显示，统计结果保持空白，也不会计算首批临时数据。完整数据就绪后，将完整 `dataSource` 与 `loading: false` 一起更新，表格自动计算汇总并在完成后统一显示结果。默认值为 `false`，正常的空数据仍可汇总为零。
+
+使用服务端汇总时，通过 `query.summaryValues` 传入以列 `key` 为键的对象或 Map。若数据和汇总分别请求，可保持 `loading: true`，待两者都返回后再设为 `false`；此配置同样支持 React 适配包，外部无需控制汇总计算状态。
+
+```ts
+const options = {
+  dataSource: rows,
+  loading,
+  query: {
+    // 服务端汇总可选；不传则使用本地异步汇总。
+    summaryValues: serverSummaryValues,
+  },
+};
+```
+
 ### 列配置 `ListTableColumn`
 
 | 属性                        | 类型                                                                          | 说明                                          |
@@ -151,6 +168,30 @@ table.mount();
 
 列配置可通过 `settingTitle`、`initialHide`、`hideInSetting`、`disableHide` 约束列设置中的标题、初始显隐和隐藏权限。
 
+### XLSX Worker 导出
+
+`exportXlsx()` 默认对 1 万行及以上数据尝试 Worker；现有调用无需修改。表格加载提示会显示已处理行数与文件生成阶段。取值和 `render` 回调仍在主线程执行，工作表构建、文件编码交给 Worker。
+
+```ts
+const controller = new AbortController();
+table.exportXlsx({
+  fileName: "表格数据",
+  includeSummary: true,
+  worker: "auto", // true：始终尝试；false：使用主线程
+  maxRowsPerFile: 100_000, // 默认十万行；20 列以内无需降低每份行数
+  signal: controller.signal,
+  onError: (error) => console.error("导出失败", error), // 可替换为业务提示
+  onProgress: ({ phase, completedRows, totalRows }) => {
+    console.log(phase, completedRows, totalRows);
+  },
+});
+// 需要取消时调用 controller.abort()。
+```
+
+大数据按行数和单元格预算自动拆成多个独立 XLSX，文件名追加 `_001`、`_002`。每份保留表头，汇总只追加在全部数据末尾。逐份生成、下载并释放，不同时持有全部工作簿。进度包含 `fileIndex`、`fileCount`；可通过 `saveFile(blob, fileName, part)` 接管保存，等待其返回后才生成下一份。
+
+浏览器可能要求允许下载多个文件。取消或失败会停止后续文件，已经下载的文件保留。每份默认最多 10 万行（含汇总尾行、不含表头），20 列以内按此行数分文件；超过 20 列时受 2,000,020 个单元格预算限制，适当减小每份行数。长文本另有 16M UTF-16 码元安全预算，超限时需调低 `maxRowsPerFile`。Worker 不可用时回退；CSV、TXT、JSON 不受影响。千万行多列数据仍建议服务端导出。
+
 ## 内建单元格内容
 
 `render` 支持直接返回结构化内容，内建类型包括：
@@ -170,9 +211,9 @@ table.mount();
 - `checkbox`
 - `radio`
 - `switch`
-- `link`
-
-`icon` 当前内置 `star`、`sun`、`moon`、`check`（√）和 `close`（×）。
+- `link`
+
+`icon` 当前内置 `star`、`sun`、`moon`、`check`（√）和 `close`（×）。
 
 ### 金额单元格示例