Skip to content

Fantasia1999/skills-zh / translations/docx

当用户想要创建、读取、编辑或操作 Word 文档(.docx 文件)时,使用此技能。触发条件包括:任何提及“Word 文档”、“word document”、“.docx”的情况,或要求生成包含目录、标题、页码或信头等格式的专业文档。当从 .docx 文件中提取或重组内容、在文档中插入或替换图片、在 Word 文件中执行查找和替换、处理修订或批注,或将内容转换为精美的 Word 文档时,也应使用此技能。如果用户要求将“报告”、“备忘录”、“信函”、“模板”或类似的交付成果作为 Word 或 .docx 文件,请使用此技能。请勿用于 PDF、电子表格、Google Docs 或与文档生成无关的常规编码任务。

DOCX 创建、编辑与分析

概述

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

快速参考

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

将 .doc 转换为 .docx

旧版的 .doc 文件在编辑前必须进行转换:

python scripts/office/soffice.py --headless --convert-to docx document.doc

读取内容

# 提取带有修订记录的文本
pandoc --track-changes=all document.docx -o output.md

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

转换为图片

python scripts/office/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

接受修订

要生成一个接受了所有修订的干净文档(需要 LibreOffice):

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: [/* content */] }] });
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: [/* content */]
}]

常用页面尺寸(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 } }, // 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("Title")] }),
    ]
  }]
});

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

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

// ✅ 正确 - 使用带 LevelFormat.BULLET 的编号配置
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("Bullet item")] }),
      new Paragraph({ numbering: { reference: "numbers", level: 0 },
        children: [new TextRun("Numbered item")] }),
    ]
  }]
});

// ⚠️ 每个 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("Cell")] })]
        })
      ]
    })
  ]
})

表格宽度计算:

始终使用 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 不兼容)
  • 表格 width 必须等于 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: "Title", description: "Desc", name: "Name" } // 三者都必需
  })]
})

分页符

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

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

超链接

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

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

脚注

const doc = new Document({
  footnotes: {
    1: { children: [new Paragraph("Source: Annual Report 2024")] },
    2: { children: [new Paragraph("See appendix for methodology")] },
  },
  sections: [{
    children: [new Paragraph({
      children: [
        new TextRun("Revenue grew 15%"),
        new FootnoteReferenceRun(1),
        new TextRun(" using adjusted metrics"),
        new FootnoteReferenceRun(2),
      ],
    })]
  }]
});

制表位

// 在同一行右对齐文本 (例如,标题对面的日期)
new Paragraph({
  children: [
    new TextRun("Company Name"),
    new TextRun("\tJanuary 2025"),
  ],
  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})

// 点状前导符 (例如,目录样式)
new Paragraph({
  children: [
    new TextRun("Introduction"),
    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: [/* content */]
}]

使用 type: SectionType.NEXT_COLUMN 的新节来强制分栏。

目录

// 关键:标题必须仅使用 HeadingLevel - 不能使用自定义样式
new TableOfContents("Table of Contents", { 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("Header")] })] })
  },
  footers: {
    default: new Footer({ children: [new Paragraph({
      children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
    })] })
  },
  children: [/* content */]
}]

docx-js 的关键规则

  • 明确设置页面尺寸 - docx-js 默认为 A4;美国文档请使用 US Letter (12240 x 15840 DXA)
  • 横向:传入纵向尺寸 - docx-js 内部会交换宽高;将短边作为 width,长边作为 height 传入,并设置 orientation: PageOrientation.LANDSCAPE
  • 绝不使用 \n - 使用独立的 Paragraph 元素
  • 绝不使用 unicode 项目符号 - 使用带编号配置的 LevelFormat.BULLET
  • PageBreak 必须在 Paragraph 内 - 独立使用会创建无效的 XML
  • ImageRun 需要 type - 始终指定 png/jpg/etc
  • 始终使用 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 } } 代替。对于两栏页脚,使用制表位(见“制表位”部分),而非表格
  • 目录仅需要 HeadingLevel - 标题段落不能有自定义样式
  • 覆盖内置样式 - 使用确切的 ID:"Heading1", "Heading2" 等
  • 包含 outlineLevel - 目录所必需 (H1 为 0,H2 为 1,依此类推)

编辑现有文档

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

第 1 步:解包

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

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

第 2 步:编辑 XML

编辑 unpacked/word/ 目录下的文件。有关模式,请参阅下面的 XML 参考。

使用 "Claude" 作为作者来进行修订和批注,除非用户明确要求使用其他名称。

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

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

<!-- 使用这些实体以获得专业的排版效果 -->
<w:t>Here&#x2019;s a quote: &#x201C;Hello&#x201D;</w:t>
实体字符
&#x2018;‘ (左单引号)
&#x2019;’ (右单引号 / 撇号)
&#x201C;“ (左双引号)
&#x201D;” (右双引号)

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

python scripts/comment.py unpacked/ 0 "Comment text with &amp; and &#x2019;"
python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # 回复批注 0
python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author"  # 自定义作者名

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

