vue-video-plus

bagn # 🎬vuevideoplus

一个基于 Vue 3 开发的功能丰富、高度可定制的现代化视频播放器组件

📮 联系作者

有任何疑问可以给我发邮件或者加 QQ

📧 邮箱: [e-mail]
💬 QQ: 250219234

✨ 特性

• 🎨 主题定制 - 支持纯色/渐变主题，可自定义播放器颜色
• 📱 响应式设计 - 完美适配桌面端和移动端
• 🎯 丰富功能 - 倍速播放、画中画、全屏、关灯模式等
• 🎬 清晰度切换 - 支持多清晰度无缝切换，自动记忆用户偏好
• ⌨️ 快捷键支持 - 空格播放/暂停、方向键快进快退、音量调节
• 🔄 自动播放策略 - 智能处理浏览器自动播放限制
• 💾 状态持久化 - 自动保存音量、倍速、清晰度等设置，刷新页面也能记住
• 🎭 镜像画面 - 支持视频镜像翻转
• 🔊 音量记忆 - 自动记住用户音量设置
• 🎬 循环播放 - 支持视频循环播放
• 💡 关灯模式 - 沉浸式观看体验
• 🎪 多种动画 - 播放按钮支持多种切换动画效果
• 🛠️ TypeScript - 完整的类型定义支持

📦 安装

npm

npm install vue-video-plus

pnpm

pnpm add vue-video-plus

yarn

yarn add vue-video-plus

🚀 快速开始

全局注册

import { createApp } from 'vue'
import App from './App.vue'

// 引入组件和样式
import VueVideoPlus from 'vue-video-plus'
import 'vue-video-plus/dist/style.css'

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

组件内使用

<template>
  <VueVideoPlus
   
    @play="handlePlay"
    @pause="handlePause"
  />
</template>

<script setup>
import { reactive } from 'vue'
import { VueVideoPlus } from 'vue-video-plus'
import 'vue-video-plus/dist/style.css'

const options = reactive({
  width: '1080px',
  height: '608px',
  // 在线视频
  src: 'https://example.com/video.mp4',
  // 或使用本地视频（需放在 public 文件夹）
  // src: '/videos/demo.mp4',
  autoPlay: false,
  muted: false,
  volume: 0.5,

})

const handlePlay = (event) => {
  console.log('视频开始播放', event)
}

const handlePause = (event) => {
  console.log('视频暂停', event)
}
</script>

💡 提示：将视频文件放在项目根目录的 public/videos/ 文件夹中，然后使用 /videos/your-video.mp4 路径引用。

📖 配置项

基础配置

参数	说明	类型	默认值
src	视频源地址	String	演示视频 URL
width	播放器宽度（桌面端）	String	'1080px'
height	播放器高度（桌面端）	String	'608px'
title	视频标题	String	''
type	视频类型	String	'video/mp4'
poster	视频封面图	String	''
autoPlay	自动播放	Boolean	true
muted	静音	Boolean	true
volume	默认音量（0-1）	Number	0.3
loop	循环播放	Boolean	false
currentTime	初始播放时间（秒）	Number	0
control	是否显示控制器	Boolean	true
preload	预加载策略	String	'auto'

📹 视频源地址 (src) 详细说明

默认值：http://www.jplayer.org/video/m4v/Incredibles_Teaser.m4v（演示视频）

播放器支持多种视频源格式，你可以根据需要选择：

1️⃣ 使用在线视频（推荐用于生产环境）

<VueVideoPlus src="https://example.com/video.mp4" />

2️⃣ 使用本地视频文件

在项目根目录创建 public 文件夹（如果还没有），将视频文件放入：

your-project/
├── public/
│   └── videos/
│       └── demo.mp4
├── src/
└── package.json

然后使用相对路径引用：

<VueVideoPlus src="/videos/demo.mp4" />

3️⃣ 导入本地视频（适用于较小的视频）

<script setup>
import { VueVideoPlus } from 'vue-video-plus'
import myVideo from '@/assets/video.mp4'
</script>

<template>
  <VueVideoPlus :src="myVideo" />
</template>

4️⃣ 使用默认演示视频（快速测试）

<!-- 不指定 src，使用内置演示视频 -->
<VueVideoPlus />

⚠️ 注意事项：

• 支持的格式：MP4、WebM、Ogg 等浏览器原生支持的格式
• HLS（.m3u8）需要配合 hls.js 使用（见下方 FAQ）
• 建议使用 public 文件夹存放视频，避免打包体积过大
• 跨域视频需要服务器配置 CORS

主题配置

参数	说明	类型	默认值
colorStart	主题起始颜色	String	'#52a0fd'
colorEnd	主题结束颜色（空字符串为纯色，否则渐变）	String	'#00e2fa'
borderRadius	播放器圆角	String	'8px'

