template-docx-exporter

template-docx-exporter

一个在浏览器/Node 环境通用的 DOCX 导出工具：用 docxtemplater 渲染普通占位符与图片，并自动将数据生成的表格 XML 替换到模板中。支持在模板表格内放置占位符，直接用生成表格替换该表，复用模板样式；也提供钩子与 XML 逃生口以应对特殊样式需求。(注：目前仅能解决自用项目中的业务需求，暂无其他拓展性的业务需求)

快速开始

import { exportDocx } from "docx-exporter";

const out = await exportDocx({
  template: arrayBufferFromDocx,   // 必填：ArrayBuffer | Blob | Uint8Array
  data: {
    name: "示例",
    number: "20250101",
    // 表格配置 + 数据，键名以 $table_ 开头
    $table_a: {
      options: {
        // 可选：列宽、行高、字号、合并、对齐等
        columns: [
          { key: "seq", label: "序号", widthRatio: 1 },
          { key: "type", label: "分类", widthRatio: 2, merge: true },
          { key: "project", label: "检测项目", widthRatio: 4 },
          { key: "result", label: "检测结论", widthRatio: 3 },
        ],
        rowHeightCm: 1.1,
        font: "SimSun",
        // 进阶：可传 hooks / overrideTblPrXml / overrideTblGridXml / appendAfterTableXml
      },
      data: [
        { type: "A", seq: "1", project: "项目1", result: "通过" },
        { type: "A", seq: "2", project: "项目2", result: "通过" },
      ],
    },
  },
  // output 默认 blob；如需 ArrayBuffer 指定 output: "arraybuffer"
});

然后在浏览器用 file-saver 下载：

import { saveAs } from "file-saver";
saveAs(out as Blob, "export.docx");

模板约定

• 表格占位符写在模板表格内：在目标表格任意单元格放 {$table_a}（与数据键同名）。
  • 渲染时会抽取该表的 <w:tblPr>/<w:tblGrid> 样式，并直接用生成表替换这张表，示例表不会残留。
• 普通占位符、图片仍由 docxtemplater 处理，图片支持 URL / data URI / base64 / ArrayBuffer。
• 如果模板里没有匹配表格，则会回退到普通占位符文本替换（需在正文放置占位符）。

数据结构

• 普通字段：任意键值（如 name, number）。
• 表格字段：键名以 $table_ 开头，值为：

  {
    options?: TableOptions; // 样式与钩子
    data: TableDataRow[] | TableGroup[];
  }
  

  • TableDataRow = Record<string, string | number>
  • TableGroup = { items: TableDataRow[]; ...groupFields }（会先展开，常用于纵向合并分类）

常用 TableOptions

• 列宽/合并：columns[].widthRatio、columns[].merge；或 mergeColumns 快捷设置。
• 行高/字体/字号/加粗/对齐：rowHeightCm, font, titleSize, headerSize, bodySize, headerBold, cellBold, align。
• 逃生口：overrideTblPrXml, overrideTblGridXml, appendAfterTableXml。
• 钩子：

  hooks: {
    onCell?: (cell, rowIdx, colIdx) => TableCell | void;
    onRow?: (row, rowIdx) => TableRow | void;
    onTable?: (table) => Table | void;
  }
  

  可用于注入特殊属性、追加 run 等。

图片支持

• 支持 Blob/ArrayBuffer、data URI、纯 base64、URL（会 fetch）；
• 可在占位值上带 { width, height, unit }（unit 支持 px/cm）或直接传数字作为高度。

运行环境

• 浏览器：默认返回 Blob，可直接配合 file-saver。
• Node：output: "arraybuffer" 时返回 ArrayBuffer；图片 base64 转换兼容无 atob 的环境。

开发与构建

pnpm install
pnpm dev              # playground 调试
pnpm build            # 生成 dist/index.js & d.ts
pnpm playground:build # 打包 playground

目录结构概览

• src/index.ts：主入口，解析数据、渲染 docxtemplater、注入表格 XML。
• src/table-builder.ts：表格生成、样式克隆、钩子、逃生口。
• src/table-injector.ts：表格 XML 注入逻辑。
• playground/：Vite+Vue 示例与默认模板/data。