快速上手 vue-office：在 Vue 项目中优雅集成 Office 文档预览

各位前端开发者，大家好！

你是否曾在项目中遇到过这样的需求：需要在网页上直接展示 Word、Excel、PPT 或 PDF 文件？传统方案往往需要后端服务支持，或者依赖那些笨重且兼容性不佳的浏览器插件。这不仅增加了开发复杂度，也影响了用户体验。

今天，我向大家推荐一个纯前端解决方案——vue-office。它是一个专为 Vue 3/2 打造的 Office 文档预览组件库，能让你以一种前所未有的优雅方式，在项目中轻松集成文档预览功能。

🤔 为什么 vue-office 是你的不二之选？

• 📦 开箱即用，与 Vue 生态完美契合：作为专为 Vue 设计的组件，它遵循直观的组件化思想，集成过程丝滑流畅，同时兼容 Vue 2。
• 📁 主流格式，一网打尽：核心支持预览 Word (.docx)、Excel (.xlsx)、PPT (.pptx) 和 PDF 文件，满足绝大多数业务需求。
• 🌐 纯前端渲染，解放后端：所有文件的解析和渲染都在浏览器端完成，无需服务器转换，极大减轻了后端压力，并提升了响应速度。
• 💪 功能强大，易于扩展：不仅支持分页渲染，还提供了丰富的事件钩子（如渲染完成、失败），并允许通过 options 属性向底层库传递高级配置。
• 🍃 轻量化设计，按需加载：将不同格式的预览功能拆分成独立的包，你可以根据项目需求按需引入，有效控制打包体积。

---

快速安装指南

vue-office 的模块化设计让你可以只安装你需要的部分。请注意，为了兼容 Vue 2 和 Vue 3，需要额外安装 vue-demi。

# 1. 安装 Word 预览组件
npm install @vue-office/docx vue-demi

# 2. 安装 Excel 预览组件
npm install @vue-office/excel vue-demi

# 3. 安装 PDF 预览组件
npm install @vue-office/pdf vue-demi

# 4. 安装 PPTX 预览组件
npm install @vue-office/pptx vue-demi

对于 Vue 2.6 及以下版本，还需额外安装 @vue/composition-api：

npm install @vue/composition-api

---

核心用法：三步集成预览功能

vue-office 的 API 设计极其简洁。你只需导入相应组件，并通过 src 属性提供文档的 URL 或文件对象即可。

预览 Word 文档

<template>
  <div>
    <VueOfficeDocx
      :src="docxSrc"
      style="height: 80vh"
      @rendered="onRendered"
      @error="onError"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
// 引入 Word 预览组件
import VueOfficeDocx from "@vue-office/docx";

// 你的 .docx 文件链接
const docxSrc = ref("/doc.docx");

const onRendered = () => {
  console.log("Word 文档渲染完成！");
};

const onError = (error) => {
  console.error("渲染 Word 文档时出错:", error);
};
</script>

预览 Excel 表格

<template>
  <div class="excel-container">
    <VueOfficeExcel
      :src="xlsxSrc"
      style="height: 100vh;"
      @rendered="onRendered"
      @error="onError"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
// 1. 引入 Excel 预览组件
import VueOfficeExcel from "@vue-office/excel";

// 2. 设置 .xlsx 文件链接
const xlsxSrc = ref("/xls.xlsx");

// 3. 监听渲染事件
const onRendered = () => {
  console.log("🎉 Excel 表格渲染完成！");
};

const onError = (error) => {
  console.error("❌ 渲染 Excel 表格时出错:", error);
};
</script>

预览 PDF 文档

<template>
  <div class="pdf-container">
    <VueOfficePdf
      :src="pdfSrc"
      style="height: 100vh;"
      @rendered="onRendered"
      @error="onError"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
// 1. 引入 PDF 预览组件
import VueOfficePdf from "@vue-office/pdf";

// 2. 设置 .pdf 文件链接
const pdfSrc = ref("/pdf.pdf");

// 3. 监听渲染事件
const onRendered = () => {
  console.log("🎉 PDF 文档渲染完成！");
};

const onError = (error) => {
  console.error("❌ 渲染 PDF 文档时出错:", error);
};
</script>

预览 PPTX 幻灯片

<template>
  <div class="pptx-container">
    <VueOfficePptx
      :src="pptxSrc"
      style="height: 100vh;"
      @rendered="onRendered"
      @error="onError"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
// 1. 引入 PPTX 预览组件
import VueOfficePptx from "@vue-office/pptx";

// 2. 你的 .pptx 文件链接
const pptxSrc = ref("/pptx.pptx");

// 3. 监听渲染事件
const onRendered = () => {
  console.log("🎉 PPTX 幻灯片渲染完成！");
};

const onError = (error) => {
  console.error("❌ 渲染 PPTX 幻灯片时出错:", error);
};
</script>

---

进阶实战：本地文件上传与即时预览

在实际项目中，最常见的场景莫过于让用户上传本地文件并立即预览。下面是一个完整的实现示例：

<template>
  <div>
    <h4>选择一个 Word 文档进行预览：</h4>
    <input type="file" @change="handleFileChange" accept=".docx" />
    <hr />
    <div v-if="!docxSrc" class="placeholder">请选择文件</div>
    <VueOfficeDocx v-else :src="docxSrc" style="height: 80vh;" />
  </div>
</template>

<script setup>
import { ref } from "vue";
import VueOfficeDocx from "@vue-office/docx";
import "@vue-office/docx/lib/index.css";

const docxSrc = ref(null);

const handleFileChange = (event) => {
  // 获取用户选择的文件
  const file = event.target.files[0];
  if (file) {
    // 将 File 对象直接赋值给 src 属性
    docxSrc.value = file;
  }
};
</script>

---

技术揭秘：底层是如何工作的？

vue-office 的强大功能并非凭空而来，它巧妙地整合了多个成熟的开源库：

• Word (.docx): 底层使用 docx-preview，它能将 .docx 文件转换成 HTML 进行渲染。
• Excel (.xlsx): 底层使用大名鼎鼎的 SheetJS (xlsx) 进行解析，并将其渲染成表格。
• PPTX (.pptx): 底层使用 pptx-preview，将 PPTX 文件解析并渲染为图片序列。
• PDF: 底层依赖 Mozilla 的 pdf.js，这是目前最主流的纯 JS PDF 渲染引擎。

vue-office 的价值在于将这些库封装成统一、易用的 Vue 组件，并处理了加载、渲染、错误处理等一系列通用逻辑，让开发者可以聚焦于业务本身。

---

总结与展望

vue-office 为 Vue 生态系统提供了一个轻量、强大且纯前端的 Office 文档预览解决方案。它通过简洁的 API 和模块化的设计，极大地降低了在 Web 应用中集成文档预览功能的门槛。

无论是开发企业内部的 OA 系统、在线教育平台，还是需要文档展示的内容管理系统，vue-office 都能成为你工具箱中一把锋利的瑞士军刀。

如果你还在为文档预览而烦恼，不妨现在就去试试 vue-office 吧！相信它会给你带来惊喜。

项目地址: vue-office