# @docx-editor\.dev/editor-api 中文文档

规范地址：https://npmcn.com/package/%40docx-editor.dev/editor-api/

版本：2\.38\.0
npm 元数据更新时间：2026-11-16T13:48:40.129Z
中文译文更新时间：2026-11-16T13:50:43.615Z
软件包许可：LicenseRef-EigenPal-Pro-Evaluation-1\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40docx-editor.dev/editor-api
原文对照：https://npmcn.com/package/%40docx-editor.dev/editor-api/?lang=original
项目主页：https://docx-editor.dev/
源码仓库：https://github.com/eigenpal/docx-editor

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.16\.0 \|\| \>=22\.3\.0
- 运行依赖：0 个
- peer 依赖：@docx-editor\.dev/core ~2\.38\.0
- 首次发布：2026-08-05T15:01:44.895Z
- 最新版本发布：2026-11-16T13:48:38.450Z
- 近 30 天下载量：36900（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：68（近 12 个月 68 个）

## 中文简介

DOCX 文档自动化:从服务器或已经打开页面的编辑器驱动文档的批量对象模型

## 安装

```sh
npm install @docx-editor.dev/editor-api
```

也可以使用：`pnpm add @docx-editor.dev/editor-api`、`yarn add @docx-editor.dev/editor-api`、`bun add @docx-editor.dev/editor-api`

## README