第 3 步:打包

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

使用自动修复进行验证,压缩 XML,并创建 DOCX。使用 --validate false 跳过验证。

自动修复将解决:

  • durableId >= 0x7FFFFFFF (重新生成有效的 ID)
  • 带有空白的 <w:t> 缺少 xml:space="preserve"

自动修复无法解决:

  • 格式错误的 XML、无效的元素嵌套、缺少关系、模式违规

常见陷阱

  • 替换整个 <w:r> 元素:添加修订时,用 <w:del>...<w:ins>... 作为同级元素替换整个 <w:r>...</w:r> 块。不要在 run 内部注入修订标记。
  • 保留 <w:rPr> 格式:将原始 run 的 <w:rPr> 块复制到你的修订 run 中,以保持粗体、字号等格式。

XML 参考

模式合规性

  • <w:pPr> 中的元素顺序:<w:pStyle>, <w:numPr>, <w:spacing>, <w:ind>, <w:jc>, <w:rPr> 最后
  • 空白:为带有前导/尾随空格的 <w:t> 添加 xml:space="preserve"
  • RSIDs:必须是 8 位十六进制数 (例如, 00AB1234)

修订

插入:

<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:t>inserted text</w:t></w:r>
</w:ins>

删除:

<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>deleted text</w:delText></w:r>
</w:del>

在 <w:del> 内部:使用 <w:delText> 代替 <w:t>,使用 <w:delInstrText> 代替 <w:instrText>。

最小化编辑 - 只标记变化的部分:

<!-- 将 "30 days" 改为 "60 days" -->
<w:r><w:t>The term is </w:t></w:r>
<w:del w:id="1" w:author="Claude" w:date="...">
  <w:r><w:delText>30</w:delText></w:r>
</w:del>
<w:ins w:id="2" w:author="Claude" w:date="...">
  <w:r><w:t>60</w:t></w:r>
</w:ins>
<w:r><w:t> days.</w:t></w:r>

删除整个段落/列表项 - 当移除段落的所有内容时,同时将段落标记标记为已删除,以便它与下一段落合并。在 <w:pPr><w:rPr> 内添加 <w:del/>:

<w:p>
  <w:pPr>
    <w:numPr>...</w:numPr>  <!-- 如果存在,则是列表编号 -->
    <w:rPr>
      <w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
    </w:rPr>
  </w:pPr>
  <w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
    <w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r>
  </w:del>
</w:p>

如果没有 <w:pPr><w:rPr> 中的 <w:del/>,接受修订后会留下一个空段落/列表项。

拒绝另一位作者的插入 - 在他们的插入内部嵌套删除:

<w:ins w:author="Jane" w:id="5">
  <w:del w:author="Claude" w:id="10">
    <w:r><w:delText>their inserted text</w:delText></w:r>
  </w:del>
</w:ins>

恢复另一位作者的删除 - 在后面添加插入(不要修改他们的删除):

<w:del w:author="Jane" w:id="5">
  <w:r><w:delText>deleted text</w:delText></w:r>
</w:del>
<w:ins w:author="Claude" w:id="10">
  <w:r><w:t>deleted text</w:t></w:r>
</w:ins>

批注

运行 comment.py(见第 2 步)后,向 document.xml 添加标记。对于回复,使用 --parent 标志并将标记嵌套在父标记内。

关键:<w:commentRangeStart> 和 <w:commentRangeEnd> 是 <w:r> 的同级元素,绝不能在 <w:r> 内部。

<!-- 批注标记是 w:p 的直接子元素,绝不在 w:r 内部 -->
<w:commentRangeStart w:id="0"/>
<w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>deleted</w:delText></w:r>
</w:del>
<w:r><w:t> more text</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>

<!-- 批注 0 及其内部嵌套的回复 1 -->
<w:commentRangeStart w:id="0"/>
  <w:commentRangeStart w:id="1"/>
  <w:r><w:t>text</w:t></w:r>
  <w:commentRangeEnd w:id="1"/>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>

图片

  1. 将图片文件添加到 word/media/
  2. 向 word/_rels/document.xml.rels 添加关系:
<Relationship Id="rId5" Type=".../image" Target="media/image1.png"/>
  1. 向 [Content_Types].xml 添加内容类型:
<Default Extension="png" ContentType="image/png"/>
  1. 在 document.xml 中引用:
<w:drawing>
  <wp:inline>
    <wp:extent cx="914400" cy="914400"/>  <!-- EMU 单位:914400 = 1 英寸 -->
    <a:graphic>
      <a:graphicData uri=".../picture">
        <pic:pic>
          <pic:blipFill><a:blip r:embed="rId5"/></pic:blipFill>
        </pic:pic>
      </a:graphicData>
    </a:graphic>
  </wp:inline>
</w:drawing>

依赖项

  • pandoc: 文本提取
  • docx: npm install -g docx (新文档)
  • LibreOffice: PDF 转换 (通过 scripts/office/soffice.py 为沙盒环境自动配置)
  • Poppler: pdftoppm 用于图片处理
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall