@canvas-components/utils 0.2.4 → 0.2.6

package/dist/index.d.cts

@@ -4,19 +4,75 @@ export { ValueDataIndex, getValueByDataIndex, isSameDataIndex, stringifyDataInde
 export { formatDateTimeValue, isDateTimeFormatPattern, resolveDateValue } from './date/index.cjs';
 export { clamp, isPointInRect } from './geometry/index.cjs';
 export { ChineseNumberStyle, NumberFormatOptions, PreciseNumberInput, PreciseRoundingMode, addPreciseNumbers, comparePreciseNumbers, dividePreciseNumber, formatChineseNumber, formatCustomNumberPattern, formatNumberValue, formatPercentValue, formatPreciseNumber, formatScientificValue, normalizeDecimalPlaces, parseChineseNumber, parseNumberValue, roundPreciseNumber, sumPreciseNumbers } from './number/index.cjs';
+import 'xlsx';
+
+/** 表格导出支持的汇总方式，title 保留来源汇总标题。 */
+type TableExportSummaryType = "none" | "title" | "sum" | "avg" | "count" | "unionCount" | "rowCount" | "mergedRowCount" | "min" | "max" | "original";
+/** 列表与透视表共用的导出汇总展示配置。 */
+interface TableExportSummarySettings {
+    type: TableExportSummaryType;
+    showTypePrefix: boolean;
+    precision?: number;
+    roundingMode: "round" | "floor" | "ceil" | "truncate";
+    preserveTrailingZeros: boolean;
+}
+/** 仅作用于本次导出，不修改来源表格。 */
+interface TableExportSettings {
+    columnKeys: string[];
+    sortState: Array<{
+        key: string;
+        order: "ascend" | "descend";
+        priority?: number;
+    }>;
+    summaries: Record<string, TableExportSummarySettings>;
+    includeSummary: boolean;
+}
+/** 导出配置表的一行，隐藏列默认不勾选。 */
+interface TableExportColumnChoice {
+    key: string;
+    title: string;
+    selected?: boolean;
+    sortOrder: "default" | "ascend" | "descend";
+    sortIndex?: number;
+    sortPriority?: number;
+    summary: TableExportSummarySettings;
+    summaryTitle?: string;
+}
+/** 框架无关的导出弹窗请求。 */
+interface TableExportNameRequest {
+    fileName: string;
+    columns?: TableExportColumnChoice[];
+    includeSummary?: boolean;
+    onConfirm: (fileName: string, settings?: TableExportSettings) => void;
+    onCancel: () => void;
+}
 
 /** 单轴 Canvas 滚动条样式。尺寸单位均为 CSS 像素。 */
 interface CanvasScrollbarAxisOptions {
+    /** scrollbar 为现有滑块模式；button 为两个各占半轴的画布按钮。 */
+    mode?: "scrollbar" | "button";
     /** 是否显示；隐藏不禁用滚轮或程序滚动。 */
     visible?: boolean;
     /** 横向高度 / 纵向宽度，默认 10，最小 6。 */
     thickness?: number;
+    /** 纵向按钮栏宽度，优先于 thickness。 */
+    width?: number;
+    /** 横向按钮栏高度，优先于 thickness。 */
+    height?: number;
+    /** 按钮长按时的最大滚动速度，单位 CSS 像素/秒，默认 1800。 */
+    maxScrollSpeed?: number;
     /** 滑块填充颜色。 */
     thumbColor?: string;
     /** 滚动槽背景颜色，不传时保持表格背景。 */
     trackColor?: string;
     /** 两端箭头颜色。 */
     buttonColor?: string;
+    /** 两端按钮常态背景；不传时沿用滚动槽背景。 */
+    buttonBackgroundColor?: string;
+    /** 鼠标悬停按钮时的背景颜色。 */
+    buttonHoverBackgroundColor?: string;
+    /** 按下按钮时的背景颜色。 */
+    buttonPressedBackgroundColor?: string;
     /** 滑块圆角；不传时保持胶囊形状。 */
     thumbRadius?: number;
 }
@@ -27,12 +83,19 @@ interface CanvasScrollbarOptions extends CanvasScrollbarAxisOptions {
 }
 /** 合并通用与单轴配置，并归一化无效尺寸。 */
 declare function resolveCanvasScrollbarAxis(options: CanvasScrollbarOptions | undefined, axis: "horizontal" | "vertical"): {
+    mode: string;
     visible: boolean;
     thickness: number;
+    maxScrollSpeed: number;
     thumbColor: string;
     trackColor: string | undefined;
     buttonColor: string;
+    buttonBackgroundColor: string | undefined;
+    buttonHoverBackgroundColor: string;
+    buttonPressedBackgroundColor: string;
     thumbRadius: number | undefined;
 };
+/** 长按按钮时逐渐加速，2.5 秒达到配置上限。 */
+declare function resolveCanvasScrollbarHoldSpeed(elapsedMs: number, maxScrollSpeed: number): number;
 
-export { type CanvasScrollbarAxisOptions, type CanvasScrollbarOptions, resolveCanvasScrollbarAxis };
+export { type CanvasScrollbarAxisOptions, type CanvasScrollbarOptions, type TableExportColumnChoice, type TableExportNameRequest, type TableExportSettings, type TableExportSummarySettings, type TableExportSummaryType, resolveCanvasScrollbarAxis, resolveCanvasScrollbarHoldSpeed };

package/dist/index.d.ts

@@ -4,19 +4,75 @@ export { ValueDataIndex, getValueByDataIndex, isSameDataIndex, stringifyDataInde
 export { formatDateTimeValue, isDateTimeFormatPattern, resolveDateValue } from './date/index.js';
 export { clamp, isPointInRect } from './geometry/index.js';
 export { ChineseNumberStyle, NumberFormatOptions, PreciseNumberInput, PreciseRoundingMode, addPreciseNumbers, comparePreciseNumbers, dividePreciseNumber, formatChineseNumber, formatCustomNumberPattern, formatNumberValue, formatPercentValue, formatPreciseNumber, formatScientificValue, normalizeDecimalPlaces, parseChineseNumber, parseNumberValue, roundPreciseNumber, sumPreciseNumbers } from './number/index.js';
+import 'xlsx';
+
+/** 表格导出支持的汇总方式，title 保留来源汇总标题。 */
+type TableExportSummaryType = "none" | "title" | "sum" | "avg" | "count" | "unionCount" | "rowCount" | "mergedRowCount" | "min" | "max" | "original";
+/** 列表与透视表共用的导出汇总展示配置。 */
+interface TableExportSummarySettings {
+    type: TableExportSummaryType;
+    showTypePrefix: boolean;
+    precision?: number;
+    roundingMode: "round" | "floor" | "ceil" | "truncate";
+    preserveTrailingZeros: boolean;
+}
+/** 仅作用于本次导出，不修改来源表格。 */
+interface TableExportSettings {
+    columnKeys: string[];
+    sortState: Array<{
+        key: string;
+        order: "ascend" | "descend";
+        priority?: number;
+    }>;
+    summaries: Record<string, TableExportSummarySettings>;
+    includeSummary: boolean;
+}
+/** 导出配置表的一行，隐藏列默认不勾选。 */
+interface TableExportColumnChoice {
+    key: string;
+    title: string;
+    selected?: boolean;
+    sortOrder: "default" | "ascend" | "descend";
+    sortIndex?: number;
+    sortPriority?: number;
+    summary: TableExportSummarySettings;
+    summaryTitle?: string;
+}
+/** 框架无关的导出弹窗请求。 */
+interface TableExportNameRequest {
+    fileName: string;
+    columns?: TableExportColumnChoice[];
+    includeSummary?: boolean;
+    onConfirm: (fileName: string, settings?: TableExportSettings) => void;
+    onCancel: () => void;
+}
 
 /** 单轴 Canvas 滚动条样式。尺寸单位均为 CSS 像素。 */
 interface CanvasScrollbarAxisOptions {
+    /** scrollbar 为现有滑块模式；button 为两个各占半轴的画布按钮。 */
+    mode?: "scrollbar" | "button";
     /** 是否显示；隐藏不禁用滚轮或程序滚动。 */
     visible?: boolean;
     /** 横向高度 / 纵向宽度，默认 10，最小 6。 */
     thickness?: number;
+    /** 纵向按钮栏宽度，优先于 thickness。 */
+    width?: number;
+    /** 横向按钮栏高度，优先于 thickness。 */
+    height?: number;
+    /** 按钮长按时的最大滚动速度，单位 CSS 像素/秒，默认 1800。 */
+    maxScrollSpeed?: number;
     /** 滑块填充颜色。 */
     thumbColor?: string;
     /** 滚动槽背景颜色，不传时保持表格背景。 */
     trackColor?: string;
     /** 两端箭头颜色。 */
     buttonColor?: string;
+    /** 两端按钮常态背景；不传时沿用滚动槽背景。 */
+    buttonBackgroundColor?: string;
+    /** 鼠标悬停按钮时的背景颜色。 */
+    buttonHoverBackgroundColor?: string;
+    /** 按下按钮时的背景颜色。 */
+    buttonPressedBackgroundColor?: string;
     /** 滑块圆角；不传时保持胶囊形状。 */
     thumbRadius?: number;
 }
@@ -27,12 +83,19 @@ interface CanvasScrollbarOptions extends CanvasScrollbarAxisOptions {
 }
 /** 合并通用与单轴配置，并归一化无效尺寸。 */
 declare function resolveCanvasScrollbarAxis(options: CanvasScrollbarOptions | undefined, axis: "horizontal" | "vertical"): {
+    mode: string;
     visible: boolean;
     thickness: number;
+    maxScrollSpeed: number;
     thumbColor: string;
     trackColor: string | undefined;
     buttonColor: string;
+    buttonBackgroundColor: string | undefined;
+    buttonHoverBackgroundColor: string;
+    buttonPressedBackgroundColor: string;
     thumbRadius: number | undefined;
 };
+/** 长按按钮时逐渐加速，2.5 秒达到配置上限。 */
+declare function resolveCanvasScrollbarHoldSpeed(elapsedMs: number, maxScrollSpeed: number): number;
 
-export { type CanvasScrollbarAxisOptions, type CanvasScrollbarOptions, resolveCanvasScrollbarAxis };
+export { type CanvasScrollbarAxisOptions, type CanvasScrollbarOptions, type TableExportColumnChoice, type TableExportNameRequest, type TableExportSettings, type TableExportSummarySettings, type TableExportSummaryType, resolveCanvasScrollbarAxis, resolveCanvasScrollbarHoldSpeed };

package/dist/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();
@@ -206,8 +210,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") {
@@ -221,7 +239,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)
@@ -273,7 +291,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;
@@ -283,7 +301,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,
@@ -414,7 +432,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);
 }