[![DOCX Editor by EigenPal](https://raw.githubusercontent.com/eigenpal/docx-editor/main/.github/assets/readme-logo-light.svg)](https://www.docx-editor.dev/)

[![npm version](https://img.shields.io/npm/v/@docx-editor.dev/editor-api.svg?style=flat-square&color=3B5BDB)](https://www.npmjs.com/package/@docx-editor.dev/editor-api) [![npm downloads](https://img.shields.io/npm/dm/@docx-editor.dev/editor-api.svg?style=flat-square&color=3B5BDB)](https://www.npmjs.com/package/@docx-editor.dev/editor-api) [![EigenPal Pro License](https://img.shields.io/badge/license-EigenPal_Pro_License-blue.svg?style=flat-square&color=3B5BDB)](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/LICENSE.md) [![Demo](https://img.shields.io/badge/Live_Demo-3B5BDB?style=flat-square&logo=vercel&logoColor=white)](https://docx-editor.dev/editor) [![Documentation](https://img.shields.io/badge/Docs-3B5BDB?style=flat-square&logo=readthedocs&logoColor=white)](https://www.docx-editor.dev/docs)

# @docx-editor.dev/editor-api (英语)

通过 Office.js 对象模型中支持的子集来编辑 DOCX 文件. API包括段落,范围,评论和修订. 使用 `load()` 队列读取和 `sync()` 以解剖法应用每批.

在服务器上运行 API 覆盖 DOCX 字节,或在浏览器中针对打开的编辑器. 见 [Office.js 兼容性](https://www.docx-editor.dev/docs/2.x/editor-api/office-js-api) 关于受支助成员和与办事处的差别.

```bash
npm install @docx-editor.dev/editor-api @docx-editor.dev/core
```

服务器使用需要节点.js `^20.16.0 || >=22.3.0`。 。 。 .

## 按任务分列的指南

开始 [运行时间和设置](https://www.docx-editor.dev/docs/2.x/editor-api/runtime) 财务报告和审定财务报表 [夹击、装入和出错](https://www.docx-editor.dev/docs/2.x/editor-api/batching-and-errors)。 。 。 .

| 任务 | 指南 |
| --- | --- |
| 读取、插入、替换或删除文本 | [文字和范围](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-ranges) |
| 将段落拆分为 `insertText()` 财务报告和审定财务报表 `\n`,也作为跟踪变化 | [拆分段落](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-ranges#split-a-paragraph) |
| 查找匹配或使用书签 | [搜索和导航](https://www.docx-editor.dev/docs/2.x/editor-api/search-and-navigation) |
| 设置字体、段落属性、样式或链接 | [格式和样式](https://www.docx-editor.dev/docs/2.x/editor-api/formatting) |
| 创建和配置列表 | [清单和编号](https://www.docx-editor.dev/docs/2.x/editor-api/lists) |
| 工作表值、行、列和单元格 | [表格和单元格](https://www.docx-editor.dev/docs/2.x/editor-api/tables) |
| 插入并调整图像大小 | [内嵌图片](https://www.docx-editor.dev/docs/2.x/editor-api/pictures) |
| 插入字段, 写入其缓存结果, 或计算 PAGE 和 NUMPGES | [字段和页形](https://www.docx-editor.dev/docs/2.x/editor-api/fields) |
| 从 OOXML 插入等式 | [插入等式](https://www.docx-editor.dev/docs/2.x/editor-api/text-and-ranges#insert-an-equation) |
| 提出分块、字段或等式作为跟踪变化 | [跟踪更改](https://www.docx-editor.dev/docs/2.x/editor-api/revisions#propose-several-structural-edits-in-one-run) |
| 提出模型中的段落重写为最少的跟踪更改 | [提议重写AI](https://www.docx-editor.dev/docs/2.x/recipes/propose-rewrite),与 `prepareRewrite` 从 `@docx-editor.dev/editor-api/agent` |
| 设置页面几何和编辑页眉、页脚或注释 | [页面布局和故事](https://www.docx-editor.dev/docs/2.x/editor-api/page-layout-and-stories) |
| 填充模板控制并编辑其元数据 | [内容控制](https://www.docx-editor.dev/docs/2.x/editor-api/content-controls) |
| 讨论内容和管理线索 | [评论](https://www.docx-editor.dev/docs/2.x/editor-api/comments) |
| 创建、检查、接受或拒绝跟踪更改 | [跟踪更改](https://www.docx-editor.dev/docs/2.x/editor-api/revisions) |
| 查找任何公共对象、方法、属性或支持类型 | [API 成员目录](https://www.docx-editor.dev/docs/2.x/editor-api/reference) |

## 在服务器上

根项打开 DOCX 字节,编辑文档,并返回所保存的字节.

```ts
import { readFile, writeFile } from 'node:fs/promises';
import { DocxEditor } from '@docx-editor.dev/editor-api';

const runtime = await DocxEditor.createServer(await readFile('contract.docx'), {
  author: 'Review bot',
});
try {
  const filled = await runtime.run(async (context) => {
    const matches = context.document.body.search('{{cap}}', { matchCase: true });
    matches.load('items');
    await context.sync(); // Read the matching ranges.

    for (const match of matches.items) match.insertText('$500k', 'Replace');
    await context.sync(); // Commit all writes in one atomic batch.
    return matches.items.length;
  });
  console.log(`replaced ${filled}`);
  await writeFile('contract.filled.docx', await runtime.save());
} finally {
  runtime.dispose();
}
```

`createServer` 在解析前解析文档,而不保留输入缓冲。 然后可以重新使用或转移缓冲器。 每个 `save()` 返回独立的 `Uint8Array`。将保存的字节装入活编辑器,以显示服务器编辑.

## 在服务器上创建跟踪更改

开始于 [Office.js 开发者指南](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/OFFICE_JS_GUIDE.md) 用于完整的服务器实例和分批公约.

设定 `document.changeTrackingMode = 'TrackMineOnly'`,然后使用标准 Office.js 编辑方法。 供应代理商 `author` 打开服务器或合作运行时间时:

```ts
await runtime.run(async (context) => {
  const matches = context.document.body.search('within 7 days');
  matches.load('items');
  await context.sync();
  if (matches.items.length !== 1) throw new Error('Choose a unique target');

  context.document.changeTrackingMode = 'TrackMineOnly';
  const replacement = matches.items[0]!.insertText('within 30 days', 'Replace');
  await context.sync();
  replacement.load('text');
  await context.sync();
});
```

使用 `range.insertText(text, 'Before' | 'After')` 用于插入,以及 `range.delete()` 或者说 `range.clear()` 用于删除. `insertText()` 返回插入范围。 模式任务和编辑 `sync()`; 失败的批次保留了上一个模式和文档。 装入 `document.changeTrackingMode` 在读之前. `Off` 是初始模式.

这是一个支持的 Office.js 子集 . `TrackMineOnly` 应用到此服务器主机并坚持到整个服务器主机 `run()` 打电话 它不会改变同行的跟踪设置,也不会保存全文件的跟踪策略. `TrackAll` 失败 `NotSupported`. 浏览器跟踪的写作需要Pro审查模块;运行时间设置不会改变编辑器UI模式. 被跟踪的文本编辑支持一个段落,包括表格单元格文本,以及相邻的兄妹段落外部协作. 跟踪 `Paragraph.delete()` 财务报告和审定财务报表 `Range.delete()` 整个段落的记录删除了案文并删除了段落标记,这也是在合作中。 字体、段落格式、段落样式和 `readingOrder` 更改记录属性修改,插入段落的记录插入文字和段落标记。 被跟踪的编辑可以进入另一个作者待处理的文本插入或删除的内部或相邻处,每个作者的修改保留单独的决定. 运行时间会拒绝触摸自己待修改的编辑,另一个作者的段落标记,格式化,移动,或结构变化,并在行内有待插入或删除的文本. 跟踪段落分割通过 `insertText()` 与 `\n`字段通过 `insertField()` 取得结果 `Field.result`,一次一个方程 `insertOoxml()` 制作本土修改。 其他结构变化在跟踪时拒绝. 完整名单见 [订正](https://docx-editor.dev/docs/2.x/editor-api/revisions)15\. 评论和修订决定仍然有效。 设定 `Off` 明确用于永久编辑.

见 [服务器代理审查示例](https://npmcn.com/package/examples/server-agent-review/README.md) 为霍库斯波克斯, stale-read 处理,和审查生命周期.

## 在浏览器中

将打开的核心、 React 或 Vue 编辑器传递到 `createBrowser()`。编辑使用编辑器的撤消历史。 通过自有编辑器保存.

```ts
import { DocxEditor } from '@docx-editor.dev/editor-api/browser';

const runtime = DocxEditor.createBrowser(editor, { author: 'Demo Reviewer' });
try {
  await runtime.run(async (context) => {
    const heading = context.document.body.paragraphs.getFirstOrNullObject();
    heading.load('text');
    await context.sync();

    if (!heading.isNullObject) heading.font.bold = true;
    await context.sync();
  });
} finally {
  runtime.dispose();
}
```

使用 `/browser` 打开编辑器的条目。 使用服务器上的根条目将浏览器渲染代码从捆绑中排除出.

供应 `author` 供评论、答复和跟踪编辑。 浏览器评论也要求Pro审查模块和一个可编辑的文件. 处理错误 `code`。见 [评论](https://www.docx-editor.dev/docs/2.x/editor-api/comments) 财务报告和审定财务报表 [跟踪更改](https://www.docx-editor.dev/docs/2.x/editor-api/revisions) 用于支助行动.

## 方案拟订模式

-   在读取属性前装入属性 。 装入收藏 `items` 在项目属性之前.
-   批次独立写作方式 `sync()`。失败的批次没有应用写;早期的成功同步仍然被承诺 .
-   在使用返回对象之前插入后同步 .
-   内置代理 `runtime.run()`,或明确跟踪和采用它们.
-   编辑段落后再次搜索 。 现有幅度保留原有的抵销额.
-   检查 `isNullObject` 在使用无对象存取器时同步.
-   在使用前检查无效字体值和审查日期 .

见 [夹击、装入和出错](https://www.docx-editor.dev/docs/2.x/editor-api/batching-and-errors) 用于交易限制、代理寿命和错误恢复.

## Office.js 兼容性

API 执行 Office.js 对象模型的一个已记录子集。 它运行时没有Office.js主机,不需要Office.js包. 见 [Office.js 兼容性](https://www.docx-editor.dev/docs/2.x/editor-api/office-js-api) 用于支持操作、运行时间差异和兼容性报告.

服务器页面域更新需要配置有字体资源的测量器. 见 [字段和页形](https://www.docx-editor.dev/docs/2.x/editor-api/fields) 和可运行的报告代理.

要从前审查者, Bridge, MCP, 或聊天API 升级, 请参见 [移徙](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/MIGRATION.md)。 。 。 .

## 软件包

| 软件包 | 说明 |
| --- | --- |
| [`@docx-editor.dev/react`](https://www.npmjs.com/package/@docx-editor.dev/react) | 反应适配器. `<DocxEditor>`提供原始物 钩子和复合铬. |
| [`@docx-editor.dev/core`](https://www.npmjs.com/package/@docx-editor.dev/core) | 框架-可知性引擎:OOXML读取/写出,犬形文档树,布局,颜料. |
| [`@docx-editor.dev/i18n`](https://www.npmjs.com/package/@docx-editor.dev/i18n) | 共享区域字符串和类型 . |
| [`@docx-editor.dev/pro`](https://www.npmjs.com/package/@docx-editor.dev/pro) | 跟踪更改、注释和自定义节点. |
| [`@docx-editor.dev/editor-api`](https://www.npmjs.com/package/@docx-editor.dev/editor-api) | 支持 Office.js 子集用于在服务器或打开编辑器中编辑文档 . |

## 哪些 API 任务

使用 React 或 Vue 适配器钩, 复检钩,以及 `DocxEditorReview` 从 `@docx-editor.dev/pro/react` 或者说 `@docx-editor.dev/pro/vue` 用于构建浏览器审查控制。 使用编辑 API 在 `@docx-editor.dev/editor-api` 用于文档自动化。 它遵循Office.js对象模型,在浏览器和服务器主机中运行.

| 任务 | 浏览器控制( React 或 Vue) | 文件自动化 |
| --- | --- | --- |
| [对已找到文本的评论](https://www.docx-editor.dev/docs/2.x/recipes/comment-on-found-text) | `editor.findMatches`, (中文(简体) ), `editor.selectMatch`,则 `useReview().comment` | `body.search`,则 `Range.insertComment` |
| [对线索的答复](https://www.docx-editor.dev/docs/2.x/pro/comments) | `useReview().reply(item, text)` | `Comment.reply(text)` |
| [记录跟踪替换](https://www.docx-editor.dev/docs/2.x/recipes/tracked-replacement) | 那么建议模式 `editor.exec({ type: 'replaceMatch', match, text })` | `document.changeTrackingMode = 'TrackMineOnly'`,则 `Range.insertText(text, 'Replace')` |
| [提议将AI重写为已跟踪的更改](https://www.docx-editor.dev/docs/2.x/recipes/propose-rewrite) | `prepareRewrite` 结束 `DocxEditor.createBrowser` | `prepareRewrite` 从 `@docx-editor.dev/editor-api/agent` |
| [接受或拒绝更改](https://www.docx-editor.dev/docs/2.x/recipes/accept-reject-without-scrolling) | `useReview().accept(item)` 或者说 `useReview().reject(item)` | `Revision.accept()` 或者说 `Revision.reject()` |
| [不滚动打开更改](https://www.docx-editor.dev/docs/2.x/recipes/accept-reject-without-scrolling) | `useReview().setActive(key, { reveal: false })` | 不适用:无取景口 |
| [突出显示区域](https://www.docx-editor.dev/docs/2.x/recipes/highlight-ranges) | `useHighlights(name, source, options)` | 不适用 |
| [自定义审查铁路卡](https://www.docx-editor.dev/docs/2.x/recipes/custom-review-cards) | `DocxEditorReview` 与 `preset` 设置为 `false`, (中文(简体) ), `useReviewCardHeights`, (中文(简体) ), `useStackedReviewPositions`,以及 `useReviewRailMetrics` | 不适用 |
| 关于选择的注释按钮 | `DocxEditorReview.AddComment` 作为直系儿童 `DocxEditorReview`,或 `useEditorCommand('review.addComment')` | 不适用 |
| [页面设置和段落对话框](https://www.docx-editor.dev/docs/2.x/customization/dialogs) | `DocxEditor.PageSetupDialog` 或者说 `DocxEditor.ParagraphDialog` | `Section.pageSetup`,以及 `Paragraph` 属性,例如 `alignment` |

这个包装了任务秘方 [`docs/index.md`](https://npmcn.com/package/%40docx-editor.dev/editor-api/docs/index.md).这些网站还有: [任务配方](https://www.docx-editor.dev/docs/2.x/recipes)。 。 。 .

## 许可证

此软件包使用 [EigenPal Pro 许可证](https://github.com/eigenpal/docx-editor/blob/main/packages/editor-api/LICENSE.md)。见 [定价](https://www.docx-editor.dev/pricing) 许可证和支持选项.

## 捐款

欢迎捐款。 见 [捐款额](https://github.com/eigenpal/docx-editor/blob/main/CONTRIBUTING.md) 用于设置,测试,以及一次性CLA签名.

## 商业支助

> \[!TIP\]问题或定制特征? 电子邮件 **[docx-编辑器@eigenpal.com](mailto:docx-editor@eigenpal.com)**。 。 。 .

## 常见问题

### @docx-editor\.dev/editor-api 是什么？

DOCX 文档自动化:从服务器或已经打开页面的编辑器驱动文档的批量对象模型

### 如何安装 @docx-editor\.dev/editor-api？

在项目目录运行 npm install @docx-editor\.dev/editor-api，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@docx-editor\.dev/core（~2\.38\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @docx-editor\.dev/editor-api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @docx-editor\.dev/editor-api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @docx-editor\.dev/editor-api 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.16\.0 \|\| \>=22\.3\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @docx-editor\.dev/editor-api 可以商用吗？

@docx-editor\.dev/editor-api 使用 LicenseRef-EigenPal-Pro-Evaluation-1\.0 许可。声明的许可为 LicenseRef-EigenPal-Pro-Evaluation-1\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @docx-editor\.dev/editor-api 的下载量有多少？

根据 npm 官方下载统计，@docx-editor\.dev/editor-api 在 2026/10/13 – 2026/11/11 这 30 天内被下载 36,900 次，日均约 1,230 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @docx-editor\.dev/editor-api 还在维护吗？

最新版本 2\.38\.0 发布于 2026/11/16（今天）；至今共发布 68 个版本，其中过去 12 个月发布了 68 个；首次发布于 2026/08/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