主题示例：

// 纯色主题
{ colorStart: '#52a0fd', colorEnd: '' }

// 渐变主题
{ colorStart: '#52a0fd', colorEnd: '#00e2fa' }

功能配置

参数	说明	类型	默认值
speed	是否支持快进快退	Boolean	true
speedRate	倍速选项	Array	['2.0', '1.5', '1.25', '1.0', '0.75', '0.5']
qualities	清晰度选项列表	Array<QualityOption>	[]
mirror	镜像画面	Boolean	false
lightOff	关灯模式	Boolean	false
webFullScreen	网页全屏	Boolean	false
playsinline	iOS 内联播放（不全屏）	Boolean	false

🎬 清晰度配置 (qualities)

类型定义：

interface QualityOption {
  label: string      // 显示标签，如 "1080P"
  value: string      // 清晰度标识，如 "1080p"
  url: string        // 对应的视频源地址
  default?: boolean  // 是否为默认清晰度
}

使用示例：

<VueVideoPlus
  src="/video-1080p.mp4"
  :qualities="[
    {
      label: '超清 1080P',
      value: '1080p',
      url: '/video-1080p.mp4',
      default: true
    },
    {
      label: '高清 720P',
      value: '720p',
      url: '/video-720p.mp4'
    },
    {
      label: '标清 480P',
      value: '480p',
      url: '/video-480p.mp4'
    }
  ]"
/>

注意事项：

• 空数组 [] 表示不启用清晰度切换功能
• 建议提供 3-5 个清晰度选项
• 切换清晰度时会保持播放位置和播放状态
• 用户选择的清晰度会自动保存（需启用 storage.fields.quality）

📖 详细文档： 清晰度切换配置指南

UI 配置

参数	说明	类型	默认值
playBtnPosition	中央播放按钮位置	String	'center'
playBtnAnimation	播放按钮切换动画	String	'scale'
controlBtns	显示的控制按钮	Array	见下方说明

playBtnPosition 可选值：

• 'center' - 居中
• 'bottom-right' - 右下角
• 'bottom-left' - 左下角

playBtnAnimation 可选值：

• 'rotate' - 旋转
• 'scale' - 缩放
• 'flip' - 翻转
• 'slide' - 滑动
• 'none' - 无动画

controlBtns 默认值：

[
  'audioTrack',      // 音轨（预留）
  'quality',         // 清晰度（预留）
  'speedRate',       // 倍速
  'volume',          // 音量
  'setting',         // 设置
  'pip',            // 画中画
  'pageFullScreen', // 网页全屏
  'fullScreen'      // 全屏
]

高级配置

参数	说明	类型	默认值
playRetryTimeout	播放重试超时时间（毫秒）	Number	500

💾 状态持久化配置

播放器支持自动保存用户设置到本地存储（localStorage），刷新页面后自动恢复。

参数	说明	类型	默认值
storage	持久化配置对象	Object	见下方说明
videoId	视频唯一标识（用于区分不同视频的播放位置）	String	''

storage 配置项：

storage: {
  enabled: true,              // 是否启用持久化
  prefix: 'vue-video-player', // localStorage key 前缀
  
  // 要持久化的字段
  fields: {
    volume: true,           // ✅ 音量（强烈推荐）
    playbackRate: true,     // ✅ 播放速度（强烈推荐）
    muted: true,           // ✅ 静音状态（推荐）
    quality: true,         // ✅ 清晰度偏好（推荐）
    currentTime: false     // ⚖️ 播放位置（默认关闭，可按需开启）
  },
  
  // 播放位置保存配置（仅当 fields.currentTime=true 时生效）
  currentTimeConfig: {
    enabled: false,        // 是否启用播放位置保存
    minDuration: 300,      // 最小保存时长（秒），视频<5分钟不保存
    minProgress: 0.05,     // 最小保存进度（5%），避免保存刚开始的视频
    maxProgress: 0.95      // 最大保存进度（95%），避免保存已完成的视频
  },
  
  // 过期时间配置
  expiration: {
    global: 0,                              // 全局设置过期时间（毫秒），0=永不过期
    currentTime: 30 * 24 * 60 * 60 * 1000  // 播放位置过期时间（30天）
  }
}

使用示例：

<template>
  <VueVideoPlus
    src="/video.mp4"
    videoId="my-video-001"
    :storage="{
      enabled: true,
      prefix: 'my-app-video',
      fields: {
        volume: true,
        playbackRate: true,
        currentTime: true  // 启用断点续播
      },
      currentTimeConfig: {
        enabled: true,
        minDuration: 300
      }
    }"
  />
</template>

💡 使用场景：

