# @aidalinfo/office-to-markdown 中文文档 规范地址：https://npmcn.com/package/%40aidalinfo/office-to-markdown/ 版本：1\.0\.2 npm 元数据更新时间：2025-08-27T15:00:42.620Z 中文译文更新时间：2026-11-06T15:46:24.749Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aidalinfo/office-to-markdown 原文对照：https://npmcn.com/package/%40aidalinfo/office-to-markdown/?lang=original 项目主页：https://github.com/aidalinfo/extract-kit#readme 源码仓库：https://github.com/aidalinfo/extract-kit ## 关键信息（来自 npm 元数据） - 包体积（解压后）：101 kB，27 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.0\.0 - 运行依赖：3 个 - peer 依赖：typescript \>=4\.5\.0 - 首次发布：2025-08-11T13:21:06.250Z - 最新版本发布：2025-08-27T15:00:42.437Z - 近 30 天下载量：2847（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：3（近 12 个月 0 个） ## 中文简介 用于将Office文档(DOCX)转换为Markdown格式的现代TypeScript库,通过增强表支持和数学等式转换,为 Bun 运行时优化. ## 安装 ```sh npm install @aidalinfo/office-to-markdown ``` 也可以使用：`pnpm add @aidalinfo/office-to-markdown`、`yarn add @aidalinfo/office-to-markdown`、`bun add @aidalinfo/office-to-markdown` ## README # @ aidalinfo/ 办公室到标记下 [![npm version](https://badge.fury.io/js/%40aidalinfo%2Foffice-to-markdown.svg)](https://badge.fury.io/js/%40aidalinfo%2Foffice-to-markdown) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh/) 一个现代化的TypeScript库,用于将Office文档(DOCX)转换为Markdown格式,在高级支持数学方程式和表格的情况下,为Bun生态系统进行了优化. > **通过微软的逆向工程创建 [标记下方](https://github.com/microsoft/markitdown)** - TypeScript的再执行,将Python的文档转换能力带入JavaScript/Bun生态系统,增强性能和类型安全. ## \* 特性 - ✅ **DOCX 到 Markdown 转换** 结构保护 - ✅ **数学等式支持** (OMML ~ LaTeX) (中文(简体) ) - ✅ **表格处理** 自动格式化 - ✅ **样式保存** (粗体、斜体、标题) - ✅ **图像处理** 带备选案文文本 - ✅ **简单而高级的 API** 用于不同用途的情况 - ✅ **强力错误处理** 带有特定错误代码 - ✅ **最佳业绩** 用 Bun 运行时间 - ✅ **完整类型脚本类型** 用于更好的 DX ## \* 安装 ### 使用 Bun( 建议) ```bash bun add @aidalinfo/office-to-markdown ``` ### 以npm/yarn/pnpm计 ```bash npm install @aidalinfo/office-to-markdown # or yarn add @aidalinfo/office-to-markdown # or pnpm add @aidalinfo/office-to-markdown ``` ### 所需依赖 自动安装以下依赖性: - `mammoth` - DOCX 到 HTML 转换 - `turndown` - HTML 到Markdown 转换 - `jszip` - ZIP存档操作(DOCX) ## \* 转换工作流程 转换过程遵循这些步骤: 1. **文件检测** - MIME类型和扩展核查 2. **预处理** - DOCX内容提取和修改 3. **数学处理** - OMML — LaTeX 转换 4. **主要转换** - DOCX – HTML 通过长毛象 5. **后处理** - HTML – 有自定义规则的标记 ## 简单使用 ### 基本转换 ```typescript import { docxToMarkdown } from '@aidalinfo/office-to-markdown'; // Simple file conversion const markdown = await docxToMarkdown('./document.docx'); console.log(markdown); ``` ### 高级 API ```typescript import { OfficeToMarkdown } from '@aidalinfo/office-to-markdown'; const converter = new OfficeToMarkdown({ headingStyle: 'atx', // Use ## for headings preserveTables: true, // Preserve tables convertMath: true, // Convert equations to LaTeX }); // Conversion with options const result = await converter.convertDocx('./document.docx'); console.log('Title:', result.title); console.log('Content:', result.markdown); ``` ### 从不同来源转换 ```typescript import { OfficeToMarkdown } from '@aidalinfo/office-to-markdown'; const converter = new OfficeToMarkdown(); // From file path const result1 = await converter.convert('./document.docx'); // From Buffer const buffer = await Bun.file('./document.docx').arrayBuffer(); const result2 = await converter.convert(buffer); // From Bun file const file = Bun.file('./document.docx'); const result3 = await converter.convert(file); // Batch processing const results = await converter.convertMultiple([ './doc1.docx', './doc2.docx', buffer ]); ``` ## QQ 配置选项 | 选项 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | `headingStyle` | `'atx' | 'setext'` | `'atx'` | 标记下行向样式 | | `preserveTables` | `boolean` | `true` | 保留表格 | | `convertMath` | `boolean` | `true` | 转换数学等式 | | `styleMap` | `string` | \- 说吧 | 自定义长毛图映射 | ## 技术结构 ### 模块结构 ``` src/ ├── converters/ # Document converters │ ├── base-converter.ts # Abstract base class │ └── docx-converter.ts # Specialized DOCX converter ├── preprocessing/ # Preliminary processing │ └── docx-preprocessor.ts # DOCX preprocessing (math) ├── math/ # Mathematical processing │ └── omml-processor.ts # OMML → LaTeX converter ├── utils/ # Utilities │ ├── html-to-markdown.ts # HTML → Markdown conversion │ ├── file-detector.ts # File type detection │ └── error-handler.ts # Error handling └── types/ # TypeScript definitions ├── converter.ts # Converter types ├── result.ts # Result types └── stream-info.ts # File info types ``` ### 转换管道 1. **文件检测** - MIME类型和扩展核查 2. **预处理** - DOCX内容提取和修改 3. **数学处理** - OMML — LaTeX 转换 4. **主要转换** - DOCX – HTML 通过长毛象 5. **后处理** - HTML – 有自定义规则的标记 ### 数学方程式处理 等式转换遵循这个过程: ```typescript // OMML (Office Math Markup Language) 1 2 // ↓ Preprocessing $\frac{1}{2}$ // ↓ Mammoth (HTML)

