file-preview-vue3-ts

一个基于 Vue 3 + TypeScript + Element Plus 的多功能文件预览组件。 支持 PDF、Office 文档 (Docx, Excel, PPTX)、图片、视频、音频、文本等多种格式的在线预览。

特性

• 📚 多格式支持：集成 @vue-office 实现 Office 文档预览，原生支持 PDF、图片、音视频及文本代码。
• ⚡ 懒加载：内置 IntersectionObserver，仅当文件进入视口时才加载资源，优化多文件预览性能。
• 🎭 多展示模式：
  • Tab 标签页：适合文档对比。
  • Carousel 走马灯：适合图片画廊。
  • List 列表：适合流式浏览。
• 📦 开箱即用：基于 Element Plus UI，提供优雅的加载与错误处理状态。
• 🛠 TypeScript：完全的类型定义支持。

安装

npm install file-preview-vue3-ts
# 确保已安装 peerDependencies
npm install vue element-plus

快速开始

全局注册

import { createApp } from 'vue'
import App from './App.vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import FilePreview from 'file-preview-vue3-ts'
import 'file-preview-vue3-ts/dist/style.css'

const app = createApp(App)
app.use(ElementPlus)
app.use(FilePreview)
app.mount('#app')

局部引入

<script setup lang="ts">
import { FilePreview } from 'file-preview-vue3-ts'
import 'file-preview-vue3-ts/dist/style.css'

const file = {
  url: 'https://example.com/document.docx',
  name: '测试文档.docx',
  type: 'docx'
}
</script>

<template>
  <div style="height: 600px;">
    <FilePreview :file="file" />
  </div>
</template>

多文件预览

支持传入数组，并配置 displayMode。

<script setup lang="ts">
import { FilePreview } from 'file-preview-vue3-ts'

const files = [
  { url: 'https://example.com/slide.pptx', name: '演示文稿', type: 'pptx' },
  { url: 'https://example.com/sheet.xlsx', name: '数据表', type: 'xlsx' },
  { url: 'https://example.com/image.png', name: '图片', type: 'png' }
]
</script>

<template>
  <!-- Tab 模式 (默认) -->
  <FilePreview :file="files" display-mode="tab" />
  
  <!-- 走马灯模式 -->
  <FilePreview :file="files" display-mode="carousel" />
  
  <!-- 列表模式 -->
  <FilePreview :file="files" display-mode="list" />
</template>

API

Props

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | file | IFileSource | IFileSource[] | - | 文件对象或数组 | | displayMode | 'tab' \| 'carousel' \| 'list' | 'tab' | 多文件展示模式 | | width | string \| number | '100%' | 容器宽度 | | height | string \| number | '100%' | 容器高度 | | multiFileConfig | object | - | 多文件模式的详细配置 (如 Tab 位置, 轮播间隔等) |

IFileSource 类型

interface IFileSource {
  url?: string;           // 文件 URL
  content?: Blob | File;  // 文件流 (优先级低于 url)
  name?: string;          // 文件名
  type?: string;          // 文件类型 (docx, pdf, xlsx, etc.)
}

支持格式

| 类型 | 实现方案 | 备注 | | --- | --- | --- | | PDF | @vue-office/pdf | 支持缩放、分页 | | Word | @vue-office/docx | 支持 .docx 格式 | | Excel | @vue-office/excel | 支持 .xlsx 格式 | | PPT | @vue-office/pptx | 支持 .pptx 格式 | | 图片 | 原生 <img> | jpg, png, svg, gif, webp | | 视频 | 原生 <video> | mp4, webm, ogv | | 音频 | 原生 <audio> | mp3, wav, ogg | | 文本 | 原生 <pre> | txt, json, md, code |

许可证

MIT