# @docen/import-docx 中文文档

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

版本：0\.2\.9
npm 元数据更新时间：2026-06-23T04:18:05.763Z
中文译文更新时间：2026-11-12T13:45:01.001Z
软件包许可：MIT

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

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

弃用说明：Deprecated: merged into @docen/docx — use @docen/docx for DOCX parse/generate\.

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

- 包体积（解压后）：318 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：@napi-rs/canvas ^0\.1\.88
- 首次发布：2026-01-11T10:51:23.296Z
- 最新版本发布：2026-04-27T12:30:53.163Z
- 近 30 天下载量：7887（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

一个强大的 TipTap/ProseMirror 扩展来导入 Microsoft Word DOCX 文件到编辑内容

## 安装

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

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

## README

# @ docen/ 导入- docx

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

> 将 Microsoft Word DOCX 文件导入 TipTap/ProseMirror 内容.

## 特征

-   📝 **丰富的文本解析** - 准确分析标题、段落和有格式的区块
-   🖼️ **图像提取** - 自动提取图像,提供基数64转换和裁剪支持
-   📊 **表格支持** - 带有colspan/rowspan检测算法的完整表格结构
-   ✅ **列表任务( T)** - 项目符号列表、带有起始数字提取的编号列表和带有复选框检测的任务列表
-   🎨 **文本格式** - 粗体、斜体、下划线、下划线、上划线和亮点
-   🎯 **文本样式** - 综合样式支持,包括颜色、背景、字体、大小和行高
-   🔗 **链接** - 超链接提取与红外线保护
-   💻 **代码块** - 带有语言属性提取的代码块检测
-   🌐 **横线** - 在浏览器和节点环境中工作
-   ✂️ **图像裁剪** - 作物元数据保存,可选择实物作物
-   🧠 **智能分析** - DOCX XML 分析适当的元素分组和结构重建
-   ⚡ **快速处理** - 用于超快ZIP减压

## 安装

```bash
# Install with npm
$ npm install @docen/import-docx

# Install with yarn
$ yarn add @docen/import-docx

# Install with pnpm
$ pnpm add @docen/import-docx
```

## 快速启动

```typescript
import { parseDOCX } from "@docen/import-docx";
import { readFileSync } from "node:fs";

// Read DOCX file
const buffer = readFileSync("document.docx");

// Parse DOCX to TipTap JSON
const content = await parseDOCX(buffer);

// Use in TipTap editor
editor.commands.setContent(content);
```

## API 参考

### `parseDOCX(input, options?)`

分析 DOCX 文件并将其转换为TipTap/ProseMiror JSON内容.

**参数:**

-   `input: Buffer | ArrayBuffer | Uint8Array` - DOCX文件数据
-   `options?: DocxImportOptions` - 可选导入配置

**回返情况:** `Promise<JSONContent>` - TipTap/ProseMiror 文档内容,并嵌入图像

**选项 :**

```typescript
interface DocxImportOptions {
  image?: {
    /** Custom image handler (default: embed as base64) */
    handler?: (info: DocxImageInfo) => Promise<DocxImageResult>;

    /**
     * Dynamic import function for @napi-rs/canvas
     * Required for image cropping in Node.js environment, ignored in browser
     */
    canvasImport?: () => Promise<typeof import("@napi-rs/canvas")>;

    /**
     * Enable or disable physical image cropping during import
     * When true, images with crop information in DOCX will be physically cropped
     * When false (default), crop metadata is preserved but full image is used
     *
     * @default false
     */
    crop?: boolean;
  };

  paragraph?: {
    /** Whether to ignore empty paragraphs (default: false) */
    ignoreEmpty?: boolean;
  };
}
```

**默认图像转换器 :**

软件包导出 `defaultImageConverter` 将图像嵌入为基础64数据 URL:

```typescript
import { parseDOCX, defaultImageConverter } from "@docen/import-docx";

await parseDOCX(buffer, {
  image: {
    handler: async (info) => {
      if (shouldUploadToCDN) {
        return { src: await uploadToCDN(info.data) };
      }
      return defaultImageConverter(info);
    },
  },
});
```

## 支持的内容类型

### 文本格式

-   **粗体**, (中文(简体) ), _斜体_, (中文(简体) ), 下划线, (中文(简体) ), ~切换~
-   ưμ㼯A ~下标~
-   文字概要
-   文本颜色和背景颜色
-   字体家庭和大小
-   线高

### 块元素

-   **标题** (H1-H6) 适当水平检测
-   **段 次 页 次** 文本对齐(左、右、中、正则)
-   **块名** (由缩进+左边框格式检测出)
-   **水平规则** (检测为DOCX中的分页符)
-   **代码块** 有语言属性支持

### 名单

-   **符号列表** 有适当的巢穴和结构
-   **编号列表** 带有自定义起始数提取
-   **任务列表** 已检查/未检查的状态检测(qq/qq符号)

### 表格

-   完整表格结构解析
-   **表格单元格** 使用网格算法进行 colspan 检测
-   **表格单元格** 使用 vMerge 跟踪进行行宽检测
-   单元格对齐和格式化保存
-   合并的单元格处理(横向和纵向)

