插件说明

@sv-print/plugin-api-excel 为打印模板实例挂载 toExcel 方法，生成 .xlsx 格式文件（Office Open XML），兼容 Microsoft Excel、WPS、LibreOffice、Google Sheets 等主流办公软件。

核心能力：

• 挂载 template.toExcel(printData, options?)，返回 Promise<Blob>
• 表格元素：自动解析 HTML 表格结构，支持合并单元格（colspan/rowspan）、样式保留
• 文本元素：提取文本内容及样式（字体、字号、加粗、颜色、对齐），支持长文本元素（longText）
• 图片元素：嵌入为 Excel 图片；页码元素自动识别 hiprint-paperNumber 并作为文本写入
• 其他元素（box、ECharts、Fabric 等）：通过 snapdom 截图转为图片嵌入
• 行列精确映射：基于元素边界动态构建行列分割点，精确还原 HTML 渲染位置与尺寸，自动列宽适配
• 多面板/多页面：每页独立 Sheet 或合并为单个 Sheet（multiSheet / pageGap 控制）
• 预览条自动注入「导出 excel」按钮（onPreview hook，opts.showExcel != false 时）

第三方依赖：exceljs + snapdom。

npm install @sv-print/plugin-api-excel

示例代码

唯一注册入口 hiprint.register（异步），须在创建模板之前注册：

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

await hiprint.register({
  // 须在创建模板之前注册
  plugins: [pluginApiExcel()], // 工厂函数，可传 config // 注册后预览条自动注入「导出 excel」按钮（opts.showExcel: false 可关闭）
});

const template = new hiprint.PrintTemplate(/* ... */); // 须在 register 之后创建模板

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

// 获取 Blob（不下载）
const blob = await template.toExcel(printData, {
  isDownload: false,
  name: 'report.xlsx',
});

高级用法

toExcel 参数

template.toExcel(printData, options?)

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

解析规则：解析模板 HTML，table → 单元格、text → RichText、image → addImage、box/其他元素 → snapdom 截图嵌入，列宽按 pt → Excel 公式换算，上限 300 列 / 800 行。

多页面工作表控制

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

// 所有页面内容写入同一个 Sheet（页面紧贴，无间隙）
template.toExcel(printData, { multiSheet: false });

// 所有页面写入同一个 Sheet，页面之间留 20pt 间隙
template.toExcel(printData, { multiSheet: false, pageGap: 20 });

multiSheet: false 时所有页面共用一套列宽网格（取各页最大纸宽统一构建），页面内容按行依次堆叠；pageGap 以 pt 为单位控制相邻页面之间的空隙（超过 409pt 会自动拆分为多行）。

自定义元素类型检测

通过 customTypeResolver 自定义元素的类型判断逻辑，实现灵活扩展：

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

// 将特定 class 的元素按指定类型处理
const myResolver = ($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 截图转为图片

写入前回调 onBeforeWrite

在元素写入 Excel 前拿到原始 HTML、元素集合、Sheet 等进行微调。回调返回新数组时会替换原始元素集合；返回 void / undefined 时以对 ctx.elements 的原地修改为准。

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

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

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

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

  // 修改元素位置/尺寸
  for (const 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	合并后的完整选项

注意事项

• 所有 api 插件依赖 globalThis.$（jQuery Deferred）与 globalThis.hinnn，由 sv-print 内核提供
• 预览条中不希望出现「导出 excel」按钮时，预览时传 opts.showExcel: false

版权所有

版权归属：sv-print

许可证：署名 4.0 国际 (CC-BY-4.0)

贡献者: Canim

上一页图片 导出

下一页Word 导出