• 默认配置（推荐）：自动保存音量、倍速、静音状态
• 启用断点续播：适合长视频、课程、电影等场景，设置 fields.currentTime: true
• 禁用持久化：设置 storage: { enabled: false }

📖 详细文档：

持久化功能配置较为复杂，详细说明请查看：状态持久化配置指南

🎮 事件

原生视频事件

组件支持所有原生 HTML5 视频事件：

事件名	说明	回调参数
loadstart	开始加载视频	Event
play	开始播放	Event
pause	暂停播放	Event
playing	播放中	Event
seeking	开始跳转	Event
seeked	跳转完成	Event
canplay	可以播放	Event
waiting	缓冲中	Event
durationchange	时长变化	Event
progress	下载进度	Event
timeupdate	播放进度更新	Event
ended	播放结束	Event
error	播放错误	Event
stalled	数据获取失败	Event

自定义事件

事件名	说明	回调参数
mirrorChange	镜像状态改变	(isMirror: Boolean, video: HTMLVideoElement)
loopChange	循环状态改变	(isLoop: Boolean, video: HTMLVideoElement)
lightOffChange	关灯模式改变	(isLightOff: Boolean, video: HTMLVideoElement)

使用示例：

<template>
  <VueVideoPlus
    v-bind="options"
    @play="handlePlay"
    @pause="handlePause"
    @timeupdate="handleTimeUpdate"
    @ended="handleEnded"
    @mirrorChange="handleMirrorChange"
    @loopChange="handleLoopChange"
  />
</template>

<script setup>
const handlePlay = (event) => {
  console.log('播放开始', event)
}

const handlePause = (event) => {
  console.log('播放暂停', event)
}

const handleTimeUpdate = (event) => {
  const currentTime = event.target.currentTime
  console.log('当前播放时间:', currentTime)
}

const handleEnded = (event) => {
  console.log('播放结束', event)
}

const handleMirrorChange = (isMirror, video) => {
  console.log('镜像模式:', isMirror, video)
}

const handleLoopChange = (isLoop, video) => {
  console.log('循环播放:', isLoop, video)
}
</script>

🎯 方法

通过 ref 可以调用播放器实例的方法：

方法名	说明	参数
play()	播放视频	-
pause()	暂停视频	-
togglePlay()	切换播放/暂停	-

使用示例：

<template>
  <VueVideoPlus ref="videoRef" v-bind="options" />
  <button @click="handlePlay">播放</button>
  <button @click="handlePause">暂停</button>
  <button @click="handleToggle">切换</button>
</template>

<script setup>
import { ref } from 'vue'

const videoRef = ref(null)

const handlePlay = () => {
  videoRef.value?.play()
}

const handlePause = () => {
  videoRef.value?.pause()
}

const handleToggle = () => {
  videoRef.value?.togglePlay()
}
</script>

⌨️ 快捷键

播放器支持以下键盘快捷键（仅桌面端）：

快捷键	功能
空格	播放/暂停
←	快退 10 秒
→	快进 10 秒
→ 长按	5 倍速播放
↑	增加音量
↓	减少音量
F	全屏/退出全屏
ESC	退出网页全屏

💡 完整示例

<template>
  <div class="video-container">
    <VueVideoPlus
      ref="videoPlayer"
      v-bind="options"
      @play="onPlay"
      @pause="onPause"
      @timeupdate="onTimeUpdate"
      @ended="onEnded"
      @mirrorChange="onMirrorChange"
      @loopChange="onLoopChange"
      @lightOffChange="onLightOffChange"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue'
import { VueVideoPlus } from 'vue-video-plus'
import 'vue-video-plus/dist/style.css'

const videoPlayer = ref()

const options = reactive({
  // 基础配置
  width: '1080px',
  height: '608px',
  src: 'https://example.com/video.mp4',
  title: '精彩视频',
  type: 'video/mp4',
  poster: 'https://example.com/poster.jpg',
  
  // 主题配置
  colorStart: '#52a0fd',
  colorEnd: '#00e2fa',
  borderRadius: '8px',
  
  // 播放配置
  autoPlay: true,
  muted: false,
  volume: 0.5,
  loop: false,
  currentTime: 0,
  
  // 功能配置
  speed: true,
  speedRate: ['2.0', '1.5', '1.25', '1.0', '0.75', '0.5'],
  mirror: false,
  lightOff: false,
  webFullScreen: false,
  
  // UI 配置
  playBtnPosition: 'center',
  playBtnAnimation: 'scale',
  control: true,
  controlBtns: [
    'speedRate',
    'volume',
    'setting',
    'pip',
    'pageFullScreen',
    'fullScreen'
  ],
  
  // 持久化配置
  storage: {
    enabled: true,
    prefix: 'my-video-app',
    fields: {
      volume: true,
      playbackRate: true,
      muted: true,
      currentTime: false
    }
  },
  
  // 高级配置
  playRetryTimeout: 500
})

