DOCX

批注与修订

文档批注、修订跟踪和结构化文档标签（内容控件）

批注

用 comment 子元素添加批注，把它放在所批注文字的旁边：

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              "这段文字被",
              {
                "comment": {
                  "author": "Author Name",
                  "initials": "AN",
                  "children": ["请审阅此部分。"],
                  "wrap": [{ "text": "批注" }]
                }
              },
              "。"
            ]
          }
        }
      ]
    }
  ]
}

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              "这段文字被",
              {
                comment: {
                  author: "Author Name",
                  initials: "AN",
                  date: new Date(),
                  children: ["请审阅此部分。"],
                  wrap: [{ text: "批注" }],
                },
              },
              "。",
            ],
          },
        },
      ],
    },
  ],
});

children 是批注回复正文（存入 comments part，可为任意段落内容）；wrap 是批注范围所覆盖的文档文字（行内 run/文本）。

属性	类型	说明
`author`	`string`	批注作者（默认为空）
`initials`	`string`	作者缩写
`date`	`Date \| string`	创建时间（默认为当前）
`children`	`(string \| ParagraphOptions)[]`	批注回复正文
`wrap`	`(string \| RunOptions)[]`	范围所包裹的锚定文字

显式标记（高级）

当范围跨越多个段落或表格，或需要续接已有文档的 id 时，可显式书写标记。commentRangeStart、commentRangeEnd 与 commentReference 必须共用同一个 id，且与 comments 条目匹配：

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

await generateDocument({
  comments: {
    children: [
      {
        id: 0,
        author: "Author Name",
        date: new Date(),
        children: ["请审阅此部分。"],
      },
    ],
  },
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              { commentRangeStart: { id: 0 } },
              "这段文字附带批注。",
              { commentRangeEnd: { id: 0 } },
              { commentReference: 0 },
            ],
          },
        },
      ],
    },
  ],
});

修订跟踪

跟踪文档中的插入、删除和移动：

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              "原始文本，",
              {
                "insertion": {
                  "id": 0,
                  "author": "Author",
                  "date": "2024-01-15T10:30:00Z",
                  "text": "插入的文本"
                }
              },
              "，以及",
              {
                "deletion": {
                  "id": 1,
                  "author": "Author",
                  "date": "2024-01-15T10:30:00Z",
                  "text": "删除的文本"
                }
              },
              "。"
            ]
          }
        }
      ]
    }
  ]
}

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

// 插入
await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                insertion: {
                  id: 0,
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                  text: "此文本已被插入。",
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

// 删除
await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                deletion: {
                  id: 1,
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                  text: "此文本已被删除。",
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

移动修订

用 moveFrom（源）和 moveTo（目标）子元素跟踪移动的内容。同一次移动的 moveFrom 与 moveTo 必须共用同一个 name，Word 才能将它们配对：

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              "这段文字被 ",
              {
                "moveFrom": {
                  "name": "my-move",
                  "author": "Author",
                  "date": "2024-01-15T10:30:00Z",
                  "wrap": [{ "text": "移动的文本" }]
                }
              },
              "。"
            ]
          }
        },
        {
          "paragraph": {
            "children": [
              "它出现在这里：",
              {
                "moveTo": {
                  "name": "my-move",
                  "author": "Author",
                  "date": "2024-01-15T10:30:00Z",
                  "wrap": [{ "text": "移动的文本" }]
                }
              },
              "。"
            ]
          }
        }
      ]
    }
  ]
}

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              "这段文字被 ",
              {
                moveFrom: {
                  name: "my-move",
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                  wrap: [{ text: "移动的文本" }],
                },
              },
              "。",
            ],
          },
        },
        {
          paragraph: {
            children: [
              "它出现在这里：",
              {
                moveTo: {
                  name: "my-move",
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                  wrap: [{ text: "移动的文本" }],
                },
              },
              "。",
            ],
          },
        },
      ],
    },
  ],
});

wrap 是移动 run 所承载的移动内容（行内 run/文本）。author 和 date 同时作用于范围起始标记和移动 run。

属性	类型	说明
`name`	`string`	移动名称——from/to 配对须共用
`author`	`string`	移动作者
`date`	`string`	ISO 8601 时间戳
`wrap`	`(string \| RunOptions)[]`	移动 run 承载的移动内容
`colFirst`	`number`	表格单元格范围的起始列
`colLast`	`number`	表格单元格范围的结束列
`displacedByCustomXml`	`"before" \| "after"`	相邻 customXml 的位移方向

显式标记（高级）

