文本与段落

文档由段落（paragraph）元素构成，每个段落包含带有独立格式的文本片段（text）子元素。

#Paragraph

JSON

{
  "sections": [
    {
      "children": [
        { "paragraph": { "children": ["Plain text paragraph."] } },
        { "paragraph": { "heading": "Heading1", "children": ["Chapter Title"] } }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        { paragraph: { children: ["Plain text paragraph."] } },
        { paragraph: { heading: "Heading1", children: ["Chapter Title"] } },
      ],
    },
  ],
});

#对齐与间距

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "alignment": "center",
            "spacing": { "before": 200, "after": 200, "line": 360 },
            "indent": { "left": 720 },
            "children": ["Centered paragraph with spacing and indent."]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            alignment: "center",
            spacing: { before: 200, after: 200, line: 360 },
            indent: { left: 720 },
            children: ["Centered paragraph with spacing and indent."],
          },
        },
      ],
    },
  ],
});

#边框

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "border": { "bottom": { "style": "single", "size": 6, "color": "999999" } },
            "children": ["Paragraph with a bottom border."]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            border: {
              bottom: { style: "single", size: 6, color: "999999" },
            },
            children: ["Paragraph with a bottom border."],
          },
        },
      ],
    },
  ],
});

#TextRun

每个文本片段可以设置独立的格式：

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              { "text": "Bold", "bold": true },
              { "text": ", Italic", "italic": true },
              { "text": ", Underline", "underline": { "type": "single" } },
              { "text": ", Strikethrough", "strike": true },
              { "text": ", 24pt", "size": 24 },
              { "text": ", Colored", "color": "FF0000" },
              { "text": ", Courier", "font": "Courier New" },
              { "text": ", Super", "verticalAlign": "superscript" },
              { "text": ", Sub", "verticalAlign": "subscript" }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              { text: "Bold", bold: true },
              { text: ", Italic", italic: true },
              { text: ", Underline", underline: { type: "single" } },
              { text: ", Strikethrough", strike: true },
              { text: ", 24pt", size: 24 },
              { text: ", Colored", color: "FF0000" },
              { text: ", Courier", font: "Courier New" },
              { text: ", Super", verticalAlign: "superscript" },
              { text: ", Sub", verticalAlign: "subscript" },
            ],
          },
        },
      ],
    },
  ],
});

#编号列表和项目符号列表

使用 Numbering 定义列表样式，然后在段落中引用：

JSON

{
  "numbering": {
    "abstractNumberings": [
      {
        "reference": "my-numbering",
        "levels": [
          { "level": 0, "format": "decimal", "text": "%1.", "alignment": "start" },
          { "level": 1, "format": "lowerLetter", "text": "%2)", "alignment": "start" }
        ]
      }
    ]
  },
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "numbering": { "reference": "my-numbering", "level": 0 },
            "children": ["First item"]
          }
        },
        {
          "paragraph": {
            "numbering": { "reference": "my-numbering", "level": 0 },
            "children": ["Second item"]
          }
        },
        {
          "paragraph": {
            "numbering": { "reference": "my-numbering", "level": 1 },
            "children": ["Nested sub-item"]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  numbering: {
    abstractNumberings: [
      {
        reference: "my-numbering",
        levels: [
          { level: 0, format: "decimal", text: "%1.", alignment: "start" },
          { level: 1, format: "lowerLetter", text: "%2)", alignment: "start" },
        ],
      },
    ],
  },
  sections: [
    {
      children: [
        {
          paragraph: {
            numbering: { reference: "my-numbering", level: 0 },
            children: ["First item"],
          },
        },
        {
          paragraph: {
            numbering: { reference: "my-numbering", level: 0 },
            children: ["Second item"],
          },
        },
        {
          paragraph: {
            numbering: { reference: "my-numbering", level: 1 },
            children: ["Nested sub-item"],
          },
        },
      ],
    },
  ],
});

对于项目符号列表，在级别配置中使用 format: "bullet"。

#制表位

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "tabStops": [{ "type": "left", "position": 10000 }],
            "children": ["Name", "TAB", "John Doe"]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            tabStops: [{ type: "left", position: 10000 }],
            children: ["Name", "TAB", "John Doe"],
          },
        },
      ],
    },
  ],
});

#分页符

在段落之间插入分页符：

JSON

{
  "sections": [
    {
      "children": [{ "paragraph": { "pageBreakBefore": true, "children": ["Start of new page"] } }]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [{ paragraph: { pageBreakBefore: true, children: ["Start of new page"] } }],
    },
  ],
});

#Paragraph 选项参考

选项	类型	说明
`alignment`	`"left" \| "center" \| "right" \| "distribute"`	水平对齐
`spacing.before`	`number`	段前间距（TWIP）
`spacing.after`	`number`	段后间距（TWIP）
`spacing.line`	`number`	行距（1/240 行）
`indent.left`	`number`	左缩进（TWIP）
`indent.right`	`number`	右缩进（TWIP）
`indent.firstLine`	`number`	首行缩进（TWIP）
`indent.hanging`	`number`	悬挂缩进（TWIP）
`heading`	`string`	标题级别（`"Heading1"` — `"Heading6"`）
`border`	`object`	段落边框
`pageBreakBefore`	`boolean`	强制在此段落前分页
`numbering`	`object`	列表引用和级别
`tabStops`	`array`	制表位定义
`style`	`string`	命名样式引用
`paraId`	`string`	段落唯一标识（8 位 hex，`w14:paraId`）
`textId`	`string`	段落文本标识（`w14:textId`）
`rsid`	`string`	修订 id（`w:rsidR`，hex）；相关：`defaultRunRsid`、`propertiesRsid`、`runPropertiesRsid`、`deletionRsid`
`textDirection`	`"lr" \| "rl" \| "tb" \| "tbV" \| "rlV" \| "lrV"`	文本流向（w:textDirection ST_TextDirection）
`textboxTightWrap`	`"none" \| "allLines" \| "firstAndLastLine" \| "firstLineOnly" \| "lastLineOnly"`	文本框内紧密环绕（w:textboxTightWrap）
`divId`	`number`	HTML div id 引用（w:divId）
`cnfStyle`	`object`	表格行/单元格条件格式标志（w:cnfStyle — firstRow/lastRow/firstColumn/lastColumn/...）

#TextRun 选项参考

| 选项 | 类型 | 说明 | | ------------------ | --------- | -------------------------------------------------------------------- | ------------- | ------------ | | text | string | 文本内容 | | bold | boolean | 粗体 | | italic | boolean | 斜体 | | underline | object | 下划线样式和类型 | | strike | boolean | 删除线 | | doubleStrike | boolean | 双删除线 | | verticalAlign | string | 下标 / 上标 / 基线（"subscript" | "superscript" | "baseline"） | | size | number | 字号（磅，12 = 12pt） | | color | string | 十六进制颜色（不带 #） | | font | string | 字体族名称 | | highlight | string | 高亮颜色 | | shading | object | 背景底纹 | | style | string | 命名字符样式引用 | | break | number | 换行次数 | | characterSpacing | number | 字符间距（TWIP） | | rsid | string | 修订 id（w:rsidR，hex）；相关：runPropertiesRsid、deletionRsid |