Vue3 Media Previewer

一个 Vue 3 媒体文件预览组件，支持图片、视频、音频预览，具备缩放、旋转、拖拽等交互功能。

特性

• 🖼️ 图片预览 - 支持缩放、旋转、拖拽、下载
• 🎬 视频预览 - 原生 HTML5 视频播放器
• 🎵 音频预览 - 自定义音频播放器，带可视化效果
• 📄 不支持文件 - 为不支持的格式提供下载选项
• 🎨 可定制 - 使用 CSS 变量自定义主题
• 🎯 多种使用方式 - 组件、指令或 JS 函数调用
• ⌨️ 键盘支持 - ESC 关闭，方向键切换

安装

npm install vue3-media-previewer
# 或
yarn add vue3-media-previewer
# 或
pnpm add vue3-media-previewer

使用方法

1. 组件方式

<template>
  <div>
    <button @click="openPreview">预览图片</button>
    <MediaPreviewer
      ref="previewerRef"
      :url-list="urls"
      :file-name-list="names"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { MediaPreviewer } from 'vue3-media-previewer'

const previewerRef = ref(null)
const urls = ref(['https://example.com/image.jpg'])
const names = ref(['我的图片.jpg'])

const openPreview = () => {
  previewerRef.value?.open(0)
}
</script>

2. 指令方式

// main.js
import { createApp } from 'vue'
import { vMediaPreview } from 'vue3-media-previewer'
import App from './App.vue'

const app = createApp(App)
app.directive('media-preview', vMediaPreview)
app.mount('#app')

<template>
  <!-- 单个文件，仅传 URL -->
  <img v-media-preview="'https://example.com/image.jpg'" :src="..." />

  <!-- 单个文件，带自定义文件名 -->
  <img v-media-preview="{ urls: 'https://example.com/abc123', names: '报告.pdf' }" :src="..." />

  <!-- 多个文件 -->
  <img v-media-preview="{ urls: imageList, names: nameList, index: 0 }" :src="..." />

  <!-- 可用于任意元素 -->
  <button v-media-preview="{ urls: videoUrl, names: '视频.mp4' }">预览视频</button>
</template>

3. JS 函数调用

<script setup>
import {
  useMediaPreview,
  previewMediaFile,
  previewMediaFiles
} from 'vue3-media-previewer'

// 方式 A：在 setup 中使用
const mediaPreview = useMediaPreview()

// 预览单个文件
mediaPreview.previewFile('https://example.com/image.jpg')
mediaPreview.previewFile('https://example.com/abc123', '报告.pdf')

// 预览多个文件
mediaPreview.previewFiles(['url1', 'url2'], 0)
mediaPreview.previewFiles(['url1', 'url2'], ['文件名1', '文件名2'], 0)

// 使用 openPreview 方法（推荐）
mediaPreview.openPreview({
  urlList: ['https://example.com/1.jpg', 'https://example.com/2.jpg'],
  fileNameList: ['图片 1.jpg', '图片 2.jpg']
}, 0)

// 方式 B：全局方法（无需在 setup 中初始化）
previewMediaFile('https://example.com/video.mp4')
previewMediaFile('https://example.com/abc123', '文档.pdf')
previewMediaFiles(['url1', 'url2'], 0)
previewMediaFiles(['url1', 'url2'], ['文件名1', '文件名2'], 0)
</script>

支持的文件类型

图片

• jpg, jpeg, png, gif, webp, bmp, svg, ico

视频

• mp4, avi, mov, wmv, flv, webm, mkv, m4v, 3gp

音频

• mp3, wav, ogg, m4a, aac, flac, wma

自定义样式

使用 CSS 变量自定义预览器外观：

:root {
  /* 遮罩层背景 */
  --preview-overlay-bg: rgba(0, 0, 0, 0.65);

  /* 按钮背景 */
  --preview-btn-bg: rgba(0, 0, 0, 0.4);
  --preview-btn-hover-bg: rgba(0, 0, 0, 0.6);

  /* 主题色（蓝色系） */
  --preview-primary-color: #409eff;
  --preview-primary-light: #66b1ff;
  --preview-primary-gradient: linear-gradient(135deg, #409eff, #66b1ff);
  --preview-primary-gradient-horizontal: linear-gradient(90deg, #409eff, #66b1ff);
}

API

MediaPreviewer 属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | urlList | string[] | [] | 要预览的文件 URL 列表 | | fileNameList | string[] | [] | 自定义文件名列表（可选） |

MediaPreviewer 方法

| 方法 | 参数 | 说明 | |------|------|------| | open | (index?: number) | 在指定索引处打开预览 | | close | () | 关闭预览 |

useMediaPreview

| 方法 | 参数 | 说明 | |------|------|------| | openPreview | (options, initialIndex?) | 使用 options 对象打开预览 | | previewFile | (url, fileName?) | 预览单个文件 | | previewFiles | (urlList, fileNameList?, initialIndex?) | 预览多个文件 | | closePreview | () | 关闭预览 |

全局方法

| 方法 | 参数 | 说明 | |------|------|------| | previewMediaFile | (url, fileName?) | 全局预览单个文件 | | previewMediaFiles | (urlList, fileNameList?, initialIndex?) | 全局预览多个文件 |

键盘快捷键

• ESC - 关闭预览
• ← - 上一个文件
• → - 下一个文件

图片控制

• 放大/缩小 - 鼠标滚轮或工具栏按钮
• 拖拽 - 点击并拖动（放大时）
• 旋转 - 左/右旋转按钮
• 1:1 - 恢复原始尺寸
• 适应屏幕 - 适应屏幕大小
• 下载 - 下载当前图片

许可证

MIT