docx-generator

DOCX 生成器

何时使用此技能

在以下情况下使用此技能：

• 根据数据或规范以编程方式创建 Word 文档
• 在保留企业样式的同时，用动态内容填充品牌模板
• 提取现有 DOCX 文件中的文本、表格和结构以供分析
• 查找并替换 {{TITLE}} 或 ${author} 等占位文本
• 自动化文档生成工作流（报告、合同、信函）

在以下情况下请勿使用此技能：

• 用户想要打开或查看文档（使用原生 Word 或查看器）
• 需要使用数据源进行复杂的邮件合并（使用原生 Word 邮件合并）
• 处理较旧的 .doc 格式（仅支持 DOCX）
• 需要 PDF 输出（请改用 pdf-generator 技能）

前提条件

• 已安装 Deno（https://deno.land/）
• 用于基于模板操作的输入 DOCX 文件
• 用于从头生成的 JSON 规范

快速开始

两种操作模式

1. 模板模式：修改现有品牌模板

   • 分析模板以查找占位符
   • 将 {{PLACEHOLDERS}} 替换为实际内容

2. 从头生成模式：使用 JSON 规范从头创建文档

说明

模式 1：基于模板生成

步骤 1a：分析模板

提取文本清单，以了解哪些内容可以替换：

deno run --allow-read scripts/analyze-template.ts corporate-template.docx > inventory.json

输出（inventory.json）：

{
  "filename": "corporate-template.docx",
  "paragraphCount": 25,
  "tableCount": 2,
  "imageCount": 1,
  "paragraphs": [
    {
      "index": 0,
      "style": "Title",
      "fullText": "{{DOCUMENT_TITLE}}",
      "runs": [
        { "text": "{{DOCUMENT_TITLE}}", "bold": true, "fontSize": 28 }
      ]
    }
  ],
  "placeholders": [
    { "tag": "{{DOCUMENT_TITLE}}", "location": "paragraph", "paragraphIndex": 0 },
    { "tag": "{{AUTHOR}}", "location": "footer-default", "paragraphIndex": 0 },
    { "tag": "${date}", "location": "table", "tableIndex": 0, "cellLocation": "R1C2" }
  ]
}

步骤 1b：创建替换规范

创建 replacements.json：

{
  "textReplacements": [
    { "tag": "{{DOCUMENT_TITLE}}", "value": "Q4 2024 Financial Report" },
    { "tag": "{{AUTHOR}}", "value": "Finance Department" },
    { "tag": "${date}", "value": "December 15, 2024" },
    { "tag": "{{COMPANY}}", "value": "Acme Corporation" }
  ],
  "includeHeaders": true,
  "includeFooters": true
}

步骤 1c：生成输出

deno run --allow-read --allow-write scripts/generate-from-template.ts \
  corporate-template.docx replacements.json output.docx

模式 2：从头生成

步骤 2a：创建规范

创建 spec.json：

{
  "title": "Quarterly Report",
  "creator": "Finance Team",
  "styles": {
    "defaultFont": "Calibri",
    "defaultFontSize": 11
  },
  "sections": [
    {
      "header": {
        "paragraphs": [
          { "text": "Acme Corporation", "alignment": "right" }
        ]
      },
      "footer": {
        "paragraphs": [
          { "text": "Confidential", "alignment": "center" }
        ]
      },
      "content": [
        {
          "text": "Q4 2024 Financial Report",
          "heading": 1,
          "alignment": "center"
        },
        {
          "runs": [
            { "text": "Executive Summary: ", "bold": true },
            { "text": "This report provides an overview of our financial performance for Q4 2024." }
          ]
        },
        { "pageBreak": true },
        {
          "text": "Revenue Breakdown",
          "heading": 2
        },
        {
          "rows": [
            {
              "cells": [
                { "content": [{ "text": "Category" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Amount" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Change" }], "shading": "DDDDDD" }
              ],
              "isHeader": true
            },
            {
              "cells": [
                { "content": [{ "text": "Product Sales" }] },
                { "content": [{ "text": "$1,250,000" }] },
                { "content": [{ "text": "+15%" }] }
              ]
            },
            {
              "cells": [
                { "content": [{ "text": "Services" }] },
                { "content": [{ "text": "$750,000" }] },
                { "content": [{ "text": "+8%" }] }
              ]
            }
          ],
          "width": 100,
          "borders": true
        }
      ]
    }
  ]
}

步骤 2b：生成文档

deno run --allow-read --allow-write scripts/generate-scratch.ts spec.json output.docx

示例

示例 1：生成合同

场景：根据品牌模板生成合同。

步骤：