// 事件处理
const onPlay = (event: Event) => {
  console.log('视频开始播放', event)
}

const onPause = (event: Event) => {
  console.log('视频暂停', event)
}

const onTimeUpdate = (event: Event) => {
  const video = event.target as HTMLVideoElement
  console.log('播放进度:', video.currentTime, '/', video.duration)
}

const onEnded = (event: Event) => {
  console.log('视频播放结束', event)
}

const onMirrorChange = (isMirror: boolean, video: HTMLVideoElement) => {
  console.log('镜像模式:', isMirror)
}

const onLoopChange = (isLoop: boolean, video: HTMLVideoElement) => {
  console.log('循环播放:', isLoop)
}

const onLightOffChange = (isLightOff: boolean, video: HTMLVideoElement) => {
  console.log('关灯模式:', isLightOff)
}

// 控制方法
const playVideo = () => {
  videoPlayer.value?.play()
}

const pauseVideo = () => {
  videoPlayer.value?.pause()
}

const togglePlayVideo = () => {
  videoPlayer.value?.togglePlay()
}
</script>

<style scoped>
.video-container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 20px;
}

/* 移动端适配 */
@media (max-width: 768px) {
  .video-container {
    padding: 10px;
  }
}
</style>

🎨 主题示例

纯色主题

// 经典蓝
{ colorStart: '#52a0fd', colorEnd: '' }

// 玫瑰红
{ colorStart: '#eb3b5a', colorEnd: '' }

// 薄荷绿
{ colorStart: '#00b894', colorEnd: '' }

渐变主题

// 科技蓝（默认）
{ colorStart: '#52a0fd', colorEnd: '#00e2fa' }

// 日落橙
{ colorStart: '#ff6b6b', colorEnd: '#ffa500' }

// 炫彩紫
{ colorStart: '#667eea', colorEnd: '#764ba2' }

// 海洋蓝
{ colorStart: '#4b7bec', colorEnd: '#3867d6' }

📱 移动端适配

播放器自动检测设备类型并适配：

• 桌面端：使用配置的 width 和 height
• 移动端：自动设置为 100% 宽度，高度按 16:9 比例计算
• 触摸支持：移动端使用原生控制器
• 响应式：窗口大小变化时自动调整

🔧 常见问题

1. 视频无法自动播放？

浏览器的自动播放策略要求首次自动播放必须静音。播放器已内置处理：

• 首次自动播放会先静音
• 用户交互后自动恢复音量
• 或者设置 autoPlay: false 让用户手动播放

2. 拖动进度条时音量闪烁？

这个问题已在 v1.2.4 版本修复，确保使用最新版本。

3. 如何支持 HLS（m3u8）视频？

播放器支持浏览器原生支持的 HLS 格式（Safari），其他浏览器需要使用 hls.js：

import Hls from 'hls.js'

if (Hls.isSupported()) {
  const hls = new Hls()
  hls.loadSource('https://example.com/video.m3u8')
  hls.attachMedia(videoElement)
}

4. 如何自定义控制器样式？

使用深度选择器覆盖样式：

:deep(.player-wrap) {
  /* 自定义样式 */
}

:deep(.control-tool) {
  background: rgba(0, 0, 0, 0.8);
}

5. 如何启用断点续播功能？

设置 storage.fields.currentTime: true 并配置 currentTimeConfig：

<VueVideoPlus
  src="/movie.mp4"
  videoId="movie-001"
  :storage="{
    fields: {
      currentTime: true
    },
    currentTimeConfig: {
      enabled: true,
      minDuration: 300,    // 只保存5分钟以上的视频
      minProgress: 0.05,   // 进度>5%才保存
      maxProgress: 0.95    // 进度<95%才保存
    }
  }"
/>

注意：记得设置 videoId 来区分不同视频的播放位置。

6. 为什么刷新后音量/倍速没有保存？

确保持久化功能已启用（默认启用）：

storage: {
  enabled: true,  // 确保为 true
  fields: {
    volume: true,       // 保存音量
    playbackRate: true  // 保存倍速
  }
}

如果仍然不生效，检查浏览器是否禁用了 localStorage。

7. 如何清除已保存的播放数据？

打开浏览器开发者工具（F12）：

• 进入 Application → Local Storage
• 找到 vue-video-player-settings 键（或你自定义的 prefix）
• 右键删除

或在代码中清除：

localStorage.removeItem('vue-video-player-settings')

📄 License

MIT License

👨‍💻 作者

鱿鱼溪学院

🤝 贡献

欢迎提交 Issue 和 Pull Request！

如果这个项目对你有帮助，欢迎 ⭐ Star 支持一下！