Word 文档导入导出技术方案详解

文件限制:

• 最大文件大小：10MB
• 支持格式：.docx, .md, .markdown, .txt

3. Word 文档解析 (mammoth)

核心函数：docxToHtml

这里我们利用 mammoth 库将二进制 Buffer 转换为 HTML。需要注意的是，样式映射和图片处理是其中的关键点。

async function docxToHtml(buffer: ArrayBuffer): Promise<ImportedDocumentResult> {
  const nodeBuffer = Buffer.from(buffer);
  const { value, messages } = await mammoth.convertToHtml({
    buffer: nodeBuffer,
    // 样式映射：将 Word 样式映射到 HTML 标签
    styleMap: [
      'p[style-name="Heading 1"] => h1:fresh',
      'p[style-name="Heading 2"] => h2:fresh',
      'p[style-name="Heading 3"] => h3:fresh',
      'p[style-name="Heading 4"] => h4:fresh',
    ],
    // 图片处理：转换为 base64 内联图片
    convertImage: mammoth.images.inline(async (image) => {
      const base64 = await image.read('base64');
      return {
        src: `data:${image.contentType};base64,${base64}`,
      };
    }),
  });

  // 清理样式（移除 text-indent 等）
  const sanitized = removeInlineTextIndentStyles(value.trim()) || '<p></p>';

  // 提取警告信息
  const warnings = messages?.filter((message) => message.type === 'warning').map((message) => message.message);

  return {
    format: 'docx',
    html: sanitized,
    warnings: warnings && warnings.length > 0 ? warnings : undefined,
  };
}

样式映射策略

mammoth 通过 styleMap 配置将 Word 内置样式映射到 HTML 标签。这里的 fresh 修饰符很重要，它确保每个样式都生成独立的新标签，避免合并到父元素导致结构混乱。

图片处理

代码中使用了 convertImage 回调来处理文档内的图片。工作原理很简单：检测到图片 -> 读取二进制数据 -> 转为 Base64 -> 生成 Data URL。

这样做的好处是所有资源自包含，无需额外请求，编辑器可直接渲染，甚至支持离线编辑。不过缺点也很明显，大图片会增加文档体积，且 Base64 编码比原始二进制大约 33%。

4. 样式清理

Word 导出的 HTML 往往带有很多冗余的内联样式，比如 text-indent。这可能会与编辑器的首行缩进规则冲突。我们需要一个清洗函数来过滤掉这些干扰项。

function removeInlineTextIndentStyles(html: string): string {
  return html.replace(
    /(style=)(['"])([^'"]*)(\2)/gi,
    (_match, prefix: string, quote: string, styles: string) => {
      const filtered = styles
        .split(';')
        .map((item) => item.trim())
        .filter(
          (item) =>
            item.length > 0 && !/^text-indent\s*:/i.test(item),
        );
      if (filtered.length === 0) {
        return '';
      }
      return `${prefix}${quote}${filtered.join('; ')}${quote}`;
    },
  );
}

示例：

<!-- 清理前 -->
<p style="text-indent: 2em; font-size: 14px;">段落内容</p>
<!-- 清理后 -->
<p style="font-size: 14px;">段落内容</p>

5. 纯文本和 Markdown 导入

除了 Word，我们也支持纯文本和 Markdown 文件的导入。对于纯文本，主要任务是检测段落分隔符并正确包裹为 <p> 标签。

function textToHtml(buffer: ArrayBuffer): ImportedDocumentResult {
  const text = normalizeTextContent(buffer).trim();
  // 检测段落分隔符（双换行）
  const hasDoubleBreak = /\n{2,}/.test(text);
  const rawBlocks = hasDoubleBreak ? text.split(/\n{2,}/) : text.split(/\n/);
  const paragraphs = rawBlocks
    .map((block) => block.replace(/\n+/g, '\n').trim())
    .filter(Boolean)
    .map((paragraph) => {
      if (!hasDoubleBreak) {
        return `<p>${escapeHtml(paragraph)}</p>`;
      }
      // 段落内的单换行转换为 <br>
      const lines = paragraph.split('\n').map((line) => escapeHtml(line));
      return `<p>${lines.join('<br>') }</p>`;
    });

  return {
    format: 'text',
    html: paragraphs.join('\n'),
  };
}

技术细节

在实际开发中，有几个坑需要注意。首先是图片的存储问题，虽然 Base64 方便，但超过一定大小会导致性能下降。如果文档很大，建议考虑将图片单独上传到 OSS，然后在 HTML 中替换为外部链接。其次是样式兼容性，不同版本的 Word 生成的 HTML 结构差异较大，测试时要覆盖多种模板。

最佳实践

1. 异步处理：大文件解析耗时较长，建议在 API 层使用队列或异步任务，避免阻塞主线程。
2. 错误边界：解析过程中可能遇到损坏的文件，务必捕获异常并返回友好的提示。
3. 版本控制：依赖库更新频繁，锁定版本号能减少意外破坏。

通过以上方案，我们可以实现一个稳定、高效的 Word 文档导入导出功能，满足大多数富文本编辑场景的需求。