# @betteroffice/docx-react 中文文档

规范地址：https://npmcn.com/package/%40betteroffice/docx-react/

版本：0\.5\.1
npm 元数据更新时间：2026-10-27T11:28:34.802Z
中文译文更新时间：2026-11-08T00:25:12.880Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.3 MB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-07-18T17:08:01.077Z
- 最新版本发布：2026-10-27T11:28:34.347Z
- 近 30 天下载量：84747（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

Word-fusional React DOCX编辑和取景器:全OOXML忠心,实时人类+AI代理合作.

## 安装

```sh
npm install @betteroffice/docx-react
```

也可以使用：`pnpm add @betteroffice/docx-react`、`yarn add @betteroffice/docx-react`、`bun add @betteroffice/docx-react`

## README

# @ betteroffice/ docx 反应

使用工具栏对 DOCX 编辑器和取景器进行反演,平面画布,评论,并跟踪更改. 引擎默认在一个Web Worker中运行;文档读取,编辑,并输出回还承诺.

## 安装

```bash
bun add @betteroffice/docx-react react react-dom
```

同伴依赖性 : `react` 财务报告和审定财务报表 `react-dom` 18或19号.

## 使用量

```tsx
import { DocxEditor } from '@betteroffice/docx-react';
import '@betteroffice/docx-react/styles.css';

export function Editor({ file }: { file: File }) {
  return <DocxEditor documentBuffer={file} />;
}
```

