vue2-file-preview-kit

vue2-file-preview-kit

Vue 2 多类型文件在线预览组件 —— 图片 / PDF / Word / Excel / PPT / Markdown / 代码 / 音视频，一个组件全部搞定。

纯前端本地解析，无需后端服务。所有解析器（pdf.js、mammoth、SheetJS、pptx-preview、marked、highlight.js 等）已内置打包，运行时零依赖（vue 为 peerDependency）。

功能矩阵

安装

npm i vue2-file-preview-kit
# 或
yarn add vue2-file-preview-kit

要求 vue ^2.6 / ^2.7。

快速开始

插件方式（全局注册）

import Vue from 'vue'
import VueFilePreviewKit from 'vue2-file-preview-kit'
import 'vue2-file-preview-kit/dist/style.css'

Vue.use(VueFilePreviewKit, {
  // 可选：内网/离线环境必须配置 pdf.js worker 地址
  pdfWorkerSrc: '/static/pdf.worker.min.js'
})

<template>
  <vue-file-preview src="/files/季度报表.xlsx" :height="640" />
</template>

局部注册（按需）

<script>
import { VueFilePreview } from 'vue2-file-preview-kit'
import 'vue2-file-preview-kit/dist/style.css'

export default {
  components: { VueFilePreview }
}
</script>

本地文件（File 对象）

<template>
  <vue-file-preview :file="file" :file-name="file && file.name" />
</template>

<script>
export default {
  data: () => ({ file: null }),
  methods: {
    onPick(e) {
      this.file = e.target.files[0] || null
    }
  }
}
</script>

带鉴权的私有文件

<vue-file-preview
  src="https://api.example.com/files/12345"
  :headers="{ Authorization: 'Bearer <token>' }"
  :with-credentials="true"
  :timeout="30000"
  file-name="合同.docx"
/>

Props

Events

全局配置

import { setGlobalConfig } from 'vue2-file-preview-kit'

setGlobalConfig({
  pdfWorkerSrc: '/static/pdf.worker.min.js', // pdf.js worker 地址
  textMaxSize: 10 * 1024 * 1024, // 文本类最大渲染体积（默认 10MB）
  pdfMaxPages: 100 // PDF 最大渲染页数（默认 100）
})

类型识别规则

优先级：显式 type > 文件名扩展名 > MIME（Content-Type）> 文件头魔数。

魔数识别覆盖 PDF、PNG、JPEG、GIF、BMP、WEBP、SVG、MP3、WAV、FLAC、OGG、MP4 等，扩展名缺失或错误时也能正确归类。

常见问题与说明

PDF 渲染需要 worker

pdf.js 必须加载 worker 才能解析。组件内置多 CDN 自动兜底链：jsDelivr → npmmirror → unpkg。若运行环境无法访问公网（内网/离线），请将 pdfjs-dist@3.11.174/build/pdf.worker.min.js 拷贝到可访问目录并通过 pdfWorkerSrc（或 setGlobalConfig）指定。

旧版 Office（doc/ppt/xls/wps/et/dps…）

二进制格式浏览器端无成熟解析器。当文件是公网可访问的 http(s) 地址时，组件使用 Office Online 预览服务嵌入展示；否则展示下载引导面板。如需强制本地/在线，可用 viewer="local" / viewer="online"。docx / xlsx / pptx 均为本地解析，无此限制。

音视频播放说明

音视频通过浏览器原生 <video> / <audio> 直接播放远程地址（不整包下载、不受 CORS fetch 限制）。服务器若校验 Referer 或要求鉴权头，需自行保证媒体地址可被浏览器直接访问。通过 file 传入的本地文件会自动转为 blob 播放。

PPTX 兼容处理

部分工具（如 pptxgenjs 等）生成的 pptx 会在 [Content_Types].xml 中登记不存在的部件，导致解析器中断。组件内置 sanitizePptx 预处理，自动剔除无效条目后渲染，兼容此类"脏"文件。

渲染保护

• PDF 仅渲染前 100 页（可配置）
• 文本类超过 10MB 只展示下载引导（可配置）
• Excel 仅渲染前 500 行 × 60 列，超出提示下载

TypeScript

内置完整类型声明（types/index.d.ts），支持 FileCategory、PreviewError、loadResource 等全部导出的类型推导。

工具函数导出

import {
  resolveCategory, // 综合推断文件类别
  sniffCategory, // 魔数识别
  loadResource, // 统一加载（URL / File / Blob）
  decodeText, // 文本解码（UTF-8 严格 → GBK 回退）
  downloadFile, // 统一下载（URL / File / Blob / ArrayBuffer）
  triggerDownload, // 触发浏览器下载
  PreviewError, // 带 code 的错误类型
  formatSize, // 文件体积格式化
  CATEGORIES, // 类别常量
  CATEGORY_META // 类别展示元信息（label/icon/color）
} from 'vue2-file-preview-kit'

浏览器支持

现代浏览器（Chrome / Edge / Firefox / Safari），需支持 ES2015+、Promise、Fetch、Canvas。不支持 IE。

License

MIT