leonz-vue3-file-preview

一个基于 Vue 3 的多格式文件预览插件，支持音频、视频、图片、3D 模型、Office 文档、Markdown、JSON、DXF、KML 等常见文件格式的在线预览。

特性

• 音频：mp3、wav、ogg、aac、flac
• 视频：mp4、webm、ogg
• 图片：jpg、jpeg、png、gif、webp、svg
• 3D 模型：obj、glb、stl（依赖 @google/model-viewer、babylonjs）
• Office：docx、xlsx、pptx、doc、xls、ppt（支持 OnlyOffice 或微软在线预览）
• Markdown：md（依赖 mavon-editor，未安装时降级为纯文本）
• JSON：json（语法高亮格式化显示）
• 纯文本：txt 及其他文本类型
• DXF：dxf（依赖 dxf-viewer + three）
• KML：kml（依赖 cesium）

安装

npm install leonz-vue3-file-preview

可选依赖

根据实际预览需求，按需安装以下依赖：

# 3D 模型预览（GLB / OBJ / STL）
npm install @google/model-viewer babylonjs babylonjs-loaders

# Markdown 预览
npm install mavon-editor

# DXF 预览
npm install dxf-viewer three

# KML 预览
npm install cesium

# 视频播放器增强（如需要 video.js 皮肤）
npm install @videojs-player/vue video.js

# JSON 增强查看器
npm install vue-json-viewer

使用方式

全局注册

import { createApp } from 'vue'
import Vue3FilePreview from 'leonz-vue3-file-preview'
import App from './App.vue'

const app = createApp(App)

app.use(Vue3FilePreview, {
  cesiumToken: '你的-cesium-token',          // KML 预览必填
  officeViewUrl: 'https://your-office-viewer.com', // Office 在线预览地址（可选）
  dxfFontUrl: '/fonts/simfang.ttf',          // DXF 字体路径（可选）
})

app.mount('#app')

局部注册

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

<template>
  <FilePreview
    file-url="https://example.com/document.docx"
    file-name="document.docx"
    @finished="onPreviewFinished"
  />
</template>

Props

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | fileUrl | string | 是 | 文件的访问地址 | | fileName | string | 否 | 文件名（用于未提供 mimeType 时推断文件类型） | | mimeType | string | 否 | 文件的 MIME 类型 | | options | FilePreviewOptions | 否 | 预览配置项（优先级高于全局配置） |

事件

| 事件 | 说明 | |------|------| | finished | 文件加载/预览完成时触发 | | error | 预览失败时触发 |

配置项

interface FilePreviewOptions {
  cesiumToken?: string      // Cesium Ion Token，用于 KML 预览
  officeViewUrl?: string    // 自定义 Office 文档在线预览服务地址
  dxfFontUrl?: string       // DXF 预览使用的字体文件地址
}

文件类型识别

插件按以下优先级自动识别文件类型：

1. 传入的 mimeType prop
2. 从 fileName 或 fileUrl 中提取的文件扩展名

也可手动调用工具函数进行识别：

import { detectFileType, getPreviewType, getMimeTypeByExtension } from 'leonz-vue3-file-preview'

const { mimeType, previewType } = detectFileType('https://example.com/file.pdf')

各格式预览说明

Office 文档

提供两种预览方案：

1. 微软 Office Online（默认）：自动跳转至微软免费在线预览服务
2. OnlyOffice：在 index.html 中引入 OnlyOffice API 脚本，并配置 officeViewUrl

<script src="https://your-onlyoffice-server/web-apps/apps/api/documents/api.js"></script>

3D 模型

• GLB 格式使用 @google/model-viewer（基于 Web Component，现代浏览器原生支持）
• OBJ / STL 格式使用 babylonjs（Canvas 渲染）

OBJ 模型加载时，需确保材质和贴图与模型文件位于同一目录下，且路径结构符合 Babylon.js 加载器要求。

DXF 预览

依赖 dxf-viewer 与 three，未安装时会提示用户安装命令。支持图层切换、自动缩放、颜色校正等功能。

KML 预览

依赖 cesium，需配置有效的 cesiumToken。

CORS 说明

大部分预览器要求文件地址支持跨域访问。请确保文件服务器已配置 Access-Control-Allow-Origin 响应头，否则可能导致加载失败。

类型声明

插件内置完整的 TypeScript 类型声明，无需额外安装 @types 包。

许可证

MIT