使用 docx 库在 JS/TS 文档中生成 Word 脚注（Footnotes）的完整指南

使用 docx 库在 JS/TS 文档中生成 Word 脚注Footnotes的完整指南【免费下载链接】docxEasily generate and modify .docx files with JS/TS with a nice declarative API. Works for Node and on the Browser.项目地址: https://gitcode.com/GitHub_Trending/do/docx导读本文基于 docxGitHub Trending 精选项目 do/docx官方文档 footnotes.md 展开系统讲解如何用声明式 API 在 .docx 文档中创建脚注从Document构造器的footnotes配置、正文中的FootnoteReferenceRun引用标记到脚注内嵌图片、编号列表等进阶用法并结合仓库源码剖析脚注在 OOXMLWordprocessingML底层的实现原理。读完本文你将能在 Node.js 与浏览器环境中熟练地生成带专业脚注的 Word 文档。什么是脚注Footnote脚注是出现在每一页底部的引用说明。与正文中插入的括号注释或长段落不同脚注把解释、评论或引用来源放在页面底部让正文阅读流保持顺畅——这正是学术论文、技术手册和法律文书中常见的排版习惯。在 OOXML 规范中脚注对应w:footnotes部件与w:footnote元素正文通过w:footnoteReference引用标记关联到具体的脚注内容。docx 库以 TypeScript 类型安全的方式封装了这一切。[!NOTE] 使用脚注前建议先理解 Sections分节因为脚注最终会随页面布局渲染在每一节的页面底部如果你的需求是在文档末尾统一收拢注释请参见 Endnotes尾注。最小示例第一个脚注先看官方文档给出的最小完整示例。这段代码创建了一个包含两个脚注的文档import { Document, FootnoteReferenceRun, Paragraph, TextRun } from docx; const doc new Document({ footnotes: { 1: { children: [new Paragraph(Foo), new Paragraph(Bar)] }, 2: { children: [new Paragraph(Test)] }, }, sections: [ { children: [ new Paragraph({ children: [ new TextRun({ children: [Hello], }), new FootnoteReferenceRun(1), new TextRun({ children: [ World!], }), new FootnoteReferenceRun(2), ], }), ], }, ], });代码分三层脚注定义在Document构造器的footnotes属性中按 id 声明脚注内容1号脚注包含两段2号脚注包含一段正文引用在段落children中插入FootnoteReferenceRun(1)、FootnoteReferenceRun(2)即在 Hello 与 World! 之间生成上标引用标记自动编号与渲染docx 会自动维护脚注编号并生成w:footnotes.xml部件无需手动管理分隔线等内部结构。文档配置footnotes 属性详解脚注通过Document构造器的footnotes属性声明其类型为PropertyTypeNotesDescriptionfootnotesRecordstring, { children: Paragraph[] }OptionalFootnote definitions keyed by reference number关键规则键Key是引用编号的字符串形式例如1、2它必须与正文中FootnoteReferenceRun(id)的id一一对应值Value是包含children: Paragraph[]的对象每个脚注可由多个Paragraph组成从而支持多段落的脚注正文该属性为可选不配置则文档不包含任何脚注。从源码看脚注部件如何生成当配置了footnotes后文档会经由 footnotes-wrapper.ts 中的FootnotesWrapper实现IViewWrapper接口挂载FootNotes部件与对应的Relationships关系文件。在 footnotes.ts 中FootNotes类构造时super(w:footnotes)会自动写入两个特殊脚注这与 Word 的规范一致id: -1的separator分隔线脚注定义正文与脚注之间的分隔横线id: 0的continuationSeparator延续分隔线脚注当脚注跨页延续时使用的分隔线。它们的段落都设置了spacing: { after: 0, line: 240, lineRule: AUTO }即单倍行距、无段后间距。因此你的业务脚注 id 从1开始即可不必关心这两个保留项——这正是 footnotes.ts 自动完成的工作。随后createFootNote(id, paragraph)方法会把每个业务脚注追加到集合中footnotes.ts。FootnoteReferenceRun正文中的引用标记在正文段落中插入new FootnoteReferenceRun(id)即可创建引用标记接受单个id参数必须与footnotes中的键匹配自动应用上标样式无需手动设置superScript在生成的 .docx 中点击该标记Word 会跳转到对应脚注内容。底层实现从 run 到 OOXML 元素FootnoteReferenceRun定义在 reference-run.ts它继承Run构造时应用名为FootnoteReference的字符样式并压入FootnoteReference组件export class FootnoteReferenceRun extends Run { public constructor(id: number) { super({ style: FootnoteReference }); this.root.push(new FootnoteReference(id)); } }FootnoteReference渲染为w:footnoteReference元素并通过FootNoteReferenceRunAttributes输出w:id属性reference-run.ts从而把正文标记与脚注内容关联起来。而FootnoteReference字符样式的真正定义在 default-styles.tsFootnoteReferenceStyle设置了superScript: true这正是自动上标的来源。同样地脚注正文内部也无需手动写编号在 footnote.ts 中Footnote类会把FootnoteRefRun渲染为w:footnoteRef元素见 footnote-ref.ts自动插入到脚注第一个段落的开头作为脚注内容前的自动引用标记而脚注正文段落默认继承FootnoteText段落样式id 为FootnoteText字号 20 half-points 即 10pt、行距 240/自动、段后 0见 default-styles.ts与 Word 内置的脚注文本样式保持一致。进阶用法一在脚注中嵌入图片脚注内容本质上是Paragraph数组因此可以复用文档中的一切段落能力——包括图片。官方文档的图片示例import { Document, FootnoteReferenceRun, ImageRun, Packer, Paragraph, TextRun } from docx; import * as fs from fs; const doc new Document({ footnotes: { 1: { children: [ new Paragraph({ children: [ new ImageRun({ type: jpg, data: fs.readFileSync(./image.jpg), transformation: { width: 100, height: 100, }, }), new TextRun(Caption for the image), ], }), ], }, }, sections: [ { children: [ new Paragraph({ children: [new TextRun(See the image), new FootnoteReferenceRun(1)], }), ], }, ], });要点ImageRun需要指定type如jpg、png与dataBuffer或 base64 字符串transformation控制宽高图片可以与TextRun混排在同一段落作为脚注配图与图注别忘了Packer在 Node 环境用Packer.toBuffer(doc)生成最终文件浏览器环境可使用Packer.toBlob。进阶用法二脚注中的编号列表与项目符号脚注内支持编号列表和项目符号列表。此时需要先在Document.numbering中定义编号配置再让脚注中的段落通过numbering引用它import { AlignmentType, convertInchesToTwip, Document, FootnoteReferenceRun, LevelFormat, Packer, Paragraph, TextRun } from docx; const doc new Document({ numbering: { config: [ { reference: footnote-numbering, levels: [ { level: 0, format: LevelFormat.DECIMAL, text: %1., alignment: AlignmentType.START, style: { paragraph: { indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.18) }, }, }, }, ], }, ], }, footnotes: { 1: { children: [ new Paragraph(This footnote contains a list:), new Paragraph({ text: First item, numbering: { reference: footnote-numbering, level: 0 }, }), new Paragraph({ text: Second item, numbering: { reference: footnote-numbering, level: 0 }, }), ], }, }, sections: [ { children: [ new Paragraph({ children: [new TextRun(See the list), new FootnoteReferenceRun(1)], }), ], }, ], });配置拆解numbering.config中声明一个名为footnote-numbering的编号实例level: 0定义第一级编号LevelFormat.DECIMAL表示十进制编号text: %1.决定编号显示为1.、2.形式convertInchesToTwip(0.5)与convertInchesToTwip(0.18)分别把 0.5 英寸与 0.18 英寸转换为 twip 单位形成左缩进 悬挂缩进的列表视觉脚注内的列表段落通过numbering: { reference: footnote-numbering, level: 0 }挂接该编号。这里引入AlignmentType是因为编号层级可指定对齐方式如AlignmentType.STARTPacker用于最终导出。项目符号列表的写法完全一致只需把LevelFormat.DECIMAL换成LevelFormat.BULLET并将text改为•之类符号。完整可运行 Demo官方仓库在 demo/17-footnotes.ts 提供了完整示例它定义了 6 个脚注涵盖多段落脚注、脚注内嵌编号列表、脚注内嵌图片读取./demo/images/cat.jpg并在两个 section 中分别引用不同编号的脚注最后通过Packer.toBuffer写出My Document.docx。可以直接对照该文件验证本文所有用法并结合 docs/usage/sections.md 理解多分节下脚注编号的分布行为。小结脚注在Document的footnotes属性中按Recordstring, { children: Paragraph[] }声明键即引用编号正文用FootnoteReferenceRun(id)插入引用标记自动上标并与脚注内容关联脚注内容可包含多段落、图片ImageRun与编号/项目符号列表底层由 FootNotes 自动补齐分隔线id: -1与延续分隔线id: 0脚注正文自动获得FootnoteText段落样式与w:footnoteRef引用标记需要文档末尾统一收拢的注释时参见 Endnotes尾注。掌握以上 API即可在 Node 与浏览器端用纯 TypeScript 产出带规范脚注的专业文档。【免费下载链接】docxEasily generate and modify .docx files with JS/TS with a nice declarative API. Works for Node and on the Browser.项目地址: https://gitcode.com/GitHub_Trending/do/docx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考