Communitygithub.com

DOCX 创建、编辑与分析

一套用于创建、编辑和分析 Microsoft Word .docx 文件的技能,提供代码片段和关键规则。

DOCX 创建、编辑与分析 是什么?

此技能提供了一套全面的工具和方法,用于处理 Microsoft Word 的 .docx 文件。它涵盖了从内容读取(使用 `markitdown`)、快速 XML 分析(通过 `unpack.py`)到全新文档创建和既有文档编辑的整个工作流程。对于创建新文档,技能依赖于 `docx`(docx-js)Node.js 库,并提供了详细的代码示例,包括页面设置、样式、列表、表格、图片、超链接、脚注、页眉/页脚和目录设置。它强调了一些关键规则,例如显式设置页面尺寸(勿用 A4 默认值)、在表格宽度中使用 DXA 单位、使用 `LevelFormat.BULLET` 作为项目符号以及将分页符放在段落内。对于编辑既有文档,它提供了分步指南:使用 `unpack.py` 解包、使用编辑工具直接修改 XML,以及使用 `pack.py` 重新打包。该技能还包含一个实用脚本 `accept_changes.py`,用于接受文档中的所有修订,以及一个验证脚本 `validate.py`。它适用于基于 AI 的代理(如 Claude Code),用于自动化文档生成和修改任务,以确保在 Google Docs 等不同平台上输出一致且兼容的文档。

兼容平台✓Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add hankunpeng/skills

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

DOCX 创建、编辑与分析 是做什么的?

概述

.docx 文件是一个包含 XML 文件的 ZIP 压缩包。

快速参考

任务方法
读取/分析内容markitdown 或解包以获取原始 XML
创建新文档使用 docx-js - 见下方“创建新文档”
编辑已有文档解包 → 编辑 XML → 重新打包 - 见下方“编辑已有文档”

读取内容

# 文本提取
markitdown document.docx > output.md

# 原始 XML 访问
python scripts/office/unpack.py document.docx unpacked/

接受修订

生成一个已接受所有修订的干净文档:

python scripts/accept_changes.py input.docx output.docx

创建新文档

使用 JavaScript 生成 .docx 文件,然后进行验证。安装:npm install -g docx

设置

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
        InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
        PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
        TabStopType, TabStopPosition, Column, SectionType,
        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
        VerticalAlign, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* 内容 */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));

验证

创建文件后,进行验证。如果验证失败,解包,修复 XML,并重新打包。

python scripts/office/validate.py doc.docx

页面尺寸

// 关键:docx-js 默认使用 A4,而非 US Letter
// 始终显式设置页面尺寸以获得一致的结果
sections: [{
  properties: {
    page: {
      size: {
        width: 12240,   // 8.5 英寸(DXA 单位)
        height: 15840   // 11 英寸(DXA 单位)
      },
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 英寸边距
    }
  },
  children: [/* 内容 */]
}]

常见页面尺寸(DXA 单位,1440 DXA = 1 英寸):

纸张宽度高度内容宽度(1 英寸边距)
US Letter12,24015,8409,360
A4(默认)11,90616,8389,026

横向: docx-js 内部会交换宽度/高度,因此传入纵向尺寸,让它处理交换:

size: {
  width: 12240,   // 将短边作为宽度传入
  height: 15840,  // 将长边作为高度传入
  orientation: PageOrientation.LANDSCAPE  // docx-js 会在 XML 中交换它们
},
// 内容宽度 = 15840 - 左边距 - 右边距(使用长边)

样式(覆盖内置标题)

使用 Arial 作为默认字体(普遍支持)。保持标题为黑色以确保可读性。

const doc = new Document({
  styles: {
    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt 默认
    paragraphStyles: [
      // 重要:使用精确的 ID 来覆盖内置样式
      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 32, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // TOC 需要 outlineLevel
      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 28, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("标题")] }),
    ]
  }]
});

列表(绝不使用 Unicode 项目符号)

// ❌ 错误 - 切勿手动插入项目符号字符
new Paragraph({ children: [new TextRun("• 项目")] })  // 错误
new Paragraph({ children: [new TextRun("\u2022 项目")] })  // 错误

// ✅ 正确 - 使用带有 LevelFormat.BULLET 的 numbering config
const doc = new Document({
  numbering: {
    config: [
      { reference: "bullets",
        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
      { reference: "numbers",
        levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ numbering: { reference: "bullets", level: 0 },
        children: [new TextRun("项目符号项")] }),
      new Paragraph({ numbering: { reference: "numbers", level: 0 },
        children: [new TextRun("编号项")] }),
    ]
  }]
});

// ⚠️ 每个 reference 创建独立的编号
// 相同的 reference = 继续(1,2,3 然后 4,5,6)
// 不同的 reference = 重新开始(1,2,3 然后 1,2,3)

表格

关键:表格需要双重宽度 - 同时设置表格上的 columnWidths 和每个单元格的 width。如果不设置两者,表格在某些平台上将渲染不正确。

// 关键:始终设置表格宽度以确保一致渲染
// 关键:使用 ShadingType.CLEAR(而非 SOLID)以防止黑色背景
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };

new Table({
  width: { size: 9360, type: WidthType.DXA }, // 始终使用 DXA(百分比在 Google Docs 中会出错)
  columnWidths: [4680, 4680], // 必须与表格宽度之和相等(DXA:1440 = 1 英寸)
  rows: [
    new TableRow({
      children: [
        new TableCell({
          borders,
          width: { size: 4680, type: WidthType.DXA }, // 也在每个单元格上设置
          shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR 而非 SOLID
          margins: { top: 80, bottom: 80, left: 120, right: 120 }, // 单元格内边距(内部,不加到宽度中)
          children: [new Paragraph({ children: [new TextRun("单元格")] })]
        })
      ]
    })
  ]
})

表格宽度计算:

始终使用 WidthType.DXA — WidthType.PERCENTAGE 在 Google Docs 中会出错。

// 表格宽度 = columnWidths 之和 = 内容宽度
// US Letter 带 1 英寸边距:12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360]  // 必须与表格宽度之和相等

宽度规则:

  • 始终使用 WidthType.DXA — 绝不使用 WidthType.PERCENTAGE(与 Google Docs 不兼容)
  • 表格宽度必须等于 columnWidths 之和
  • 单元格 width 必须与相应的 columnWidth 匹配
  • 单元格 margins 是内部内边距;它们会减少内容区域,不会增加单元格宽度
  • 对于全宽表格:使用内容宽度(页面宽度减去左右边距)

图片

// 关键:type 参数是必需的
new Paragraph({
  children: [new ImageRun({
    type: "png", // 必需:png、jpg、jpeg、gif、bmp、svg
    data: fs.readFileSync("image.png"),
    transformation: { width: 200, height: 150 },
    altText: { title: "标题", description: "描述", name: "名称" } // 三者皆必需
  })]
})

分页符

// 关键:PageBreak 必须在 Paragraph 内部
new Paragraph({ children: [new PageBreak()] })

// 或者使用 pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("新页面")] })

超链接

// 外部链接
new Paragraph({
  children: [new ExternalHyperlink({
    children: [new TextRun({ text: "点击此处", style: "Hyperlink" })],
    link: "https://example.com",
  })]
})

// 内部链接(书签 + 引用)
// 1. 在目标位置创建书签
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
  new Bookmark({ id: "chapter1", children: [new TextRun("第 1 章")] }),
]})
// 2. 链接到它
new Paragraph({ children: [new InternalHyperlink({
  children: [new TextRun({ text: "查看第 1 章", style: "Hyperlink" })],
  anchor: "chapter1",
})]})

脚注

const doc = new Document({
  footnotes: {
    1: { children: [new Paragraph("来源:2024 年度报告")] },
    2: { children: [new Paragraph("方法论请参见附录")] },
  },
  sections: [{
    children: [new Paragraph({
      children: [
        new TextRun("收入增长了 15%"),
        new FootnoteReferenceRun(1),
        new TextRun(" 使用调整后的指标"),
        new FootnoteReferenceRun(2),
      ],
    })]
  }]
});

制表位

// 在同一行右对齐文本(例如,标题对侧的日期)
new Paragraph({
  children: [
    new TextRun("公司名称"),
    new TextRun("\t2025 年 1 月"),
  ],
  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})

// 点前导符(例如,目录样式)
new Paragraph({
  children: [
    new TextRun("引言"),
    new TextRun({ children: [
      new PositionalTab({
        alignment: PositionalTabAlignment.RIGHT,
        relativeTo: PositionalTabRelativeTo.MARGIN,
        leader: PositionalTabLeader.DOT,
      }),
      "3",
    ]}),
  ],
})

多列布局

// 等宽列
sections: [{
  properties: {
    column: {
      count: 2,          // 列数
      space: 720,        // 列间距(DXA,720 = 0.5 英寸)
      equalWidth: true,
      separate: true,    // 列间垂直线
    },
  },
  children: [/* 内容自然地在列间流动 */]
}]

// 自定义宽度列(equalWidth 必须为 false)
sections: [{
  properties: {
    column: {
      equalWidth: false,
      children: [
        new Column({ width: 5400, space: 720 }),
        new Column({ width: 3240 }),
      ],
    },
  },
  children: [/* 内容 */]
}]

使用 type: SectionType.NEXT_COLUMN 的新节强制执行分栏符。

目录

// 关键:标题必须仅使用 HeadingLevel - 不使用自定义样式
new TableOfContents("目录", { hyperlink: true, headingStyleRange: "1-3" })

页眉/页脚

sections: [{
  properties: {
    page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 英寸
  },
  headers: {
    default: new Header({ children: [new Paragraph({ children: [new TextRun("页眉")] })] })
  },
  footers: {
    default: new Footer({ children: [new Paragraph({
      children: [new TextRun("第 "), new TextRun({ children: [PageNumber.CURRENT] }), new TextRun(" 页")]
    })] })
  },
  children: [/* 内容 */]
}]

docx-js 关键规则

  • 显式设置页面尺寸 - docx-js 默认使用 A4;对于美国文档,使用 US Letter(12240 x 15840 DXA)
  • 横向:传入纵向尺寸 - docx-js 内部会交换宽度/高度;将短边作为 width,长边作为 height,并设置 orientation: PageOrientation.LANDSCAPE
  • 绝不使用 \n - 使用单独的 Paragraph 元素
  • 绝不使用 unicode 项目符号 - 使用带有 numbering config 的 LevelFormat.BULLET
  • PageBreak 必须在 Paragraph 内部 - 独立使用会创建无效 XML
  • ImageRun 需要 type - 始终指定 png/jpg 等
  • 始终使用 DXA 设置表格 width - 绝不使用 WidthType.PERCENTAGE(在 Google Docs 中会出错)
  • 表格需要双重宽度 - columnWidths 数组和单元格 width,两者必须匹配
  • 表格宽度 = columnWidths 之和 - 对于 DXA,确保它们精确相加
  • 始终添加单元格边距 - 使用 margins: { top: 80, bottom: 80, left: 120, right: 120 } 以获得可读的内边距
  • 使用 ShadingType.CLEAR - 表格底纹绝不使用 SOLID
  • 绝不使用表格作为分隔线/规则 - 单元格有最小高度,会渲染为空框(包括在页眉/页脚中);改为在 Paragraph 上使用 border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }。对于双列页脚,使用制表位(参见制表位部分),而不是表格
  • TOC 仅需要 HeadingLevel - 标题段落上不使用自定义样式
  • 覆盖内置样式 - 使用精确的 ID:"Heading1"、"Heading2" 等。
  • 包含 outlineLevel - TOC 需要(H1 为 0,H2 为 1,以此类推)

编辑已有文档

按顺序执行所有 3 个步骤。

步骤 1:解包

python scripts/office/unpack.py document.docx unpacked/

提取 XML,美观打印,合并相邻的 runs,并将智能引号转换为 XML 实体(“ 等),以便它们在编辑后得以保留。使用 --merge-runs false 跳过 run 合并。

步骤 2:编辑 XML

编辑 unpacked/word/ 中的文件。模式参见下方的 XML 参考。

除非用户明确要求使用不同的名称,否则将“Claude”作为修订和批注的作者。

直接使用编辑工具进行字符串替换。不要编写 Python 脚本。 脚本会引入不必要的复杂性。编辑工具会精确显示要替换的内容。

关键:为新内容使用智能引号。 添加带有撇号或引号的文本时,请使用 XML 实体生成智能引号:

<!-- 为专业排版使用这些实体 -->
<w:t>这是&#x2019;一个引用:&#x201C;你好&#x201D;</w:t>
实体字符
&#x2018;'(左单引号)
&#x2019;'(右单引号/撇号)
&#x201C;“(左双引号)
&#x201D;”(右双引号)

添加批注: 使用 comment.py 处理跨多个 XML 文件的样板文件(文本必须是预先转义的 XML):

python scripts/comment.py unpacked/ 0 "包含 &amp; 和 &#x2019; 的批注文本"
python scripts/comment.py unpacked/ 1 "回复文本" --parent 0  # 回复批注 0
python scripts/comment.py unpacked/ 0 "文本" --author "自定义作者"  # 自定义作者名称

然后在 document.xml 中添加标记(参见 XML 参考中的批注)。

步骤 3:打包

python scripts/office/pack.py unpacked/ output.docx --original document.docx

使用自动修复进行验证,压缩 XML,并创建最终的 .docx 文件。


XML 参考

(待翻译的 XML 参考部分,保持原有结构和代码块)

...(原文已截断)

相关技能