在应用程序条目、页面或版式级别上导入样式表一次。 仅使用浏览器 组件与服务器渲染集成时。 见 [托管](https://docs.betteroffice.dev/docs/migrating-to-0-5#hosting) 用于工人,块和CSP需求.

## 关键选项

下面所有道具都是可选的. 关闭文档源以显示占位符 .

| 道具 | 类型 | 说明 |
| --- | --- | --- |
| `documentBuffer` | `ArrayBuffer | Uint8Array | Blob | File | null` | DOCX 源字节. |
| `file` | `ArrayBuffer | Uint8Array | Blob | File | null` | 别名 `documentBuffer`,在两者都设定时获胜. |
| `fileName` | `string` | 别名 `documentName`,在两者都设定时获胜. |
| `document` | `Document | null` | 解析模型从 `@betteroffice/docx`,作为替代来源. |
| `mode` | `'editing' | 'suggesting' | 'viewing'` | 直接编辑、跟踪更改或查看;默认为 `'editing'`。 。 。 . |
| `readOnly` | `boolean` | 禁用编辑并隐藏默认工具栏和标尺 . |
| `author` | `string` | 评论和跟踪更改的作者. |
| `onSave` | `(buffer: ArrayBuffer) => void` | 接收导出 DOCX 字节 . |
| `onSaveRequest` | `() => boolean | void | Promise<boolean | void>` | 拥有UI在串行化前所保存的工作流程. |
| `downloadOnSave` | `boolean` | 同时下载 UI 保存; 默认为 `true`。 。 。 . |
| `onDocumentChange` | `(change: DocxDocumentChange) => void` | 在承诺更改后接收文档版本 . |
| `onError` | `(error: Error, info?: DocxErrorInfo) => void` | 接收出错; 可收回的报告包括 `recoverable: true`。 。 。 . |
| `collaboration` | `DocxEditorCollaborationOptions` | 配置共享复制品 . |
| `showToolbar` | `boolean` | 显示内置或提供的铬; 默认为 `true`。 。 。 . |
| `toolbar` | `ReactNode` | 替换工具栏; `null` 藏来. 实验成分API. |
| `showRuler` | `boolean` | 显示标尺; 默认值为 `false`。 。 。 . |
| `showZoomControl` | `boolean` | 显示缩放控件; 默认为 `true`。 。 。 . |
| `showHiddenText` | `boolean` | 在布局中包含隐藏文本; 默认为 `false`。 。 。 . |
| `previewFirstPage` | `boolean` | 实验性早期页面预览;默认关闭并配合忽略. |
| `onFirstPagePainted` | `() => void` | 在每份文件第一页作画时打过一次电话. |
| `pageMirror` | `'full' | 'text'` | 访问页面 DOM; 默认为 `'full'`。 。 。 . |
| `measurementFontProvider` | `BundledFontProvider` | 覆盖此编辑器的测量字体提供者 . |
| `i18n` | `Translations` | 语言覆盖从 `@betteroffice/docx-i18n`。 。 。 . |
| `plugins` | `readonly DocxPlugin[]` | 主机的扩展带有管理下的生命周期和权限. |
| `memoryBudget` | `DocxMemoryBudget` | 内存压力阈值和可选工人分配限额. |
| `onMemoryPressure` | `(pressure: DocxMemoryPressure) => void` | 接收内存压力级别变化 . |

折旧: `legacySyncApi` 保持同步 API , 并在 0. 6. 0 中删除; 省略它以使用默认的 aync 编辑器 .

`onChange` 得到一个完整的 `Document` 仅与 `legacySyncApi`。默认工人编辑器 拒绝, 显示文档替换错误, 并报告错误 `onError`启用 `onDocumentChange` 用于版本通知. `experimentalWorkerOpen={false}` 已贬值 工人编辑器是默认值.

## 编辑器参考

`DocxEditorRef` 暴露了async文档操作和编辑器的命令存储, `commands`。 。 。 . 等着 `save()` 导出 DOCX 字节,或 `flushPendingInput()` 在单独的主机操作之前 这必须包括已接受的打字和当前选择。 Flashing 等待活动 IME 如果输入失败,则将替换文档,或者编辑器卸载. 无法运行的已排队工作被拒用导出 `DocxCommandAdmissionError`,其 `code` 命名事业.

使用 `readPositionAtPoint(clientX, clientY)` 对于一个版本文本目标,位于 viewport 坐标. 使用 `scrollToParagraph(paraId)` 用于同步段落导航。 两者都支持默认工人 运行时间.

`getPositionAtPoint` 财务报告和审定财务报表 `scrollToParaId` 掷出 `DocxSyncApiError` 默认编辑器; 使用 `readPositionAtPoint` 财务报告和审定财务报表 `scrollToParagraph`。 。 。 .

## 主机保存

`onSaveRequest` 处理文件 > 在序列化前保存和 Cmd/Ctrl+S。 返回时 `true` 继续 内存; 返回 `false` 或者没有什么可以压制它。 Async 调用等待, 重叠 UI 请求共享一个工作流程, 错误到达 `onError`。 。 。 .

通话 `save()` 直接在不援引的情况下进行回调出口 `onSaveRequest` 再来一次. `onSave` 接收导出缓冲器; `downloadOnSave={false}` 禁用额外的UI下载.

## 装入和无障碍

`previewFirstPage` 绘制文档打开时仅显示的预览。 编辑和插件 激活等待完整的文档 . `onFirstPagePainted` 让一个主机放弃其装入 UI 当预览或完整文档页面首次出现时.

`pageMirror="text"` 保留可读文本、链接和DOM工作较少的表格。 在页面上省略 用于辅助技术和插件 DOM 区域查询的元素的文本位置.

`getTotalPages()` 返回当前(可能为临时)的页数。 等着 `whenLayoutComplete()` ;视图外的页面在显示时被构建.

## 主机搜索

`search(query, options?)` 显示正文匹配,包括表格,不移动 选择或焦点。 它返回一个承诺并在查看模式下工作; 匹配不区分大小写 除非 `caseSensitive` 已经设定。 空查询可以清除搜索.

`searchNext()` 财务报告和审定财务报表 `searchPrevious()` 通过匹配线包裹; `searchGoTo(index)` 选择匹配. 读取状态为 `getSearchState()`,订阅 `onSearchChange()`,并明确 `clearSearch()`。 。 。 .

## 主办提案

裁判 `proposeChanges()`, (中文(简体) ), `setProposalStates()`, (中文(简体) ), `withdrawProposals()`,以及 `getProposals()` 管理按主机建议ID分类的跟踪变化。 决定预览被接受的提案为简单 文本和隐藏被否决的文本; 撤回解决那些在历史之外的决定.

设定 `allowHostProposals` 允许只读或取景模式下的建议。 设定 `showHostProposalsInSidebar` 还有展示求婚卡 两者均默认失效; 提议访问无法输入、编辑批次、命令或插件.

## 工具栏和插件

利用试验成分API来安排内置控制或供应外置铬; 见 [编写 DOCX 工具栏](https://docs.betteroffice.dev/docs/javascript#compose-the-docx-toolbar)。 。 。 . 插件 API 也具有实验性. 用于主机面板、覆盖物、侧边栏项目、寿命周期和 获得授权的操作,参见 [主机 DOCX 编辑器插件](https://docs.betteroffice.dev/docs/javascript#host-docx-editor-plugins)。 。 。 .

## 编辑批次和段落锁定

裁判 `readParagraphs`, (中文(简体) ), `findText`, (中文(简体) ), `validateEdits`,以及 `applyEdits` 冲出未完成的输入 版本检查过的操作。 见 [DOCX 编辑批次](https://docs.betteroffice.dev/docs/javascript#edit-docx-in-version-checked-batches) 财务报告和审定财务报表 [段落锁定](https://docs.betteroffice.dev/docs/javascript#docx-paragraph-anchors) 目标、身份和拒绝.

## 结构化的出口和内容管制

对于 `exportStructuredWithPages(options)` 在默认工人编辑器中,参见 [页面碎片](https://docs.betteroffice.dev/docs/javascript#page-fragments) 供修订意见, 排版要求,和几何.

裁判 `listContentControls` 财务报告和审定财务报表 `findContentControls` 在检查版本前检查控制 填充;见 [内容控制](https://docs.betteroffice.dev/docs/javascript#fill-docx-content-controls)。 。 。 .

## 协作

这个 `collaboration` 道克将工人编辑器连接到一个共享的复制品上. 见 [协作指南](https://docs.betteroffice.dev/docs/collaboration) 对于复制的召回, 共享初始状态、交通线路和检查站.

## 字体和本地化

在挂起编辑器前配置可选的测量字体; 见 [字体设置](https://docs.betteroffice.dev/docs/packages#fonts)启用 `measurementFontProvider` 页:1 一个特定编辑提供者。 嵌入式字体面相隔开文档,当 编辑器卸载或装入另一个文档.

通过区域字符串 `i18n`; 字符串和翻译类型发布于 [`@betteroffice/docx-i18n`](https://www.npmjs.com/package/@betteroffice/docx-i18n)。 。 。 .

## 记忆和恢复

`getMemoryStats()` 报告主线和工人WebAssembly记忆. `onMemoryPressure` 报告 出入口; `memoryBudget` 默认警告为75%,关键值为4个GiB的90%. `memoryBudget.workerLimitBytes` 工人编辑-核心分配.

一个失败的工人可以被替换一次每个编辑器,重新打开源并重放编辑. 对于字节来源,恢复使用最后一个检查站,所以撤销历史可以追溯到那个检查站. 如果修复失败, `onError` 报告失败和编辑停止。 协作会报告 没有自动替换的工人故障.

## 文档

-   [Java脚本指南](https://docs.betteroffice.dev/docs/javascript)
-   [协作指南](https://docs.betteroffice.dev/docs/collaboration)
-   [软件包指南](https://docs.betteroffice.dev/docs/packages)
-   [Npm 的核心软件包](https://www.npmjs.com/package/@betteroffice/docx)
-   [Npm 上的语言字符串](https://www.npmjs.com/package/@betteroffice/docx-i18n)
-   [仓库](https://github.com/openooxml/betteroffice)

## 常见问题

### @betteroffice/docx-react 是什么？

Word-fusional React DOCX编辑和取景器:全OOXML忠心,实时人类\+AI代理合作\.

### 如何安装 @betteroffice/docx-react？

在项目目录运行 npm install @betteroffice/docx-react，或使用 pnpm add / yarn add / bun add。

### @betteroffice/docx-react 支持 TypeScript 吗？

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

### @betteroffice/docx-react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @betteroffice/docx-react 可以商用吗？

@betteroffice/docx-react 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @betteroffice/docx-react 的下载量有多少？

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

### @betteroffice/docx-react 还在维护吗？

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