# @docen/docx 中文文档

规范地址：https://npmcn.com/package/%40docen/docx/

版本：0\.7\.0
npm 元数据更新时间：2026-09-07T10:39:03.341Z
中文译文更新时间：2026-11-12T13:44:14.054Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40docen/docx
原文对照：https://npmcn.com/package/%40docen/docx/?lang=original
项目主页：https://github.com/DemoMacro/docen#readme
源码仓库：https://github.com/DemoMacro/docen

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

- 包体积（解压后）：354 kB，89 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2026-06-23T03:22:42.870Z
- 最新版本发布：2026-09-07T10:39:01.195Z
- 近 30 天下载量：17520（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 18 个）

## 中文简介

DOCX 编辑器和转换器由 @office-open/docx 提供电源,带有 Tiptap 编辑层——双向 DOCX 和 Markdown 转换, 样式为 HTML 粘贴输入

## 安装

```sh
npm install @docen/docx
```

也可以使用：`pnpm add @docen/docx`、`yarn add @docen/docx`、`bun add @docen/docx`

## README

# @ docen/ docx (英语)

![npm version](https://img.shields.io/npm/v/@docen/docx) ![npm downloads](https://img.shields.io/npm/dw/@docen/docx) ![npm license](https://img.shields.io/npm/l/@docen/docx)

> DOCX 编辑器和转换器由 @office-open/docx 用 Tiptap 编辑层供电,支持 DOCX 和 Markdown 之间的双向转换(HTML 被接受为粘贴输入).

> 需要一个现成的视觉编辑? [`@docen/editor`](https://npmcn.com/package/%40docen/editor/README.md) 用统键将引擎包裹在一个流畅的 UI 主机中 `<docen-document>` 网页组件.

## 特征

-   📝 **无视图 Tiptap 引擎** – DOCX 编辑模式有 DOCX- 意识扩展;渲染属于主机(例如 @docen/editor的画布舞台)
-   🔄 **DOCX 往返旅行** — 近损 DOCX 编辑器通过 @ office- open/ docx 转换
-   📄 **标记下方支持** - Tittap JSON 马克下调
-   🎨 **DOCX 属性** 自定义 Tiptap 扩展带阴影、 边框、 缩进、 间隔、 浮动、 裁剪
-   🔗 **模板补丁** - 替换 `{{placeholders}}` 在带有 Tiptap- JSON 内容的 DOCX 模板中

## 安装

```bash
# Install with pnpm
$ pnpm add @docen/docx

# Install with npm
$ npm install @docen/docx
```

## 快速启动

```typescript
import { docxExtensions, parseDOCX, generateDOCX } from "@docen/docx";
import { Editor } from "@docen/docx/core";

// Viewless: the editor is the editing model — rendering belongs to the host.
const editor = new Editor({
  element: null,
  extensions: docxExtensions,
  content: await parseDOCX(buffer),
});

// Save back to DOCX
const output = await generateDOCX(editor.getJSON());
```

## API 密码

### 独立函数( 核心)

这些作品没有编辑器实例——用于无头/服务器/批量使用.

```typescript
import {
  parseDOCX,
  generateDOCX,
  generateDOCXSync,
  generateDOCXStream,
  parseMarkdown,
  generateMarkdown,
} from "@docen/docx";

// DOCX pipeline: DOCX binary ↔ Tiptap JSON
const json = parseDOCX(buffer); // → JSONContent
const buffer = await generateDOCX(json); // → Buffer (pre-fetches http images by default)
const blob = await generateDOCX(json, { packer: { type: "blob" } }); // → Blob
const sync = generateDOCXSync(json); // → Buffer (skips prepare)
const stream = await generateDOCXStream(json); // → ReadableStream<Uint8Array>

// Markdown pipeline: Markdown string ↔ Tiptap JSON
const json = parseMarkdown("# Hello"); // → JSONContent
const md = generateMarkdown(json); // → string
```

### 编辑器

```typescript
import { createDocxEditor, docxExtensions } from "@docen/docx";

const editor = createDocxEditor({
  element: document.querySelector("#editor"),
  extensions: docxExtensions,
  spellcheck: true,
  editable: true,
});
```

需要一个现成的编辑器UI? [`@docen/editor`](https://npmcn.com/package/%40docen/editor/README.md)是因为 `<docen-document>` 将这个引擎与打开/保存,帆布渲染,和流畅的主机捆绑.

### 模板补丁

替换 `{{placeholders}}` 在带有Tiptap-JSON内容的DOCX模板中。 每个 补丁 `content` 编写(默认:获取 http 图像),然后编译为 DOCX.

```typescript
import { patchDOCX, parseMarkdown } from "@docen/docx";

const result = await patchDOCX({
  template: templateBuffer,
  patches: {
    title: { content: parseMarkdown("# Report") },
  },
  outputType: "nodebuffer",
});
```

### 高级:模型桥

`generateDOCX` 运行 `prepareDocument → compileDocument → generateDocument` 内部。 你很少直接需要这些 工作时才联系他们 中间 `DocumentOptions` (OOXML持久性模型):

```typescript
import { resolveDocument, compileDocument, prepareDocument } from "@docen/docx";

const json = resolveDocument(docOpts); // DocumentOptions → JSONContent
const docOpts = compileDocument(json); // JSONContent → DocumentOptions
await prepareDocument(json); // in place: http image URLs → data URLs
```

## 建筑

```
Standalone Functions (core)
  parseDOCX / generateDOCX / generateDOCXSync / generateDOCXStream / patchDOCX
  parseMarkdown / generateMarkdown
  resolveDocument / compileDocument / prepareDocument  (model bridge, advanced)
        ↕ used by
createDocxEditor / docxExtensions — the viewless Tiptap editing model
        ↕ rendered by
@docen/editor's canvas stage (LeaferJS pages, caret/selection mapping)
```

-   **运行时间模型**: Tiptap JSON 通过自定义扩展具有丰富的 DOCX 属性
-   **持久性模式**:文档选项(完整的OOXML表达式)
-   **独立职能是核心** ——编辑器装订为薄薄的包装

## 许可证

-   [麻省理工学院](https://npmcn.com/package/LICENSE) © [演示宏](https://www.demomacro.com/)

## 常见问题

### @docen/docx 是什么？

DOCX 编辑器和转换器由 @office-open/docx 提供电源,带有 Tiptap 编辑层——双向 DOCX 和 Markdown 转换, 样式为 HTML 粘贴输入

### 如何安装 @docen/docx？

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

### @docen/docx 支持 TypeScript 吗？

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

### @docen/docx 支持 ESM 还是 CommonJS？

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

### @docen/docx 可以商用吗？

@docen/docx 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @docen/docx 的下载量有多少？

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

### @docen/docx 还在维护吗？

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