### 媒体嵌入( E)

-   **图像** 自动转换基数64
-   **分组图像** (DOCX图像组)支持
-   **链接** (超链接),带有href提取

## 解析算法

### 文档结构

解析器遵循一个结构化的工作流程 :

1.  **提取关系** - 剖析 `_rels/document.xml.rels` 用于超链接和图像
2.  **解析编号** - 从 `numbering.xml` (缩略语 = numFmt)
3.  **进程文件正文** - 通过文档.xml 元素进行排列:
    -   检测内容类型(表格、列表、段落、代码块等)
    -   将连续元素组合入合适的容器
    -   将 XML 节点转换为 TipTap JSON 节点

### 表格处理

表格使用专门的算法:

-   **科尔斯潘检测** - 网格算法跟踪单元格位置并检测水平合并
-   **行宽检测** - 垂直合并(vMorge) 横行跟踪,并有适当的单元格跳过
-   **单元格内容** - 对嵌入的段落进行反复分析并格式化
-   **超链接支持** - 适当处理表格单元格内的链接

### 清单处理

使用 DOCX 编号系统的列表 :

-   **编号ID映射** - 将抽象 Num 映射到格式化( Bullet vs 小数)
-   **开始取出值** - 提取和保存所订购清单的起始数字
-   **巢穴保护** - 保持正确的列表等级
-   **连续分组** - 将连续列表项目归入列表容器

## 实例

### 基本用途

```typescript
import { parseDOCX } from "@docen/import-docx";

const buffer = readFileSync("example.docx");
const content = await parseDOCX(buffer);

console.log(JSON.stringify(content, null, 2));
```

### 使用 TipTap 编辑器

```typescript
import { Editor } from "@tiptap/core";
import { parseDOCX } from "@docen/import-docx";

const editor = new Editor({
  extensions: [...],
  content: "",
});

// Import DOCX file
async function importDocx(file: File) {
  const buffer = await file.arrayBuffer();
  const content = await parseDOCX(buffer);
  editor.commands.setContent(content);
}
```

### 有图像剪接的节点.js 环境

要在节点环境中实现图像裁剪, 您需要提供 `@napi-rs/canvas`数字 :

```typescript
import { parseDOCX } from "@docen/import-docx";
import { readFileSync } from "node:fs";

// Install @napi-rs/canvas first: pnpm add @napi-rs/canvas
const buffer = readFileSync("document.docx");

const content = await parseDOCX(buffer, {
  image: {
    canvasImport: () => import("@napi-rs/canvas"),
    crop: true, // Enable physical cropping (default is false)
  },
});
```

**说明:** 默认情况下,物理图像裁剪被禁用. 裁剪元数据在输出中被保存,用于往返转换,但使用了完整的图像数据.

### 禁用图像裁剪

如果您想要在 DOCX 中明确忽略裁剪信息并使用完整图像( 这是默认行为) :

```typescript
const content = await parseDOCX(buffer, {
  image: {
    crop: false,
  },
});
```

## 已知的限制

### 块引号检测

DOCX没有语义上的块引文结构. 块数被检测到 :

-   左缩进 ~ 720 twips (0.5英寸)
-   左边界(单线)的存在

这种检测方法可能为带有类似块式缩进的自定义文件产生假阳性.

### 代码标记

这个 `code` 标记不会自动从单空间字体(Consolas, Courier New等)中检测出。 这是有意避免虚假阳性. 代码标记应该在源文档中或通过编辑器UI明确添加.

### 颜色格式

所有颜色作为六进制值(例如"#FF000","#00800")导入. 原始文档中的颜色名称没有保留 .

### 图像限制

-   只支持嵌入式图像( 未获取外部图像链接)
-   从 DOCX 元数据取出图像尺寸和标题
-   **图像裁剪**:默认情况下,保留了裁剪元数据,但图像并未实际裁剪
    -   为便于实际收割,设置 `image.crop: true` 选项中
    -   在浏览器环境中, 裁剪与 Canvas API 本地工作
    -   在Node.js中,您还必须提供 `image.canvasImport` 选项 `@napi-rs/canvas`
    -   若为 `@napi-rs/canvas` 在Node.js中不可用,将导入图像而不裁剪(严重退化)
-   一些 DOCX 图像特性( 如高级定位或文本包装) 支持有限

### 表格单元格类型

DOCX格式在语义层面不区分头细胞和体细胞. 所有单元格均导入为 `tableCell` 类型。 这是一个 DOCX 格式限制 .

## 捐款

欢迎捐款! 请读我们的 [《促进者公约》](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) 并提交拉动请求 [主要仓库](https://github.com/DemoMacro/docen)。 。 。 .

## 许可证

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

## 常见问题

### @docen/import-docx 是什么？

一个强大的 TipTap/ProseMirror 扩展来导入 Microsoft Word DOCX 文件到编辑内容注意：该包已被作者标记为弃用——Deprecated: merged into @docen/docx — use @docen/docx for DOCX parse/generate\.

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

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

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

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

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

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

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

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

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

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

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

最新版本 0\.2\.9 发布于 2026/04/27（6 个月前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/01/11。作者已将其标记为弃用，新项目建议寻找替代方案。