本文详解 docx 库中 addSection 方法不可用的根本原因及标准解决方案，强调必须通过构造函数初始化 Document 时预定义 sections 数组，而非运行时调用私有方法。
本文详解 `docx` 库中 `addsection` 方法不可用的根本原因及标准解决方案，强调必须通过构造函数初始化 `document` 时预定义 `sections` 数组，而非运行时调用私有方法。
在使用 docx（即 docxgen 的现代维护分支 @docxjs/docx 或原生 docx 库）生成 Word 文档时，开发者常误以为可像操作数组一样动态调用 doc.addSection(...) 来追加章节。但正如错误提示所示：
Property 'addSection' is private and only accessible within class 'File'
该方法确为私有（private），不可从外部调用——这是 TypeScript 类型系统与库设计的明确约束，并非 Bug，而是有意为之的 API 设计。
✅ 正确做法：所有章节（Section）必须在创建 Document 实例时，通过 sections 配置项一次性声明。
✅ 标准写法（推荐）
import { Document, Paragraph, TextRun, SectionProperties } from "@docxjs/docx";
// 构建完整的 sections 数组
const sections = [];
// 版本标题节
const versionList = Object.keys(releaseNote);
for (const key of versionList) {
const shouldInclude = cherryPick[key]?.some(Boolean);
if (!shouldInclude) continue;
// 版本标题段落
const titlePara = new Paragraph({
children: [
new TextRun({ text: key, bold: true, size: 16 }),
],
});
// 当前版本下的所有选中 release note 段落（带项目符号）
const noteParas = releaseNote[key]
.map((note: string, i: number) =>
cherryPick[key][i]
? new Paragraph({
children: [
new TextRun({ text: "• ", bold: true }),
new TextRun({ text: note }),
],
})
: null
)
.filter(Boolean) as Paragraph[];
// 合并为一个 section：含标题 + 所有选中条目
sections.push({
properties: {},
children: [titlePara, ...noteParas],
});
}
// ✅ 关键：将 sections 传入 Document 构造函数
const doc = new Document({
sections,
});
⚠️ 注意事项
- 不可事后追加：Document 实例创建后，其 sections 是只读结构；不存在 addSection 公共 API。
- Section 是顶层单元：每个 Section 可包含多个 Paragraph，无需为每个段落单独建 Section（否则会生成大量分页/分节符，破坏排版）。
- 性能更优：批量构建 sections 数组比模拟“流式添加”更符合库的设计哲学，也避免重复解析与序列化开销。
- 若需分页控制（如每版独立一页），可在 SectionProperties 中启用 breakType: "nextPage"：
properties: { breakType: "nextPage" }
? 总结
docx 库遵循“声明式文档构建”范式：你不是在编辑一个活文档对象，而是在构造一个描述文档结构的 JSON-like 配置树。因此，请始终以 数据驱动、一次性初始化 的方式组织 sections，而非尝试调用不存在的命令式方法。理解这一设计逻辑，是高效使用该库的关键前提。
