@ docen/ 导入- docx
将 Microsoft Word DOCX 文件导入 TipTap/ProseMirror 内容.
特征
- 📝 丰富的文本解析 - 准确分析标题、段落和有格式的区块
- 🖼️ 图像提取 - 自动提取图像,提供基数64转换和裁剪支持
- 📊 表格支持 - 带有colspan/rowspan检测算法的完整表格结构
- ✅ 列表任务( T) - 项目符号列表、带有起始数字提取的编号列表和带有复选框检测的任务列表
- 🎨 文本格式 - 粗体、斜体、下划线、下划线、上划线和亮点
- 🎯 文本样式 - 综合样式支持,包括颜色、背景、字体、大小和行高
- 🔗 链接 - 超链接提取与红外线保护
- 💻 代码块 - 带有语言属性提取的代码块检测
- 🌐 横线 - 在浏览器和节点环境中工作
- ✂️ 图像裁剪 - 作物元数据保存,可选择实物作物
- 🧠 智能分析 - DOCX XML 分析适当的元素分组和结构重建
- ⚡ 快速处理 - 用于超快ZIP减压
安装
# Install with npm
$ npm install @docen/import-docx
# Install with yarn
$ yarn add @docen/import-docx
# Install with pnpm
$ pnpm add @docen/import-docx
快速启动
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 文档内容,并嵌入图像
选项 :
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:
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提取
解析算法
文档结构
解析器遵循一个结构化的工作流程 :
- 提取关系 - 剖析
_rels/document.xml.rels用于超链接和图像 - 解析编号 - 从
numbering.xml(缩略语 = numFmt) - 进程文件正文 - 通过文档.xml 元素进行排列:
- 检测内容类型(表格、列表、段落、代码块等)
- 将连续元素组合入合适的容器
- 将 XML 节点转换为 TipTap JSON 节点
表格处理
表格使用专门的算法:
- 科尔斯潘检测 - 网格算法跟踪单元格位置并检测水平合并
- 行宽检测 - 垂直合并(vMorge) 横行跟踪,并有适当的单元格跳过
- 单元格内容 - 对嵌入的段落进行反复分析并格式化
- 超链接支持 - 适当处理表格单元格内的链接
清单处理
使用 DOCX 编号系统的列表 :
- 编号ID映射 - 将抽象 Num 映射到格式化( Bullet vs 小数)
- 开始取出值 - 提取和保存所订购清单的起始数字
- 巢穴保护 - 保持正确的列表等级
- 连续分组 - 将连续列表项目归入列表容器
实例
基本用途
import { parseDOCX } from "@docen/import-docx";
const buffer = readFileSync("example.docx");
const content = await parseDOCX(buffer);
console.log(JSON.stringify(content, null, 2));
使用 TipTap 编辑器
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数字 :
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 中明确忽略裁剪信息并使用完整图像( 这是默认行为) :
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 格式限制 .
捐款
欢迎捐款! 请读我们的 《促进者公约》 并提交拉动请求 主要仓库。 。 。 .