# @betteroffice/docx 中文文档 规范地址：https://npmcn.com/package/%40betteroffice/docx/ 版本：0\.5\.1 npm 元数据更新时间：2026-10-27T11:31:18.280Z 中文译文更新时间：2026-11-08T00:23:10.339Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40betteroffice/docx 原文对照：https://npmcn.com/package/%40betteroffice/docx/?lang=original 项目主页：https://betteroffice.dev/ 源码仓库：https://github.com/openooxml/betteroffice ## 关键信息（来自 npm 元数据） - 包体积（解压后）：37.4 MB，143 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：@betteroffice/fonts ^0 - 首次发布：2026-07-18T17:07:56.451Z - 最新版本发布：2026-10-27T11:31:17.122Z - 近 30 天下载量：358852（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：14（近 12 个月 14 个） ## 中文简介 文字-忠实DOCX编辑和取景器核心:完整OOXML忠心,实时人类+AI代理协作. 无框架(Rust/Wasm). ## 安装 ```sh npm install @betteroffice/docx ``` 也可以使用：`pnpm add @betteroffice/docx`、`yarn add @betteroffice/docx`、`bun add @betteroffice/docx` ## README # @ betteroffice/ docx (英语) 无框架 DOCX 解析、序列化、 CRDT 编辑、布局和画布渲染 Rust/Web Assembly. (原始内容存档于2018-09-29). 用于文档处理或自定义编辑器适配器. ## 安装 ```bash bun add @betteroffice/docx ``` `@betteroffice/fonts` 是字体资产的可选对等依赖. ## 使用量 解析一个 DOCX 并保存它,同时保存未受影响的软件包部件 : ```ts import { readFile, writeFile } from 'node:fs/promises'; import { parseDocx, repackDocx } from '@betteroffice/docx'; const document = await parseDocx(await readFile('input.docx')); // document.package.document.content: the body's paragraphs and tables // document.package also holds styles, numbering, theme, media, headers and footers const bytes = await repackDocx(document); await writeFile('output.docx', new Uint8Array(bytes)); ``` ## 入境点 | 进入点 | 说明 | | --- | --- | | `parseDocx` | 读取 `ArrayBuffer`, (中文(简体) ), `Uint8Array`, (中文(简体) ), `Blob`,或 `File` 输入文档模式. | | `repackDocx`, (中文(简体) ), `repackDocxWithWarnings` | 将一个解析过的模型保存在原软件包上;后者也返回保存警告. | | `createDocx` | 写入新的文档模型,而不包含原始的软件包. | | `createYrsSession` (从) `@betteroffice/docx/yrs`(中文(简体) ) | 同步创建 CRDT 编辑会话 . | | `saveYrsDocx` (从) `@betteroffice/docx/yrs`(中文(简体) ) | 保存 DOCX 字节打开的会话, 返回字节并坚持段落锚地 . | 用于反应编辑器和查看器 [`@betteroffice/docx-react`](https://www.npmjs.com/package/@betteroffice/docx-react)。 。 。 . ## 运行时间和资产 包装容器、解析器、布局和编辑WebAssembly资产 `dist/generated/`。 。 。 . Async 切入点加载所需的资产; 解析或解析不需要手动初始化 创建会话。 为浏览器捆绑时保存被包装的资产 URL . 核心会话在同步创建后暴露出同步编辑和阅读方法. 反应 编辑器默认在Web Worker中运行其引擎,并曝光承诺返回文档读取, 编辑和导出。 发布直接会话与 `session.destroy()` 当完成. ## 撤销分组 故事是一出文字流:正文:正文,正文或页脚,脚注,或注释. `session.setUndoCaptureMode(mode)` 选择本地交易组合为撤消步骤; `session.undoCaptureMode()` 读取模式。 打电话 `session.beginUndoCapture()` 导入或播种后. | 模式 | 分组 | | --- | --- | | `auto` (默认) | 相近编辑会合;切换故事会关闭组. | | `manual` | 编辑到一个明确的边界,包括跨故事. | `session.addUndoBoundary()` 关闭当前组。 更改模式同时关闭它 历史; 设置相同的模式。 在手动模式下,在不相关的编辑之前关闭组. 远程交易停留在本地撤消历史之外; 编辑批次提供原子执行 . ## 选择状态 `session.selectionContext(range)` 通过段落选择格式化的汇总. 切换格式为 `true`, (中文(简体) ), `false`,或 `'mixed'`; 数值格式化为 `null` 缺席时或 不统一。 使用此状态来驱动自定义格式化控制 . ## 主办提案 `session.proposeChanges({ expectVersion, proposals })` 应用经过版本检查的跟踪回合 按主机提议编号分组的更改, 取消历史 。 每项提案均列明其 `id`目标 `paragraph`,一个 `op` (单位:千美元)`replaceText` 或者说 `insertText`和 `suggest: { author, date }` 用于归属. 拒绝则使回合无效. `session.setProposalStates({ expectVersion, expectPreviewVersion, changes })` 如何改变提案 预览时不修改文档或取消历史. `session.withdrawProposals({ expectVersion, ids })` 将已接受的提案作为纯文本予以解决,并删除被否决或未作出决定的提案,因此稍后 回合搜索预览显示的文本. 以 `session.getProposals()` 或用它观察 `session.onProposalChange()`。 。 。 . 打开另一份文件即可清除登记册。 使用 `proposalRevisionPreview(snapshot)` 从 `@betteroffice/docx/yrs` 作为布局使环境 `revisionPreview` 以显示决定. ## 注释范围 `session.setCommentRanges(commentId, ranges)` 替换当前注释的粘性锚地,同时 保存其元数据。 范围可能跨越段落或涉及单独的故事;每个故事必须是 非空地、命令和在现有段落之内。 更改注释前无效的输入抛出 . Reanchoring 加入本地的反捕捉. `saveYrsDocx(session)` 写入当前区域; 主机 删除所有被评论的文本必须选择存活区域或删除注释. ## 编辑批次 随会话版本读取目标,然后在解剖学上针对该版本应用所有步骤. 见 [版本检查过的 DOCX 批次](https://docs.betteroffice.dev/docs/javascript#edit-docx-in-version-checked-batches) 用于操作、抵销、限制和打出拒绝. ## 段落锁定 会话段落键确定协作会话中的段落; 持续锚点确定 按包件部分和OOXML段落ID保存段落。 见 [DOCX 段落锁定](https://docs.betteroffice.dev/docs/javascript#docx-paragraph-anchors) 用于保存、重新打开、解析和分配身份证. ## 有结构的出口 对于 `exportDocxStructured` 财务报告和审定财务报表 `exportDocxMarkdown`,参见 [结构化内容](https://docs.betteroffice.dev/docs/javascript#export-docx-as-structured-content) 用于锁定 JSON 或 Markdown , 修改视图, 故事选择和现场会话导出 . 对于 `exportDocxStructuredWithPages`,参见 [页面碎片](https://docs.betteroffice.dev/docs/javascript#page-fragments) 用于字体要求, 布局图,和页几何. 折旧: `collectHeadings` 从 `@betteroffice/docx/utils`; 使用 `session.headings(story)` 换句话说. ## 内容控制 `listDocxContentControls` 财务报告和审定财务报表 `findDocxContentControls` 检查 DOCX 字节中的控制 . 见 [内容控制](https://docs.betteroffice.dev/docs/javascript#fill-docx-content-controls) 用于会话发现、版本检查填充以及支持的控制类型. ## 比较文档 `compareDocx` 比较两个 DOCX 文件并返回跟踪文本更改或诊断. 见 [DOCX 比较](https://docs.betteroffice.dev/docs/javascript#compare-docx-files-into-tracked-changes) 用于支持输入、归属和拒绝行为. ## 协作 `CollaborationProvider` 从 `@betteroffice/docx/collaboration` 将复制件连接到二进制 运输。 见 [协作指南](https://docs.betteroffice.dev/docs/collaboration) 用于共享国家,运输线路,检查站和部署. ## 编辑器插件 对反应主机扩展名,请使用 [DOCX 插件 API](https://docs.betteroffice.dev/docs/javascript#host-docx-editor-plugins)。 。 。 . 折旧: `EditorPluginCore`, (中文(简体) ), `PluginPanelProps`, (中文(简体) ), `PanelConfig`,以及 `SidebarItemContext` 从 `@betteroffice/docx/plugin-api`; 使用 `defineDocxPlugin` 财务报告和审定财务报表 `plugins` 从 `@betteroffice/docx-react`。 。 。 . ## 自定义适配器的字体 见 [字体设置](https://docs.betteroffice.dev/docs/packages#fonts) 可选计量资产. 对于浏览器字体加载, `createFontLoadScope()` 从 `@betteroffice/docx/utils` 分别隔离 编辑器的负载通知 . `registerDocumentFaces(faces, scope)` 嵌入式相片和 当文档在同一姓氏下使用不同的字节时,返回他们的 CSS 家庭别名. 打开范围 `scope.dispose()` 当编辑器被删除的时候. ## 文档 - [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-react) - [Npm 上的语言字符串](https://www.npmjs.com/package/@betteroffice/docx-i18n) - [仓库](https://github.com/openooxml/betteroffice) ## 常见问题 ### @betteroffice/docx 是什么？ 文字-忠实DOCX编辑和取景器核心:完整OOXML忠心,实时人类\+AI代理协作\. 无框架\(Rust/Wasm\)\. ### 如何安装 @betteroffice/docx？ 在项目目录运行 npm install @betteroffice/docx，或使用 pnpm add / yarn add / bun add。 ### @betteroffice/docx 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @betteroffice/docx 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @betteroffice/docx 可以商用吗？ @betteroffice/docx 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @betteroffice/docx 的下载量有多少？ 根据 npm 官方下载统计，@betteroffice/docx 在 2026/10/08 – 2026/11/06 这 30 天内被下载 358,852 次，日均约 11,962 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @betteroffice/docx 还在维护吗？ 最新版本 0\.5\.1 发布于 2026/10/27（12 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/07/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。