$\frac{1}{2}$

// ↓ Turndown (Markdown) $\frac{1}{2}$ ``` ### 支持的数学元素 | OMML 数据 | 拉特克语Name | 说明 | | --- | --- | --- | | `` | `\frac{}{}` | 小数 | | `` | `^{}` | 指标 | | `` | `_{}` | 下标 | | `` | `\sqrt{}` | 平方根数 | | `` | `\sqrt[]{}` | 第九个根 | ## 高级使用示例 ### 处理错误 ```typescript import { OfficeToMarkdown, FileConversionException, UnsupportedFormatException } from '@aidalinfo/office-to-markdown'; async function convertSafely(filePath: string) { try { const converter = new OfficeToMarkdown(); const result = await converter.convertDocx(filePath); return result.markdown; } catch (error) { if (error instanceof UnsupportedFormatException) { console.error('Unsupported format:', error.message); } else if (error instanceof FileConversionException) { console.error('Conversion error:', error.message); } else { console.error('Unexpected error:', error.message); } throw error; } } ``` ### 能力检查 ```typescript import { OfficeToMarkdown } from '@aidalinfo/office-to-markdown'; const converter = new OfficeToMarkdown(); // Check supported types const info = converter.getSupportedTypes(); console.log('Extensions:', info.extensions); // ['.docx'] console.log('MIME types:', info.mimeTypes); // Check if a file is supported const isSupported = await converter.isSupported('./document.pdf'); console.log('PDF supported:', isSupported); // false // Get file information const fileInfo = await converter.getFileInfo('./document.docx'); console.log('MIME type:', fileInfo.mimetype); console.log('Supported:', fileInfo.supported); ``` ### 使用节点js ```typescript import { readFile } from 'fs/promises'; import { OfficeToMarkdown } from '@aidalinfo/office-to-markdown'; // From Node.js Buffer const buffer = await readFile('./document.docx'); const converter = new OfficeToMarkdown(); const result = await converter.convert(buffer); console.log(result.markdown); ``` ## 测试和验证 ### 测试结果 - XQHTML – 有表格的标记下转换 - QQ 文件类型检测( DOCX vs 他人) - — OMML — LaTeX 数学转换 - QQ 处理特定代码出错 - \* 用真实文件完成管道测试 ### 业绩 - **速度**: ~80ms 平均文档 (7KB) - **忠诚**: 完全保留结构和内容 - **强健性**: 处理后退错误 ## 发展 ### 先决条件 - **阿宝** >= 1.2.0(建议)或 **节点.js** 页:1 - **类型脚本** \* 4.5.0 ### 开发安装 ```bash git clone https://github.com/aidalinfo/extract-kit.git cd extract-kit/packages/office-to-markdown bun install ``` ### 可用的脚本 ```bash bun run build # Complete build (ESM + types) bun run dev # Development mode with watch bun run clean # Clean dist/ folder ``` ### 测试 ```bash # Basic functionality test bun run src/test.ts # Test with real DOCX file bun run test-docx.ts "your-file.docx" ``` ## \* 路线图 - [ ] **PPT/PPTX格式支持** - 演示文稿转换 - [ ] **XLS/XLSX 格式支持** - 电子表格转换 - [ ] **流出 API** - 大文件流处理 - [ ] **插件系统** - 支持自定义转换器 - [ ] **网络接口** - 可选用户界面 - [ ] **嵌入式图像支持** - 图像取出和转换 - [ ] **CLI 批量模式** - 命令线接口 ## 捐款 欢迎捐款! 请看我们的 [捐款指南](https://github.com/aidalinfo/extract-kit/blob/main/CONTRIBUTING.md)。 。 。 . ### 贡献进程 1. **叉头** 存储器 2. **创建** 特性分支( e)`git checkout -b feature/amazing-feature`(中文(简体) ) 3. **提交** 更改( c)`git commit -m 'Add amazing feature'`(中文(简体) ) 4. **推开** 对分支机构(`git push origin feature/amazing-feature`(中文(简体) ) 5. **打开** a 拉动请求 ## 许可证 这个项目的许可证根据 **麻省理工学院** - 看这个 [自由主义](https://npmcn.com/package/%40aidalinfo/office-to-markdown/LICENSE) 详细文件. ## 承认 - 受到微软的启发 [标记下方](https://github.com/microsoft/markitdown) 项目 - 用途 [毛发.js](https://github.com/mwilliamson/mammoth.js) dOCX — HTML 转换 - 用途 [关闭](https://github.com/mixmark-io/turndown) hTML — 标记下转换 - 优化用于 [阿宝](https://bun.sh/) 运行时间 ## ++ 辅助 - **问题**数字 : [GitHub 问题](https://github.com/aidalinfo/extract-kit/issues) - **文档**数字 : [GitHub 仓库](https://github.com/aidalinfo/extract-kit/tree/main/packages/office-to-markdown) - **电子邮件**数字 : [联系人@aidarinfo.com](mailto:contact@aidalinfo.com) * * * **[@ aidarinfo/ 办公室对标记](https://www.npmjs.com/package/@aidalinfo/office-to-markdown)** _简单、快和可靠的 DOCX 到 Markdown 转换_ ⚡ ## 常见问题 ### @aidalinfo/office-to-markdown 是什么？ 用于将Office文档\(DOCX\)转换为Markdown格式的现代TypeScript库,通过增强表支持和数学等式转换,为 Bun 运行时优化\. ### 如何安装 @aidalinfo/office-to-markdown？ 在项目目录运行 npm install @aidalinfo/office-to-markdown，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（\>=4\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @aidalinfo/office-to-markdown 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @aidalinfo/office-to-markdown 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @aidalinfo/office-to-markdown 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @aidalinfo/office-to-markdown 可以商用吗？ @aidalinfo/office-to-markdown 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @aidalinfo/office-to-markdown 的下载量有多少？ 根据 npm 官方下载统计，@aidalinfo/office-to-markdown 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,847 次，日均约 95 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aidalinfo/office-to-markdown 还在维护吗？ 最新版本 1\.0\.2 发布于 2025/08/27（1\.2 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/08/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。