DOCX
样式与主题
用于字符和段落格式化的声明式样式系统
定义可复用的样式，使文档格式保持一致且易于维护。
定义样式
{
"styles": {
"default": {
"document": {
"run": {
"font": "Calibri",
"size": 22
},
"paragraph": {
"spacing": { "line": 276 }
}
}
},
"paragraphStyles": [
{
"id": "MyHeading",
"name": "My Heading",
"basedOn": "Heading1",
"run": {
"font": "Arial",
"size": 36,
"color": "2E74B5"
}
}
],
"characterStyles": [
{
"id": "CodeInline",
"name": "Code Inline",
"run": {
"font": "Consolas",
"size": 20,
"shading": { "fill": "F2F2F2" }
}
}
]
},
"sections": [
{
"children": [
{ "paragraph": { "style": "MyHeading", "children": ["Styled Heading"] } },
{
"paragraph": {
"children": ["Normal text with ", { "text": "inline code", "style": "CodeInline" }]
}
}
]
}
]
}
import { generateDocument } from "@office-open/docx";
await generateDocument({
styles: {
default: {
document: {
run: {
font: "Calibri",
size: 22,
},
paragraph: {
spacing: { line: 276 },
},
},
},
paragraphStyles: [
{
id: "MyHeading",
name: "My Heading",
basedOn: "Heading1",
run: {
font: "Arial",
size: 36,
color: "2E74B5",
},
},
],
characterStyles: [
{
id: "CodeInline",
name: "Code Inline",
run: {
font: "Consolas",
size: 20,
shading: { fill: "F2F2F2" },
},
},
],
},
sections: [
{
children: [
{ paragraph: { style: "MyHeading", children: ["Styled Heading"] } },
{
paragraph: {
children: ["Normal text with ", { text: "inline code", style: "CodeInline" }],
},
},
],
},
],
});
样式类型
| 类型 | ID | 说明 |
|---|---|---|
| 段落样式 | "paragraph" | 应用于整个段落 |
| 字符样式 | "character" | 应用于段落中的文本片段 |
| 表格样式 | "table" | 应用于表格 |
| 编号样式 | "numbering" | 应用于列表编号 |
表格样式
通过 styles.tableStyles[] 定义可复用的表格样式。每个样式可设置基础 table/row/cell 属性，并为特定区域（首行、条纹行等）设置条件格式：
import { generateDocument } from "@office-open/docx";
await generateDocument({
styles: {
tableStyles: [
{
id: "MyGrid",
name: "My Grid",
basedOn: "TableNormal",
conditionalFormats: [
{ type: "firstRow", run: { bold: true } },
{ type: "band1Horz", cell: { shading: { fill: "F2F2F2" } } },
],
},
],
},
sections: [
{
children: [{ table: { style: "MyGrid", rows: [{ cells: [{ children: ["A"] }] }] } }],
},
],
});
条件格式类型（type）
wholeTable · firstRow · lastRow · firstCol · lastCol · band1Vert · band2Vert · band1Horz · band2Horz · neCell · nwCell · seCell · swCell
每个条件格式接受可选的 paragraph、run、table、row、cell 属性块。表格样式在解析时以结构化数据往返。
默认样式
使用 default 属性覆盖文档默认值：
{
"styles": {
"default": {
"document": {
"run": { "font": "Calibri", "size": 22, "color": "333333" },
"paragraph": { "spacing": { "line": 276 } }
},
"heading1": {
"run": { "font": "Calibri Light", "size": 44, "color": "1F3763" }
}
}
},
"sections": [{ "children": [] }]
}
import { generateDocument } from "@office-open/docx";
await generateDocument({
styles: {
default: {
document: {
run: {
font: "Calibri",
size: 22, // 半点单位，即 11pt
color: "333333",
},
paragraph: {
spacing: { line: 276 }, // 1.15 倍行距
},
},
heading1: {
run: {
font: "Calibri Light",
size: 44,
color: "1F3763",
},
},
},
},
sections: [{ children: [] }],
});
使用样式
将样式应用于段落和文本片段：
{
"styles": {
"paragraphStyles": [
{ "id": "MyHeading", "name": "My Heading", "run": { "font": "Arial", "size": 36 } }
],
"characterStyles": [
{ "id": "CodeInline", "name": "Code Inline", "run": { "font": "Consolas", "size": 20 } }
]
},
"sections": [
{
"children": [
{ "paragraph": { "style": "MyHeading", "children": ["Styled Heading"] } },
{
"paragraph": {
"children": ["Normal text with ", { "text": "inline code", "style": "CodeInline" }]
}
}
]
}
]
}
// 段落样式
{ paragraph: { style: "MyHeading", children: [...] } }
// 文本片段上的字符样式
{ text: "styled", style: "CodeInline" }
外部样式
通过顶层的 externalStyles 选项（原始 XML 字符串）从现有文档导入整个 styles.xml。未定义的内置样式仍由默认工厂生成；此处定义的样式按 styleId 覆盖默认内置样式。
{
"externalStyles": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><w:styles xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"><w:style w:type=\"paragraph\" w:styleId=\"Heading1\"><w:name w:val=\"heading 1\"/><w:pPr><w:outlineLvl w:val=\"0\"/></w:pPr><w:rPr><w:color w:val=\"2E74B5\"/></w:rPr></w:style></w:styles>",
"sections": [{ "children": [] }]
}
import { generateDocument } from "@office-open/docx";
// externalStyles 是 <w:styles> 部件的原始 XML —— 例如从现有文档的 word/styles.xml 读取
await generateDocument({
externalStyles: `<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="heading 1"/>
<w:pPr><w:outlineLvl w:val="0"/></w:pPr>
<w:rPr><w:color w:val="2E74B5"/></w:rPr>
</w:style>
</w:styles>`,
sections: [
// ...
],
});
Style 选项参考
| 选项 | 类型 | 说明 |
|---|---|---|
id | string | 唯一样式标识符 |
name | string | 显示名称 |
type | "paragraph" | "character" | "table" | "numbering" | 样式类型 |
basedOn | string | 继承的父样式 |
run | object | 文本格式（字体、字号、颜色、粗体等） |
paragraph | object | 段落格式（间距、对齐等） |