@canvas-components/utils 0.2.3 → 0.2.5

package/dist/export/index.d.cts

@@ -1,3 +1,5 @@
+import * as XLSX from 'xlsx';
+
 /** XLSX 导出阶段；编码阶段无法提供准确的百分比。 */
 interface XlsxExportProgress {
     phase: "preparing" | "encoding" | "saving" | "done";
@@ -30,6 +32,10 @@ interface XlsxExportParams<Row> extends XlsxExportOptions {
     columns: ExportTableColumn<Row>[];
     sheetName?: string;
     footerRows?: unknown[][];
+    /** 多级表头；省略时使用 columns.title。 */
+    headerRows?: string[][];
+    /** 基于完整工作表（含表头）的合并范围，分文件时自动裁切并平移。 */
+    merges?: XLSX.Range[];
 }
 /** 按行数和列数双重限制自动分文件，逐份生成、保存并释放。 */
 declare function exportTableToXlsx<Row>(params: XlsxExportParams<Row>): Promise<void>;
@@ -52,6 +58,7 @@ declare function mapRowsToExportRecords<Row>(params: {
 declare function buildCsvContent<Row>(params: {
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): string;
 /**
  * 将二维数据序列化为 CSV 文本。
@@ -63,6 +70,7 @@ declare function serializeCsvRows(rows: readonly (readonly unknown[])[], lineBre
 declare function buildTxtContent<Row>(params: {
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): string;
 /**
  * 下载 JSON 文件。
@@ -79,6 +87,7 @@ declare function exportTableToCsv<Row>(params: {
     fileName: string;
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): Promise<void>;
 /**
  * 导出表格 TXT 文件。
@@ -87,6 +96,7 @@ declare function exportTableToTxt<Row>(params: {
     fileName: string;
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): Promise<void>;
 
 export { type ExportTableColumn, type XlsxExportOptions, type XlsxExportParams, type XlsxExportProgress, buildCsvContent, buildTxtContent, downloadJsonFile, exportTableToCsv, exportTableToTxt, exportTableToXlsx, mapRowsToExportRecords, serializeCsvRows };

package/dist/export/index.d.ts

@@ -1,3 +1,5 @@
+import * as XLSX from 'xlsx';
+
 /** XLSX 导出阶段；编码阶段无法提供准确的百分比。 */
 interface XlsxExportProgress {
     phase: "preparing" | "encoding" | "saving" | "done";
@@ -30,6 +32,10 @@ interface XlsxExportParams<Row> extends XlsxExportOptions {
     columns: ExportTableColumn<Row>[];
     sheetName?: string;
     footerRows?: unknown[][];
+    /** 多级表头；省略时使用 columns.title。 */
+    headerRows?: string[][];
+    /** 基于完整工作表（含表头）的合并范围，分文件时自动裁切并平移。 */
+    merges?: XLSX.Range[];
 }
 /** 按行数和列数双重限制自动分文件，逐份生成、保存并释放。 */
 declare function exportTableToXlsx<Row>(params: XlsxExportParams<Row>): Promise<void>;
@@ -52,6 +58,7 @@ declare function mapRowsToExportRecords<Row>(params: {
 declare function buildCsvContent<Row>(params: {
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): string;
 /**
  * 将二维数据序列化为 CSV 文本。
@@ -63,6 +70,7 @@ declare function serializeCsvRows(rows: readonly (readonly unknown[])[], lineBre
 declare function buildTxtContent<Row>(params: {
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): string;
 /**
  * 下载 JSON 文件。
@@ -79,6 +87,7 @@ declare function exportTableToCsv<Row>(params: {
     fileName: string;
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): Promise<void>;
 /**
  * 导出表格 TXT 文件。
@@ -87,6 +96,7 @@ declare function exportTableToTxt<Row>(params: {
     fileName: string;
     rows: Row[];
     columns: ExportTableColumn<Row>[];
+    footerRows?: unknown[][];
 }): Promise<void>;
 
 export { type ExportTableColumn, type XlsxExportOptions, type XlsxExportParams, type XlsxExportProgress, buildCsvContent, buildTxtContent, downloadJsonFile, exportTableToCsv, exportTableToTxt, exportTableToXlsx, mapRowsToExportRecords, serializeCsvRows };

package/dist/export/index.js

@@ -11,7 +11,10 @@ var __export = (target, all) => {
 };
 
 // src/export/xlsx-runtime.ts
-function createXlsxWriter(xlsx, header, sheetName, maxRows = 1048576) {
+function createXlsxWriter(xlsx, header, sheetName, maxRows = 1048576, merges = []) {
+  const headerRows = Array.isArray(header[0]) ? header : [header];
+  if (headerRows.length >= maxRows)
+    throw new Error("XLSX \u8868\u5934\u884C\u6570\u8D85\u8FC7\u5DE5\u4F5C\u8868\u5BB9\u91CF");
   const workbook = xlsx.utils.book_new();
   let worksheet;
   let rowCount = 0;
@@ -19,7 +22,7 @@ function createXlsxWriter(xlsx, header, sheetName, maxRows = 1048576) {
   const baseName = sheetName.replace(/[\\/?*[\]:]/g, "_").replace(/^'+|'+$/g, "") || "Sheet1";
   const addSheet = () => {
     const suffix = sheetIndex === 0 ? "" : `_${sheetIndex + 1}`;
-    worksheet = xlsx.utils.aoa_to_sheet([header], {
+    worksheet = xlsx.utils.aoa_to_sheet(headerRows, {
       dense: true
     });
     xlsx.utils.book_append_sheet(
@@ -27,7 +30,8 @@ function createXlsxWriter(xlsx, header, sheetName, maxRows = 1048576) {
       worksheet,
       baseName.slice(0, 31 - suffix.length) + suffix
     );
-    rowCount = 1;
+    if (merges.length && sheetIndex === 0) worksheet["!merges"] = merges;
+    rowCount = headerRows.length;
     sheetIndex += 1;
   };
   addSheet();
@@ -103,7 +107,7 @@ let writer;
 self.onmessage = function(event) {
   try {
     const message = event.data;
-    if (message.type === 'init') writer = createWriter(XLSX, message.header, message.sheetName);
+    if (message.type === 'init') writer = createWriter(XLSX, message.header, message.sheetName, undefined, message.merges);
     else if (message.type === 'append') writer.append(message.rows);
     else if (message.type === 'finish') {
       const buffer = writer.finish();
@@ -151,8 +155,22 @@ async function buildXlsxPart(params, rangeStart, rangeEnd) {
     throw new Error(
       "\u5355\u4EFD XLSX \u6570\u636E\u8D85\u8FC7\u5B89\u5168\u9650\u5236\uFF0C\u8BF7\u4F7F\u7528 exportTableToXlsx \u81EA\u52A8\u5206\u6587\u4EF6\u5BFC\u51FA"
     );
-  const header = columns.map((column) => column.title);
-  let textSize = header.reduce((size, title) => size + title.length, 0);
+  const header = params.headerRows?.length ? params.headerRows : [columns.map((column) => column.title)];
+  const headerRowCount = header.length;
+  const merges = (params.merges ?? []).flatMap((merge) => {
+    if (merge.e.r < headerRowCount) return [merge];
+    const start = Math.max(merge.s.r, headerRowCount + rangeStart);
+    const end = Math.min(merge.e.r, headerRowCount + rangeEnd - 1);
+    return end < start || end === start && merge.s.c === merge.e.c ? [] : [
+      {
+        s: { r: start - rangeStart, c: merge.s.c },
+        e: { r: end - rangeStart, c: merge.e.c }
+      }
+    ];
+  });
+  if (header.some((row) => row.length > columns.length))
+    throw new Error("XLSX \u8868\u5934\u5355\u5143\u683C\u6570\u4E0D\u80FD\u8D85\u8FC7\u5BFC\u51FA\u5217\u6570");
+  let textSize = header.flat().reduce((size, title) => size + title.length, 0);
   const normalizeExportCell = (value) => {
     const cell = normalizeCell(value);
     if (typeof cell === "string") {
@@ -166,7 +184,7 @@ async function buildXlsxPart(params, rangeStart, rangeEnd) {
     }
     return cell;
   };
-  header.forEach((title) => {
+  header.flat().forEach((title) => {
     if (title.length > 32767) throw new Error("XLSX \u8868\u5934\u8D85\u8FC7 32767 \u5B57\u7B26");
   });
   if (textSize > XLSX_MAX_TEXT_CHARS_PER_FILE)
@@ -218,7 +236,7 @@ async function buildXlsxPart(params, rangeStart, rangeEnd) {
           () => fail(new Error("XLSX Worker \u542F\u52A8\u8D85\u65F6")),
           1e4
         );
-        await request({ type: "init", header, sheetName });
+        await request({ type: "init", header, sheetName, merges });
       } catch {
         worker?.terminate();
         worker = void 0;
@@ -228,7 +246,7 @@ async function buildXlsxPart(params, rangeStart, rangeEnd) {
       }
     }
     checkAbort();
-    const writer = worker ? void 0 : createXlsxWriter(XLSX, header, sheetName);
+    const writer = worker ? void 0 : createXlsxWriter(XLSX, header, sheetName, void 0, merges);
     const totalRows = rangeEnd - rangeStart;
     const report = (phase, completedRows) => params.onProgress?.({
       phase,
@@ -359,7 +377,7 @@ function getXlsxRowsPerFile(params) {
     throw new Error("XLSX \u5206\u6587\u4EF6\u4E0A\u9650\u5FC5\u987B\u4E3A\u6B63\u6574\u6570");
   const byCells = Math.floor(
     Math.min(cellLimit, XLSX_MAX_CELLS_PER_FILE) / Math.max(1, params.columns.length)
-  ) - 1;
+  ) - (params.headerRows?.length || 1);
   if (byCells < 1) throw new Error("XLSX \u5355\u5143\u683C\u9884\u7B97\u4E0D\u8DB3\u4EE5\u5BB9\u7EB3\u8868\u5934\u548C\u4E00\u884C\u6570\u636E");
   return Math.min(rowLimit, XLSX_MAX_ROWS_PER_FILE, byCells);
 }
@@ -381,7 +399,8 @@ function buildCsvContent(params) {
     columns.map((column) => column.title),
     ...rows.map(
       (row, rowIndex) => columns.map((column) => column.value(row, rowIndex))
-    )
+    ),
+    ...params.footerRows ?? []
   ]);
 }
 function serializeCsvRows(rows, lineBreak = "\n") {
@@ -393,7 +412,13 @@ function buildTxtContent(params) {
   const body = rows.map(
     (row, rowIndex) => columns.map((column) => normalizeTextCell(column.value(row, rowIndex))).join("	")
   );
-  return [header, ...body].join("\n");
+  return [
+    header,
+    ...body,
+    ...(params.footerRows ?? []).map(
+      (row) => row.map(normalizeTextCell).join("	")
+    )
+  ].join("\n");
 }
 async function downloadJsonFile(params) {
   const { data, fileName, space = 2 } = params;
@@ -405,8 +430,8 @@ async function downloadJsonFile(params) {
   });
 }
 async function exportTableToCsv(params) {
-  const { fileName, rows, columns } = params;
-  const content = await buildCsvContentAsync({ rows, columns });
+  const { fileName, rows, columns, footerRows } = params;
+  const content = await buildCsvContentAsync({ rows, columns, footerRows });
   downloadTextFile({
     fileName: ensureExtension(fileName, "csv"),
     content,
@@ -414,8 +439,8 @@ async function exportTableToCsv(params) {
   });
 }
 async function exportTableToTxt(params) {
-  const { fileName, rows, columns } = params;
-  const content = await buildTxtContentAsync({ rows, columns });
+  const { fileName, rows, columns, footerRows } = params;
+  const content = await buildTxtContentAsync({ rows, columns, footerRows });
   downloadTextFile({
     fileName: ensureExtension(fileName, "txt"),
     content,
@@ -459,6 +484,9 @@ async function buildCsvContentAsync(params) {
     }
     await yieldToMainThread();
   }
+  for (const footer of params.footerRows ?? []) {
+    parts.push("\n", footer.map(escapeCsvCell).join(","));
+  }
   return parts.join("");
 }
 async function buildTxtContentAsync(params) {
@@ -474,6 +502,9 @@ async function buildTxtContentAsync(params) {
     }
     await yieldToMainThread();
   }
+  for (const footer of params.footerRows ?? []) {
+    parts.push("\n", footer.map(normalizeTextCell).join("	"));
+  }
   return parts.join("");
 }
 function escapeCsvCell(value) {