Mammoth.js 使用详解

Mammoth.js 使用详解

Mammoth.js 是一个用于将 Word 文档（.docx）转换为 HTML 或 Markdown 的 JavaScript 库，支持浏览器和 Node.js 环境。

安装

浏览器环境

<script src="https://unpkg.com/[email protected]/mammoth.browser.min.js">script>

Node.js 环境

npm install mammoth
# 或
yarn add mammoth

基本使用

1. 将 DOCX 转换为 HTML

// 浏览器中使用 input[type=file] 获取文件
document.getElementById("docx-file").addEventListener("change", function(event) {
  const file = event.target.files[0];
  
  mammoth.extractRawText({arrayBuffer: file})
    .then(function(result) {
      document.getElementById("output").innerHTML = result.value;
      console.log(result.messages); // 转换过程中的消息
    })
    .catch(function(error) {
      console.error(error);
    });
});

// Node.js 中使用
const mammoth = require("mammoth");
const fs = require("fs");

fs.readFile("document.docx", function(err, data) {
  mammoth.extractRawText({arrayBuffer: data})
    .then(function(result) {
      fs.writeFileSync("output.html", result.value);
    })
    .catch(function(error) {
      console.error(error);
    });
});

2. 转换为 Markdown

mammoth.convertToMarkdown({arrayBuffer: file})
  .then(function(result) {
    console.log(result.value); // Markdown 内容
  });

核心 API

转换方法

• mammoth.convertToHtml(input, options) - 转换为 HTML
• mammoth.convertToMarkdown(input, options) - 转换为 Markdown
• mammoth.extractRawText(input) - 提取纯文本

输入格式

输入可以是以下形式之一：

• {arrayBuffer: arrayBuffer} - ArrayBuffer 对象
• {buffer: buffer} - Node.js Buffer 对象
• 浏览器中的 File 对象

高级功能

1. 自定义样式映射

const options = {
  styleMap: [
    "p[style-name='Heading 1'] => h1:fresh",
    "p[style-name='Heading 2'] => h2:fresh",
    "r[style-name='Strong'] => strong"
  ]
};

mammoth.convertToHtml({arrayBuffer: file}, options)
  .then(function(result) {
    // 使用自定义样式映射的 HTML
  });

2. 处理图片

const options = {
  convertImage: mammoth.images.imgElement(function(image) {
    return image.read("base64").then(function(imageBuffer) {
      return {
        src: "data:" + image.contentType + ";base64," + imageBuffer
      };
    });
  })
};

mammoth.convertToHtml({arrayBuffer: file}, options);

3. 自定义转换器

function convertParagraph(element) {
  if (element.styleId && element.styleId === "Heading1") {
    return { type: "element", tagName: "h1", children: element.children };
  }
}

const options = {
  converters: {
    paragraph: convertParagraph
  }
};

4. 忽略空段落

const options = {
  ignoreEmptyParagraphs: true
};

实际应用示例

1. 在浏览器中预览 DOCX 文件

<input type="file" id="docx-input">
<div id="preview">div>

<script>
document.getElementById("docx-input").addEventListener("change", function(e) {
  const file = e.target.files[0];
  
  mammoth.convertToHtml({arrayBuffer: file})
    .then(function(result) {
      document.getElementById("preview").innerHTML = result.value;
    })
    .catch(function(error) {
      console.error(error);
    });
});
script>

2. 批量转换 DOCX 到 HTML (Node.js)

const mammoth = require("mammoth");
const fs = require("fs");
const path = require("path");

const inputDir = "./docx-files";
const outputDir = "./html-files";

fs.readdir(inputDir, (err, files) => {
  files.forEach(file => {
    if (path.extname(file) === ".docx") {
      const inputPath = path.join(inputDir, file);
      const outputPath = path.join(outputDir, path.basename(file, ".docx") + ".html");
      
      fs.readFile(inputPath, (err, data) => {
        mammoth.convertToHtml({buffer: data})
          .then(result => {
            fs.writeFileSync(outputPath, result.value);
            console.log(`Converted ${file} to HTML`);
          })
          .catch(error => {
            console.error(`Error converting ${file}:`, error);
          });
      });
    }
  });
});

3. 提取文档中的图片并保存

const options = {
  convertImage: mammoth.images.imgElement(function(image) {
    const extension = image.contentType.split("/")[1];
    const filename = `image-${Date.now()}.${extension}`;
    
    return image.read().then(function(imageBuffer) {
      fs.writeFileSync(path.join("images", filename), imageBuffer);
      return { src: `images/${filename}` };
    });
  })
};

mammoth.convertToHtml({buffer: data}, options);

注意事项

1. 格式支持：Mammoth 主要处理文档的结构和文本，复杂的格式可能无法完美转换
2. 大型文档：处理非常大的文档可能会消耗较多内存
3. 样式限制：不是所有 Word 样式都能准确转换为 HTML/CSS
4. 表格支持：表格会被转换为 HTML 表格，但复杂表格可能格式不完美

Mammoth.js 是一个强大的工具，特别适合需要将 Word 文档内容集成到 Web 应用中的场景，如 CMS 系统、文档管理系统等。