当需要跨段范围、显式 id 续编或独立放置标记时，可分别书写范围标记与移动 run。moveFromRangeStart/moveFromRangeEnd 标记源、moveToRangeStart/moveToRangeEnd 标记目标；movedFrom/movedTo 以修订 run 的形式承载被移动的文本：

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

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                moveFromRangeStart: {
                  id: 0,
                  name: "my-move",
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                },
              },
              {
                movedFrom: {
                  id: 1,
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                  children: ["移动的文本"],
                },
              },
              { moveFromRangeEnd: { id: 0 } },
            ],
          },
        },
        {
          paragraph: {
            children: [
              {
                moveToRangeStart: {
                  id: 2,
                  name: "my-move",
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                },
              },
              {
                movedTo: {
                  id: 3,
                  author: "Author",
                  date: "2024-01-15T10:30:00Z",
                  children: ["移动的文本"],
                },
              },
              { moveToRangeEnd: { id: 2 } },
            ],
          },
        },
      ],
    },
  ],
});

范围起始标记接受 id（必填）以及 name、author、date 和表格列范围（colFirst/colLast）；范围结束标记只需 { id }。

结构化文档标签（内容控件）

使用 SDT 创建可编辑区域和表单控件：

{
  "sections": [
    {
      "children": [
        {
          "sdt": {
            "properties": { "alias": "FullName", "tag": "full-name", "richText": true },
            "children": [{ "paragraph": { "children": ["John Doe"] } }]
          }
        },
        {
          "sdt": {
            "properties": {
              "alias": "Color",
              "tag": "combo-color",
              "comboBox": {
                "items": [
                  { "displayText": "Red", "value": "red" },
                  { "displayText": "Blue", "value": "blue" }
                ],
                "lastValue": "Red"
              }
            },
            "children": [{ "paragraph": { "children": ["Red"] } }]
          }
        }
      ]
    }
  ]
}

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

// 块级内容控件
await generateDocument({
  sections: [
    {
      children: [
        {
          sdt: {
            properties: {
              alias: "FullName",
              tag: "full-name",
              richText: true,
            },
            children: [{ paragraph: { children: ["John Doe"] } }],
          },
        },
      ],
    },
  ],
});

// 行内内容控件
await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                sdt: {
                  properties: {
                    alias: "FirstName",
                    tag: "first-name",
                  },
                  children: ["John"],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

SDT 支持多种控件类型，适用于表单、模板和文档自动化。

文档保护

使用设置限制文档编辑：

{
  "features": {
    "updateFields": true,
    "documentProtection": {
      "edit": "readOnly",
      "password": "123"
    }
  },
  "sections": [
    {
      "children": [{ "paragraph": { "children": ["受保护的文档内容。"] } }]
    }
  ]
}

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

await generateDocument({
  features: {
    updateFields: true,
    documentProtection: {
      edit: "readOnly",
      password: "123",
    },
  },
  sections: [
    {
      children: [{ paragraph: { children: ["受保护的文档内容。"] } }],
    },
  ],
});

保护类型："readOnly"、"comments"、"trackedChanges"、"forms"。

提供 password 时，会自动计算带随机盐值和 100,000 次迭代的 SHA-512 哈希。也可以直接提供预计算的哈希值。

选项	类型	说明
`edit`	`string`	保护类型
`password`	`string`	明文密码（自动计算哈希）
`algorithmName`	`string`	哈希算法（如 `"SHA-512"`）
`hashValue`	`string`	Base64 编码的密码哈希
`saltValue`	`string`	Base64 编码的盐值
`spinCount`	`number`	哈希迭代次数
`formatting`	`boolean`	限制格式化
`hash`	`string`	旧版密码哈希 (w:hash)
`salt`	`string`	旧版密码盐值 (w:salt)
`cryptoAlgorithmClass`	`string`	加密算法类别
`cryptoAlgorithmSid`	`number`	加密算法 SID
`cryptoAlgorithmType`	`string`	加密算法类型
`cryptoProvider`	`string`	加密提供程序
`cryptoProviderType`	`string`	加密提供程序类型
`cryptoProviderTypeExtension`	`number`	提供程序类型扩展
`cryptoProviderTypeExtensionSource`	`string`	提供程序类型扩展源
`algorithmExtensionId`	`number`	算法扩展 ID
`algorithmExtensionSource`	`string`	算法扩展源
`cryptoSpinCount`	`number`	旧版加密迭代次数

修订跟踪选项

使用 insertion 和 deletion 时的选项：

选项	类型	说明
`id`	`number`	修订 ID
`author`	`string`	修订作者名称
`date`	`string`	ISO 8601 时间戳

两者也接受所有 TextRun 属性（text、bold、italic、color 等）。

编辑此页面或提交问题报告

引用

目录、脚注、尾注和参考文献

文档属性

设置核心、扩展（app）和自定义文档属性