@sv-print/plugin-api-excel

为 sv-print 打印模板添加 Excel 导出功能，生成 .xlsx 格式文件，兼容 Microsoft Excel、WPS、LibreOffice、Google Sheets 等主流办公软件。

安装

npm install @sv-print/plugin-api-excel
# or
pnpm add @sv-print/plugin-api-excel

使用

import pluginApiExcel from "@sv-print/plugin-api-excel";

// 注册插件
hiprint.init([pluginApiExcel()]);

// 创建模板后即可使用 toExcel
let template = new hiprint.PrintTemplate(/* ... */);

// 下载 Excel 文件
template.toExcel(printData, { name: "导出文件名.xlsx" });

// 获取 Blob（不下载）
template.toExcel(printData, {
  isDownload: false,
  name: "report.xlsx",
}).then(blob => {
  // 处理 blob
});

API

template.toExcel(printData, options?)

参数：

| 参数 | 类型 | 说明 | |------|------|------| | printData | any | 打印数据 | | options | object | 可选配置项 |

选项：

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | isDownload | boolean | true | 是否自动下载文件 | | name | string | sv-print-{timestamp}.xlsx | 下载文件名 | | fontName | string | Microsoft YaHei | 默认字体 | | fontSize | number | 10 | 默认字号（pt） | | sheetName | string | Sheet | 工作表名称前缀 | | pixelRatio | number | 1 | 非标准元素截图像素比 | | multiSheet | boolean | true | 多页面是否自动创建多个工作表；为 false 时所有页面内容写入同一个 Sheet | | customTypeResolver | ElementTypeResolver | - | 自定义元素类型检测函数，返回 undefined 时使用内置检测逻辑 | | onProgress | (cur, total) => void | console.log | 进度回调 | | onBeforeWrite | BeforeWriteCallback | - | 写入前回调，可修改元素集合或直接操作 Sheet/Workbook |

返回值： Promise<Blob> - Excel 文件的 Blob 对象

自定义元素类型检测

通过 customTypeResolver 可以让外部自定义元素的类型判断逻辑，实现灵活的扩展。

import pluginApiExcel, { type ElementTypeResolver } from "@sv-print/plugin-api-excel";

// 注册插件
hiprint.init([pluginApiExcel()]);

let template = new hiprint.PrintTemplate(/* ... */);

// 自定义类型检测：将特定 class 的文本元素当作截图处理
let myResolver: ElementTypeResolver = ($el, defaultType) => {
  // 返回 undefined 则使用默认类型
  if ($el.hasClass("my-custom-element")) return "other";
  if ($el.hasClass("my-special-text")) return "text";
  return undefined;
};

template.toExcel(printData, {
  customTypeResolver: myResolver,
});

支持的元素类型（ElementType）：

| 类型 | 说明 | |------|------| | table | 表格元素，解析 HTML table 结构 | | text | 文本元素，提取文本及富文本样式 | | image | 图片元素，嵌入为 Excel 图片 | | hline | 水平线元素 | | vline | 垂直线元素 | | box | 盒子容器元素，截图处理 | | other | 其他元素，通过 snapdom 截图转为图片 |

多页面工作表控制

通过 multiSheet 参数控制多页面导出时的工作表创建策略：

// 默认：每个页面创建独立 Sheet
template.toExcel(printData, { multiSheet: true });

// 所有页面内容写入同一个 Sheet（页面间空一行分隔）
template.toExcel(printData, { multiSheet: false });

写入前回调 onBeforeWrite

通过 onBeforeWrite 可以在元素写入 Excel 前拿到原始 HTML、元素集合、Sheet 等进行微调。回调返回新数组时会替换原始元素集合。

import pluginApiExcel, { type BeforeWriteCallback } from "@sv-print/plugin-api-excel";

hiprint.init([pluginApiExcel()]);

let template = new hiprint.PrintTemplate(/* ... */);

const beforeWrite: BeforeWriteCallback = (ctx) => {
  console.log(`正在处理第 ${ctx.paperIndex + 1}/${ctx.paperCount} 页: ${ctx.sheetName}`);

  // 1. 直接操作 Sheet（追加额外数据）
  ctx.sheet.getCell("A1").value = "附加标题";

  // 2. 过滤掉某些元素（返回新数组替换）
  let filtered = ctx.elements.filter(
    el => !(el.el.hasClass("hiprint-paperNumber") && el.left < 50)
  );

  // 3. 修改元素位置/尺寸
  for (let el of ctx.elements) {
    if (el.type === "text" && el.top > 200) {
      el.top += 10; // 下移 10pt
    }
  }

  return filtered;
};

template.toExcel(printData, {
  onBeforeWrite: beforeWrite,
});

回调上下文 (BeforeWriteContext)：

| 属性 | 类型 | 说明 | |------|------|------| | paperIndex | number | 当前页索引（0-based） | | paperCount | number | 总页数 | | sheetName | string | 当前工作表名称 | | html | any[] | 原始 HTML 字符串数组（所有页面） | | elements | PositionedElement[] | 当前页即将写入的元素集合（可增删改） | | workbook | ExcelJS.Workbook | ExcelJS Workbook 实例 | | sheet | ExcelJS.Worksheet | 当前页对应的 Worksheet | | $paper | any | 当前页 paper 的 jQuery 对象 | | options | ToExcelOptions | 合并后的完整选项 |

返回值： void 或 PositionedElement[]。返回新数组时将替换 elements 继续写入；返回 void / undefined 时以对 ctx.elements 的原地修改为准。

特性

• 生成 .xlsx 格式（Office Open XML），最大兼容性
• 表格元素：自动解析 HTML 表格结构，支持合并单元格（colspan/rowspan）、样式保留
• 文本元素：提取文本内容及样式（字体、字号、加粗、颜色、对齐），支持长文本元素（longText）
• 图片元素：嵌入为 Excel 图片
• 页码元素：自动识别 hiprint-paperNumber 并作为文本写入
• 其他元素：通过 snapdom 截图转为图片嵌入（支持 ECharts、Fabric、矩形等自定义元素）
• 行列精确映射：基于元素边界动态构建行列分割点，精确还原 HTML 渲染位置与尺寸
• 多面板/多页面：支持每页独立 Sheet 或合并为单个 Sheet（multiSheet 参数控制）
• 自定义类型检测：通过 customTypeResolver 支持外部扩展元素类型判断逻辑
• 自动列宽适配