@@ -436,7 +454,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") {
@@ -448,7 +467,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;
@@ -460,8 +485,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,
@@ -469,8 +494,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,
@@ -514,6 +539,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) {
@@ -529,6 +557,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) {
@@ -757,16 +788,29 @@ function isPointInRect(x, y, rect) {
 function resolveCanvasScrollbarAxis(options, axis) {
   const override = options?.[axis];
   const merged = { ...options, ...override };
-  const thickness = Number.isFinite(merged.thickness) ? Math.max(merged.thickness, 6) : 10;
+  const axisSize = axis === "vertical" ? merged.width : merged.height;
+  const requestedThickness = axisSize ?? merged.thickness;
+  const thickness = Number.isFinite(requestedThickness) ? Math.max(requestedThickness, 6) : 10;
   return {
+    mode: merged.mode === "button" ? "button" : "scrollbar",
     visible: options?.visible !== false && override !== false && merged.visible !== false,
     thickness,
+    maxScrollSpeed: Number.isFinite(merged.maxScrollSpeed) && merged.maxScrollSpeed > 0 ? merged.maxScrollSpeed : 1800,
     thumbColor: merged.thumbColor ?? "rgba(100, 116, 139, 0.8)",
     trackColor: merged.trackColor,
     buttonColor: merged.buttonColor ?? "rgba(71, 85, 105, 0.88)",
+    buttonBackgroundColor: merged.buttonBackgroundColor,
+    buttonHoverBackgroundColor: merged.buttonHoverBackgroundColor ?? "rgba(71, 85, 105, 0.09)",
+    buttonPressedBackgroundColor: merged.buttonPressedBackgroundColor ?? "rgba(37, 99, 235, 0.18)",
     thumbRadius: Number.isFinite(merged.thumbRadius) ? Math.max(merged.thumbRadius, 0) : void 0
   };
 }
+function resolveCanvasScrollbarHoldSpeed(elapsedMs, maxScrollSpeed) {
+  const maximum = Math.max(maxScrollSpeed, 1);
+  const initial = Math.min(240, maximum);
+  const progress = Math.min(Math.max(elapsedMs, 0) / 2500, 1);
+  return initial + (maximum - initial) * progress * progress;
+}
 
 // src/number/precise.ts
 function addPreciseNumbers(left, right) {
@@ -1149,6 +1193,6 @@ function resolveThousandsSeparator(separator) {
   return ",";
 }
 
-export { addPreciseNumbers, buildCsvContent, buildTxtContent, clamp, comparePreciseNumbers, copyJson, copyRows, copyText, copyTextSync, dividePreciseNumber, downloadJsonFile, exportTableToCsv, exportTableToTxt, exportTableToXlsx, formatChineseNumber, formatCustomNumberPattern, formatDateTimeValue, formatNumberValue, formatPercentValue, formatPreciseNumber, formatRowsForClipboard, formatScientificValue, getValueByDataIndex, isDateTimeFormatPattern, isPointInRect, isSameDataIndex, mapRowsToExportRecords, normalizeDecimalPlaces, parseChineseNumber, parseNumberValue, resolveCanvasScrollbarAxis, resolveDateValue, roundPreciseNumber, serializeCsvRows, stringifyDataIndex, sumPreciseNumbers };
+export { addPreciseNumbers, buildCsvContent, buildTxtContent, clamp, comparePreciseNumbers, copyJson, copyRows, copyText, copyTextSync, dividePreciseNumber, downloadJsonFile, exportTableToCsv, exportTableToTxt, exportTableToXlsx, formatChineseNumber, formatCustomNumberPattern, formatDateTimeValue, formatNumberValue, formatPercentValue, formatPreciseNumber, formatRowsForClipboard, formatScientificValue, getValueByDataIndex, isDateTimeFormatPattern, isPointInRect, isSameDataIndex, mapRowsToExportRecords, normalizeDecimalPlaces, parseChineseNumber, parseNumberValue, resolveCanvasScrollbarAxis, resolveCanvasScrollbarHoldSpeed, resolveDateValue, roundPreciseNumber, serializeCsvRows, stringifyDataIndex, sumPreciseNumbers };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map