# 1. Analyze template for replaceable content
deno run --allow-read scripts/analyze-template.ts contract-template.docx --pretty

# 2. Create replacements.json with client data
# 3. Generate contract
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  contract-template.docx replacements.json acme-contract.docx

示例 2：包含表格的报告

场景：生成包含表格和格式设置的数据报告。

spec.json：

{
  "title": "Sales Report",
  "sections": [{
    "content": [
      { "text": "Monthly Sales Report", "heading": 1 },
      { "text": "January 2025", "heading": 2 },
      {
        "runs": [
          { "text": "Total Sales: ", "bold": true },
          { "text": "$125,000", "color": "2E7D32" }
        ]
      }
    ]
  }]
}

示例 3：包含页眉/页脚的信函

场景：创建带有信笺抬头的正式信函。

spec.json：

{
  "sections": [{
    "header": {
      "paragraphs": [
        { "text": "ACME CORPORATION", "alignment": "center", "runs": [{"text": "ACME CORPORATION", "bold": true, "fontSize": 16}] },
        { "text": "123 Business Ave, City, ST 12345", "alignment": "center" }
      ]
    },
    "content": [
      { "text": "December 15, 2024", "alignment": "right" },
      { "text": "" },
      { "text": "Dear Valued Customer," },
      { "text": "" },
      { "text": "Thank you for your continued business..." },
      { "text": "" },
      { "text": "Sincerely," },
      { "text": "John Smith" },
      { "runs": [{ "text": "CEO", "italic": true }] }
    ],
    "footer": {
      "paragraphs": [
        { "text": "www.acme.com | [email protected]", "alignment": "center" }
      ]
    }
  }]
}

脚本参考

脚本	用途	权限
analyze-template.ts	从 DOCX 中提取文本、表格和占位符	--allow-read
generate-from-template.ts	替换模板中的占位符	--allow-read --allow-write
generate-scratch.ts	根据 JSON 规范创建 DOCX	--allow-read --allow-write

规范参考

段落选项

属性	类型	说明
text	string	简单文本内容
runs	array	格式化的文本片段（用于混合格式）
heading	1-6	标题级别
alignment	string	left、center、right、justify
bullet	boolean	项目符号列表项
numbering	boolean	编号列表项
spacing	object	before、after、line 间距
indent	object	left、right、firstLine 缩进
pageBreakBefore	boolean	在段落前插入分页符

文本片段选项

属性	类型	说明
text	string	文本内容
bold	boolean	粗体格式
italic	boolean	斜体格式
underline	boolean	下划线格式
strike	boolean	删除线
fontSize	number	字号（磅）
font	string	字体名称
color	string	文本颜色（十六进制，不带 #）
highlight	string	突出显示颜色
superScript	boolean	上标
subScript	boolean	下标

表格选项

属性	类型	说明
rows	array	行规范数组
width	number	表格宽度百分比
borders	boolean	显示表格边框

超链接选项

属性	类型	说明
text	string	链接文本
url	string	目标 URL
bold	boolean	粗体格式
italic	boolean	斜体格式

常见问题与解决方案

问题：占位符未被替换

症状：输出的 DOCX 仍包含 {{PLACEHOLDER}} 标签。

解决方案：

1. 运行 analyze-template.ts，确认标签的准确文本
2. 标签可能被拆分到多个 XML 运行中——脚本会自动合并这些内容
3. 如果占位符位于页眉或页脚中，请确保 includeHeaders 和 includeFooters 为 true

问题：替换后格式丢失

症状：替换后的文本与原始格式不一致。

解决方案：

• 文本替换会保留原占位符的格式
• 确保占位符的格式符合你对最终文本的要求

问题：图片未显示

症状：输出中的图片元素为空白。

解决方案：

1. 使用相对于 spec.json 文件所在位置的路径
2. 确认图片文件存在且可读
3. 检查支持的格式：PNG、JPEG、GIF

问题：表格单元格内容不正确

症状：表格单元格的内容或格式有误。

解决方案：

• 每个单元格的 content 必须是段落规范数组
• 使用 shading 设置背景颜色，使用 verticalAlign 设置对齐方式

限制

• 仅支持 DOCX：不支持旧版 .doc 格式
• 不支持修订：无法添加或处理修订
• 不支持批注：无法添加文档批注
• 不支持宏：无法包含 VBA 宏
• 基本编号功能：对复杂编号方案的支持有限
• 文本运行拆分：Word 可能会将文本拆分到多个 XML 元素中；脚本会处理常见情况

相关技能

• pptx-generator：用于创建 PowerPoint 演示文稿
• xlsx-generator：用于创建 Excel 电子表格
• pdf-generator：用于创建 PDF 文档