# About docx
## 用法
组件结构
Document
├── sections
│ ├── headers
│ ├── footers
│ ├── properties
│ ├── children(Paragraph | Table | TableOfContents | Textbox)
├── title
├── subject
├── creator
├── keywords
├── description
├── lastModifiedBy
├── revision
├── externalStyles
├── styles
├── numbering
├── comments
├── footnotes
├── background
├── features
├── compatabilityModeVersion
├── compatibility
├── customProperties
├── evenAndOddHeaderAndFooters
├── defaultTabStop
├── fonts
└── hyphenation
### Document
组件结构
Document
├── sections
│ ├── headers
│ ├── footers
│ ├── properties
│ ├── children(Paragraph | Table | TableOfContents | Textbox)
├── title
├── subject
├── creator
├── keywords
├── description
├── lastModifiedBy
├── revision
├── externalStyles
├── styles
├── numbering
├── comments
├── footnotes
├── background
├── features
├── compatabilityModeVersion
├── compatibility
├── customProperties
├── evenAndOddHeaderAndFooters
├── defaultTabStop
├── fonts
└── hyphenation
选项表：
| 属性 | 类型 | 说明 |
| ---- | :----: | ---- |
| sections | ISectionOptions[] | 各章节相关内容 |
| title | string | 文章标题，仅为文件的属性 |
| subject | string | 文章主题，仅为文件的属性 |
| creator | string | 文章作者，仅为文件的属性 |
| keywords | string | 文章关键词，仅为文件的属性 |
| description | string | 文章描述，仅为文件的属性 |
| lastModifiedBy | string | 文章最后修订者 |
| revision | string | 文章修订版本号 |
| externalStyles | string | 文章修订版本号 |
| styles | IStylesOptions | 配置文档样式，待研究 |
| numbering | INumberingOptions | 有序/无序列表编号配置 |
| comments | ICommentsOptions | 评论配置 |
| footnotes | Record | 脚注配置 |
| background | IDocumentBackgroundOptions | 文档背景配置 |
| features | { trackRevisions?: boolean; updateFields?: boolean; } | 特征配置 |
| compatabilityModeVersion | number | 兼容模式版本 |
| compatibility | ICompatibilityOptions | 兼容性配置 |
#### 特殊字段说明
##### externalStyles
导入外部样式内容导入，内容格式为xml。
样式导入后，可在段落中设置指定样式。
代码示例：
```ts
// This example shows 3 styles using XML styles
import * as fs from "fs";
import { Document, HeadingLevel, Packer, Paragraph } from "docx";
const styles = fs.readFileSync("./demo/assets/custom-styles.xml", "utf-8");
const doc = new Document({
title: "Title",
externalStyles: styles,
sections: [
{
children: [
new Paragraph({
text: "Cool Heading Text",
heading: HeadingLevel.HEADING_1,
}),
new Paragraph({
text: 'This is a custom named style from the template "MyFancyStyle"',
style: "MyFancyStyle",
}),
new Paragraph("Some normal text"),
new Paragraph({
text: "MyFancyStyle again",
style: "MyFancyStyle",
}),
],
},
],
});
Packer.toBuffer(doc).then((buffer) => {
fs.writeFileSync("My Document.docx", buffer);
});
```
样式文件示例：
```xml
```
#### features
本字段可以实现配置**变更跟踪**和**目录更新**
**变更跟踪**
启用 trackRevisions 功能后，可实现自动跟踪文档新的修订。
```ts
import { Document } from "docx";
const doc = new Document({
features: {
trackRevisions: true,
},
});
```
**目录更新**
必须启用 updateFields 功能才能正确更新 TableOfContents。
```ts
const doc = new Document({
features: {
updateFields: true,
},
sections: [
{
children: [
new TableOfContents("Summary", {
hyperlink: true,
headingStyleRange: "1-5",
}),
new Paragraph({
text: "Header #1",
heading: HeadingLevel.HEADING_1,
pageBreakBefore: true,
}),
]
}
]
});
```
#### compatabilityModeVersion
兼容模式是指当你用较新版本的 Word 打开一个旧版本（如 Word 97-2003 .doc）的文档，或者从老版本升级而未转换为最新格式时，Word 会进入 兼容模式（Compatibility Mode）。此模式会：
- 禁用一些新特性（如新样式、新对象）
- 模拟旧版本的渲染方式
- 避免向后不兼容
| Version | 对应 Word 版本 | 说明 |
| --------- | ------------------ | ------------- |
| 11 | Word 2003 | `.doc` 格式兼容模式 |
| 12 | Word 2007 | 早期 `.docx` 格式 |
| 14 | Word 2010 | 支持部分新样式 |
| 15 | Word 2013 | 默认兼容版本之一 |
| 16 | Word 2016/2019/365 | 最新兼容模式 |
#### compatibility
兼容性设置是可选设置，用于保留早期文字处理应用程序中创建的文档的视觉保真度。其中一些设置提供了特定行为的功能（详见下文）；而其他设置则只是指示应用程序模仿现有文字处理应用程序的行为。
```ts
const doc = new docx.Document({
compatibility: {
version: 15,
doNotExpandShiftReturn: true,
},
});
```
兼容性选项表：
| 属性 | 类型 | 值 | 说明 |
| ---- | :----: | ---- | ---- |
| version | number | 15, 16, 17 | 最小兼容版本 |
| useSingleBorderforContiguousCells | boolean | true, false, undefined | 相邻单元格仅绘制一条边框，模仿旧 Word 表格合并边框行为 |
| wordPerfectJustification | boolean | true, false, undefined | |
| noTabStopForHangingIndent | boolean | true, false, undefined | |
| noLeading | boolean | true, false, undefined | |
| spaceForUnderline | boolean | true, false, undefined | |
| noColumnBalance | boolean | true, false, undefined | |
| balanceSingleByteDoubleByteWidth | boolean | true, false, undefined | |
| noExtraLineSpacing | boolean | true, false, undefined | |
| doNotLeaveBackslashAlone | boolean | true, false, undefined | 不要单独使用反斜杠 |
| underlineTrailingSpaces | boolean | true, false, undefined | 给尾随空格加下划线 |
| doNotExpandShiftReturn | boolean | true, false, undefined | 尾随空格换行 |
| spacingInWholePoints | boolean | true, false, undefined | |
| lineWrapLikeWord6 | boolean | true, false, undefined | 模仿 Word 6 的自动换行规则 |
| printBodyTextBeforeHeader | boolean | true, false, undefined | |
| printColorsBlack | boolean | true, false, undefined | |
| spaceWidth | boolean | true, false, undefined | |
| showBreaksInFrames | boolean | true, false, undefined | |
| subFontBySize | boolean | true, false, undefined | |
| suppressBottomSpacing | boolean | true, false, undefined | |
| suppressTopSpacing | boolean | true, false, undefined | |
| suppressSpacingAtTopOfPage | boolean | true, false, undefined | |
| suppressTopSpacingWP | boolean | true, false, undefined | |
| suppressSpBfAfterPgBrk | boolean | true, false, undefined | |
| swapBordersFacingPages | boolean | true, false, undefined | |
| convertMailMergeEsc | boolean | true, false, undefined | |
| truncateFontHeightsLikeWP6 | boolean | true, false, undefined | |
| macWordSmallCaps | boolean | true, false, undefined | |
| usePrinterMetrics | boolean | true, false, undefined | |
| doNotSuppressParagraphBorders | boolean | true, false, undefined | |
| wrapTrailSpaces | boolean | true, false, undefined | |
| footnoteLayoutLikeWW8 | boolean | true, false, undefined | |
| shapeLayoutLikeWW8 | boolean | true, false, undefined | |
| alignTablesRowByRow | boolean | true, false, undefined | 表格逐行排列，不一次性渲染整表，以保持旧版 Word 排版一致 |
| forgetLastTabAlignment | boolean | true, false, undefined | |
| adjustLineHeightInTable | boolean | true, false, undefined | |
| autoSpaceLikeWord95 | boolean | true, false, undefined | |
| noSpaceRaiseLower | boolean | true, false, undefined | |
| doNotUseHTMLParagraphAutoSpacing | boolean | true, false, undefined | |
| layoutRawTableWidth | boolean | true, false, undefined | 控制旧版 Word 处理表格宽度的方式 |
| layoutTableRowsApart | boolean | true, false, undefined | 控制旧版 Word 处理表格行间距的方式 |
| useWord97LineBreakRules | boolean | true, false, undefined | 模仿Word 97 的自动换行规则 |
| doNotBreakWrappedTables | boolean | true, false, undefined | 防止表格在文本换行点拆分 |
| doNotSnapToGridInCell | boolean | true, false, undefined | |
| selectFieldWithFirstOrLastCharacter | boolean | true, false, undefined | |
| applyBreakingRules | boolean | true, false, undefined | |
| doNotWrapTextWithPunctuation | boolean | true, false, undefined | |
| doNotUseEastAsianBreakRules | boolean | true, false, undefined | |
| useWord2002TableStyleRules | boolean | true, false, undefined | |
| growAutofit | boolean | true, false, undefined | |
| useFELayout | boolean | true, false, undefined | |
| useNormalStyleForList | boolean | true, false, undefined | |
| doNotUseIndentAsNumberingTabStop | boolean | true, false, undefined | |
| useAlternateEastAsianLineBreakRules | boolean | true, false, undefined | |
| allowSpaceOfSameStyleInTable | boolean | true, false, undefined | |
| doNotSuppressIndentation | boolean | true, false, undefined | |
| doNotAutofitConstrainedTables | boolean | true, false, undefined | 关闭受限表格的自动调整 |
| autofitToFirstFixedWidthCell | boolean | true, false, undefined | 仅根据首列的固定宽度进行自适应 |
| underlineTabInNumberingList | boolean | true, false, undefined | |
| displayHangulFixedWidth | boolean | true, false, undefined | |
| splitPgBreakAndParaMark | boolean | true, false, undefined | |
| doNotVerticallyAlignCellWithSp | boolean | true, false, undefined | |
| doNotBreakConstrainedForcedTable | boolean | true, false, undefined | |
| ignoreVerticalAlignmentInTextboxes | boolean | true, false, undefined | |
| useAnsiKerningPairs | boolean | true, false, undefined | |
| cachedColumnBalance | boolean | true, false, undefined | |
### Paragraph
Paragraph
├── TextRun
├── ImageRun
├── SymbolRun
├── Bookmark
├── PageBreak
├── ColumnBreak
├── SequentialIdentifier
├── FootnoteReferenceRun
├── InternalHyperlink
├── ExternalHyperlink
├── InsertedTextRun/DeletedTextRun
├── Math
├── SimpleField/SimpleMailMergeField
├── CommentRangeStart/CommentRangeEnd
├── CommentReference/Comments/Comment
└── CheckBox
### Table
### TableOfContents
### Textbox