Word 导出 plugin-api-word
约 874 字大约 3 分钟
...
2026-09-29
插件说明
@sv-print/plugin-api-word 导出 Word 插件：为打印模板挂载 template.toWord() API，并在预览条注入"导出 word"按钮。返回 jQuery Deferred promise，支持 .then / .fail / await；模板无可打印面板时 resolve null，导出失败时 reject。
npm install @sv-print/plugin-api-word示例代码
import pluginApiWord from '@sv-print/plugin-api-word';
await hiprint.register({ plugins: [pluginApiWord()] });
let template = new hiprint.PrintTemplate(/* ... */); // 须在 register 之后创建模板
// 默认：直接下载 docx 文件
template.toWord(printData);
// 自定义文件名 + 页级进度回调
template.toWord(printData, {
name: '出库单', // 自动补 .docx 后缀
onProgress: (cur, total) => {
console.log(`正在导出第 ${cur}/${total} 页`);
},
});
// 不自动下载，拿到 Blob 自行上传
template
.toWord(printData, { isDownload: false, name: 'report.docx' })
.then((blob) => {
const form = new FormData();
form.append('file', blob, 'report.docx');
return fetch('/api/upload', { method: 'POST', body: form });
})
.fail((err) => console.error('导出失败：', err)); // 返回 Deferred promise，支持 .then / .fail / await
// datauristring：转成 data URL，用于浏览器内嵌预览
template.toWord(printData, { isDownload: false, outputType: 'datauristring' }).then((dataUri) => {
document.querySelector('iframe').src = dataUri;
});高级用法
导出模式
// editable（默认）：网格表格还原，文本/表格/图片在 Word 中原生可编辑
template.toWord(printData, { mode: 'editable' });
// positioned：浮动定位，所见即所得还原设计位置
template.toWord(printData, { mode: 'positioned' }); // [!code word:mode参数表
template.toWord(printData, options)
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| mode | "editable" | "positioned" | "editable" | editable=网格表格（原生可编辑）；positioned=浮动定位（所见即所得） |
| outputType | "blob" | "arraybuffer" | "bloburl" | "datauristring" | "blob" | 返回值形态 |
| name | string | sv-print-时间戳.docx | 下载文件名（自动补 .docx 后缀） |
| isDownload | boolean | true | 是否触发浏览器下载 |
| fontName | string | Microsoft YaHei | 默认字体 |
| fontSize | number | 10 | 默认字号（pt） |
| pixelRatio | number | 1 | 截图元素（条码/图表等）的截图倍率 |
| customTypeResolver | (type, el, snap) => ElementType | - | 自定义元素类型解析 |
| onBeforeWrite | (ctx) => PositionedElement[] | void | - | 每页写入前回调，可返回替换后的元素数组 |
| onProgress | (cur, total) => void | - | 页级进度回调 |
自定义元素类型检测
通过 customTypeResolver 覆盖内置元素类型判断；返回 undefined 时使用内置检测逻辑。
import pluginApiWord from '@sv-print/plugin-api-word';
const myResolver = (type, el, snap) => {
if (el.hasClass('my-custom-element')) return 'custom'; // custom=截图转图片嵌入
if (el.hasClass('my-special-text')) return 'text';
return undefined; // 其余走内置检测
};
template.toWord(printData, { customTypeResolver: myResolver });写入前回调 onBeforeWrite
每页写入 Word 前回调，可原地修改 ctx.elements，或返回新数组替换原始元素集合。
template.toWord(printData, {
onBeforeWrite: (ctx) => {
console.log(`正在处理第 ${ctx.paperIndex + 1}/${ctx.paperCount} 页`);
// 过滤掉左上角的页码元素（返回新数组替换）
return ctx.elements.filter((el) => !(el.el.hasClass('hiprint-paperNumber') && el.left < 50));
},
});回调上下文（BeforeWordContext）：
| 属性 | 类型 | 说明 |
|---|---|---|
| paperIndex | number | 当前页索引（0-based） |
| paperCount | number | 总页数 |
| html | any | template.getHtml 返回的 jQuery 集合 |
| elements | PositionedElement[] | 当前页即将写入的元素集合（可增删改，pt） |
| $paper | any | 当前页 paper 的 jQuery 对象 |
| options | ToWordOptions | 合并后的完整选项 |
| doc | any | docx Document 实例（高级用法，通常不传） |
版权所有
版权归属：sv-print