前端使用 docx-preview 实现word解析实战

docx-preview 是一个轻量级的 JavaScript 库，用于在浏览器中预览 Word 文档（.docx），无需后端转换。它通过直接解析 .docx 的 XML 结构，在前端渲染为 HTML 展示。

以下是在项目中实战使用的完整步骤：

一、安装依赖

首先安装 docx-preview 核心库，以及可能需要的辅助库（如处理文件读取的 file-saver 可选）：

csharp 复制代码

bash npm install docx-preview --save 
# 或 
yarn add docx-preview

二、基础使用：预览本地/远程 .docx 文件

场景1：预览本地上传的 Word 文件

通过 <input type="file"> 让用户上传 .docx 文件，解析后预览：

jsx 复制代码

import React, { useRef } from 'react';
import { renderAsync } from 'docx-preview';

const DocxPreview = () => {
  const previewRef = useRef(null); // 用于挂载预览内容的容器

  // 处理文件上传
  const handleFileChange = async (e) => {
    const file = e.target.files[0];
    if (!file) return;

    // 验证文件类型
    if (file.type !== 'application/vnd.openxmlformats-officedocument.wordprocessingml.document') {
      alert('请上传 .docx 格式的文件');
      return;
    }

    try {
      // 清空之前的预览内容
      previewRef.current.innerHTML = '';

      // 解析并渲染 Word 文档
      await renderAsync(
        file, // 上传的文件对象
        previewRef.current, // 挂载预览的 DOM 容器
        null, // 配置项（可选）
        {
          // 加载状态回调（可选）
          onLoadStart: () => console.log('开始加载...'),
          onLoadEnd: () => console.log('加载完成'),
        }
      );
    } catch (err) {
      console.error('解析失败：', err);
      previewRef.current.innerHTML = '文档解析失败，请检查文件是否损坏';
    }
  };

  return (
    <div>
      <input type="file" accept=".docx" onChange={handleFileChange} />
      <div ref={previewRef} style={{ marginTop: 20, minHeight: 300 }} />
    </div>
  );
};

export default DocxPreview;

场景2：预览远程服务器上的 .docx 文件通过 fetch 拉取远程 `.docx` 文件（需处理跨域），转换为 `ArrayBuffer` 后解析：

jsx 复制代码

import React, { useRef, useEffect } from 'react';
import { renderAsync } from 'docx-preview';

const RemoteDocxPreview = () => {
  const previewRef = useRef(null);
  const docUrl = 'https://example.com/files/test.docx'; // 远程 .docx 地址

  useEffect(() => {
    const fetchAndRenderDoc = async () => {
      try {
        const response = await fetch(docUrl);
        if (!response.ok) throw new Error('文件请求失败');

        // 将响应转换为 ArrayBuffer（docx-preview 支持的格式）
        const arrayBuffer = await response.arrayBuffer();

        // 渲染文档
        await renderAsync(arrayBuffer, previewRef.current);
      } catch (err) {
        console.error('加载失败：', err);
        previewRef.current.innerHTML = '无法加载远程文档';
      }
    };

    fetchAndRenderDoc();
  }, [docUrl]);

  return <div ref={previewRef} style={{ padding: 20 }} />;
};

export default RemoteDocxPreview;

三、高级配置：自定义渲染效果

renderAsync 方法的第三个参数是配置对象，可自定义样式、忽略部分内容等：

arduino 复制代码

// 示例：自定义配置
const options = {
  className: 'docx-preview', // 给预览容器添加自定义类名（用于覆盖样式）
  inWrapper: true, // 是否包裹在默认容器中（默认 true）
  ignoreWidth: false, // 是否忽略文档宽度（默认 false）
  ignoreHeight: false, // 是否忽略文档高度（默认 false）
  ignoreFonts: false, // 是否忽略字体样式（默认 false）
  breakPages: true, // 是否分页（默认 true）
  ignoreLastRenderedPageBreak: true, // 是否忽略最后一个分页符
  experimental: false, // 是否启用实验性功能
  trimXmlDeclaration: true, // 是否移除 XML 声明
  useBase64URL: true, // 是否用 base64 处理图片
  renderChanges: false, // 是否渲染修订记录（默认 false）
  renderHeaders: true, // 是否渲染页眉（默认 true）
  renderFooters: true, // 是否渲染页脚（默认 true）
  renderFootnotes: true, // 是否渲染脚注（默认 true）
  renderEndnotes: true, // 是否渲染尾注（默认 true）
};

// 使用配置
await renderAsync(file, previewRef.current, options);

四、样式定制默认渲染的 HTML 会带有基础样式，可通过自定义 CSS 覆盖：

css 复制代码

/* 示例：调整预览区域样式 */
.docx-preview {
  max-width: 800px;
  margin: 0 auto;
  padding: 40px;
  background: white;
  box-shadow: 0 0 10px rgba(0,0,0,0.1);
}

/* 调整段落样式 */
.docx-preview p {
  margin: 10px 0;
  line-height: 1.5;
}

/* 隐藏页眉页脚（如果需要） */
.docx-preview .header,
.docx-preview .footer {
  display: none;
}

五、注意事项

文件格式限制 ：仅支持 .docx（Office 2007+），不支持 .doc（旧版二进制格式），如需支持 .doc 需后端转换（如用 libreoffice 或 poi）。
跨域问题：预览远程文件时，服务器需配置 CORS 允许前端域名访问，否则会报跨域错误。
复杂格式兼容性：对复杂表格、公式、特殊符号的渲染可能存在偏差，复杂场景建议结合后端转换为 PDF 预览。
性能：大文件（如超过 10MB）可能导致渲染缓慢，建议前端限制文件大小或后端分片处理。