docx.js与docxtemplater对比

docx.js 与 docxtemplater 对比分析及最简示例

一、核心定位与核心差异

特性维度	docxtemplater	docx.js（dolanmiu/docx）
核心设计哲学	模板驱动：基于已有Office模板文件，通过占位符+JSON数据渲染生成文档，核心是「模板编辑」	编程式声明：从零开始通过代码构建完整docx文档，核心是「代码控制文档全结构」
API风格	极简模板语法 + 少量渲染API，非开发人员可独立维护模板	声明式API，全TypeScript支持，强类型提示，完全通过代码定义文档元素
学习成本	极低：只需掌握{变量}、{#循环}、{?条件}基础语法，Word操作即可上手	中等：需理解文档结构（Section/Paragraph/TextRun等），学习对应API，适合开发者
核心适用场景	合同、发票、证书、标准化报表等格式固定、仅数据动态替换的场景，批量生成需求	动态结构报告、复杂格式文档、需根据业务逻辑动态生成章节/段落/表格的场景，需精细控制格式的需求
灵活性	中：受限于模板结构，仅能控制数据填充、条件显示/隐藏，无法动态新增未定义的文档结构	极高：完全代码控制，可动态生成任意文档元素、样式、结构，无模板约束
功能与付费	核心文本替换/循环/条件免费；图片插入、HTML渲染、图表、水印、搜索替换等高级功能需付费购买商业模块	全功能永久免费开源，原生支持表格、图片、页眉页脚、水印、样式、目录、修订模式、页码等几乎所有Word特性，无付费门槛
开源协议	核心库MIT协议，高级扩展模块商业闭源	完全MIT协议，无任何商业限制
多格式支持	支持docx、pptx、xlsx、odt多格式模板渲染	仅专注于docx格式文档生成
运行环境	同时支持Node.js、浏览器端	同时支持Node.js、浏览器端、Serverless环境
维护状态	持续活跃更新，官方文档完善，企业级支持	持续活跃迭代，TS优先，社区生态丰富，GitHub星数远超同类库

核心优缺点总结

• docxtemplater 优势：上手门槛极低，非技术人员可独立修改Word模板，无需改动代码；批量生成标准化文档效率极高；支持多Office格式模板。
  • 劣势：高级功能付费，灵活性受模板限制，复杂动态结构的文档难以实现。
• docx.js 优势：完全免费开源，功能全覆盖，灵活性拉满，可实现任意复杂的文档结构；强类型支持，开发体验好，无付费陷阱。
  • 劣势：学习成本更高，文档样式/结构调整必须修改代码，非开发人员无法独立维护。

二、最简使用示例

前置说明

两个库均支持Node.js与浏览器环境，以下示例均为Node.js 环境的最简可运行代码，可直接复制使用。

---

示例1：docxtemplater 基础使用

1. 安装依赖

npm install docxtemplater pizzip pizzip-utils

2. 准备模板文件

新建一个Word文档template.docx，在文档内写入以下模板内容（可自定义样式、排版）：

个人信息登记表
姓名：{name}
年龄：{age}

技能清单：
{#skills}
- {skillName}：{proficiency}
{/skills}

{?isVIP}
⚠️  该用户为VIP会员，享有专属权益
{/isVIP}

3. 核心渲染代码

const fs = require('fs');
const path = require('path');
const PizZip = require('pizzip');
const Docxtemplater = require('docxtemplater');

// 1. 读取模板文件
const templatePath = path.resolve(__dirname, 'template.docx');
const content = fs.readFileSync(templatePath, 'binary');
const zip = new PizZip(content);

// 2. 初始化docxtemplater
const doc = new Docxtemplater(zip, {
  nullGetter: () => '', // 空值不显示undefined
});

// 3. 绑定渲染数据
doc.render({
  name: '张三',
  age: 28,
  skills: [
    { skillName: 'JavaScript', proficiency: '精通' },
    { skillName: 'Node.js', proficiency: '熟练' },
    { skillName: 'Vue', proficiency: '熟练' },
  ],
  isVIP: true,
});

// 4. 生成并保存新文档
const buffer = doc.getZip().generate({ type: 'nodebuffer' });
fs.writeFileSync(path.resolve(__dirname, '个人信息表.docx'), buffer);
console.log('文档生成成功！');

---

示例2：docx.js 基础使用

1. 安装依赖

npm install docx

2. 从零生成文档的核心代码

const fs = require('fs');
const path = require('path');
const { Document, Packer, Paragraph, TextRun, HeadingLevel, Table, TableRow, TableCell, WidthType } = require('docx');

// 1. 创建文档实例，完整定义文档结构
const doc = new Document({
  sections: [
    {
      // 页面配置（A4纸，标准边距）
      properties: {
        page: {
          size: { width: 11906, height: 16838 }, // A4尺寸
          margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }, // 2.54cm边距
        },
      },
      // 文档内容主体
      children: [
        // 一级标题
        new Paragraph({
          text: '个人信息登记表',
          heading: HeadingLevel.HEADING_1,
          alignment: 'center',
        }),
        // 基础信息段落
        new Paragraph({
          children: [
            new TextRun('姓名：张三'),
            new TextRun({ text: '\n年龄：28', break: 1 }),
          ],
        }),
        // 空行
        new Paragraph(''),
        // 二级标题
        new Paragraph({
          text: '技能清单',
          heading: HeadingLevel.HEADING_2,
        }),
        // 技能表格
        new Table({
          width: { size: 100, type: WidthType.PERCENTAGE },
          rows: [
            // 表头
            new TableRow({
              children: [
                new TableCell({ children: [new Paragraph('技能名称')] }),
                new TableCell({ children: [new Paragraph('熟练程度')] }),
              ],
            }),
            // 表格行
            new TableRow({
              children: [
                new TableCell({ children: [new Paragraph('JavaScript')] }),
                new TableCell({ children: [new Paragraph('精通')] }),
              ],
            }),
            new TableRow({
              children: [
                new TableCell({ children: [new Paragraph('Node.js')] }),
                new TableCell({ children: [new Paragraph('熟练')] }),
              ],
            }),
            new TableRow({
              children: [
                new TableCell({ children: [new Paragraph('Vue')] }),
                new TableCell({ children: [new Paragraph('熟练')] }),
              ],
            }),
          ],
        }),
        // 空行
        new Paragraph(''),
        // VIP提示（加粗红色）
        new Paragraph({
          children: [
            new TextRun({
              text: '⚠️  该用户为VIP会员，享有专属权益',
              bold: true,
              color: 'FF0000',
            }),
          ],
        }),
      ],
    },
  ],
});

// 2. 打包文档并保存
Packer.toBuffer(doc).then((buffer) => {
  fs.writeFileSync(path.resolve(__dirname, '个人信息表_编程式.docx'), buffer);
  console.log('文档生成成功！');
});

三、选型建议

1. 优先选 docxtemplater：你的业务是标准化文档批量生成，模板固定、仅替换数据，需要非开发人员（如运营、法务）可独立修改模板，无需频繁改代码。
2. 优先选 docx.js：你的文档结构动态变化，需要精细控制每一处样式、元素，不想为高级功能付费，且有开发资源维护代码逻辑。
3. 混合使用：复杂固定格式用模板+docxtemplater，动态扩展内容用docx.js生成后合并，兼顾效率与灵活性。