# vueVideo++

**Repository Path**: wlscs/vue-video

## Basic Information

- **Project Name**: vueVideo++
- **Description**: 一个基于 Vue 3 开发的功能丰富、高度可定制的现代化视频播放器组件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 21
- **Forks**: 4
- **Created**: 2024-10-27
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: vue-extensions

**Tags**: None

## README

# 🎬vuevideoplus

<div align="center">

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

[![npm version](https://img.shields.io/npm/v/vue-video-plus.svg)](https://www.npmjs.com/package/vue-video-plus)
[![license](https://img.shields.io/npm/l/vue-video-plus.svg)](https://github.com/yourusername/vue-video-plus/blob/master/LICENSE)
[![downloads](https://img.shields.io/npm/dm/vue-video-plus.svg)](https://www.npmjs.com/package/vue-video-plus)

---

### 📮 联系作者

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

📧 **邮箱**: 250219234@qq.com  
💬 **QQ**: 250219234

---

</div>


## ✨ 特性

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

## 📦 安装

### npm

```bash
npm install vue-video-plus
```

### pnpm

```bash
pnpm add vue-video-plus
```

### yarn

```bash
yarn add vue-video-plus
```

## 🚀 快速开始

### 全局注册

```javascript
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')
```

### 组件内使用

```vue
<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️⃣ 使用在线视频（推荐用于生产环境）**
```vue
<VueVideoPlus src="https://example.com/video.mp4" />
```

**2️⃣ 使用本地视频文件**

在项目根目录创建 `public` 文件夹（如果还没有），将视频文件放入：
```
your-project/
├── public/
│   └── videos/
│       └── demo.mp4
├── src/
└── package.json
```

然后使用相对路径引用：
```vue
<VueVideoPlus src="/videos/demo.mp4" />
```

**3️⃣ 导入本地视频（适用于较小的视频）**
```vue
<script setup>
import { VueVideoPlus } from 'vue-video-plus'
import myVideo from '@/assets/video.mp4'
</script>

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

**4️⃣ 使用默认演示视频（快速测试）**
```vue
<!-- 不指定 src，使用内置演示视频 -->
<VueVideoPlus />
```

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

### 主题配置

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

**主题示例：**

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

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

### 功能配置

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

### UI 配置

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

**playBtnPosition 可选值：**
- `'center'` - 居中
- `'bottom-right'` - 右下角
- `'bottom-left'` - 左下角

**playBtnAnimation 可选值：**
- `'rotate'` - 旋转
- `'scale'` - 缩放
- `'flip'` - 翻转
- `'slide'` - 滑动
- `'none'` - 无动画

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

### 高级配置

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

## 🎮 事件

### 原生视频事件

组件支持所有原生 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)` |

**使用示例：**

```vue
<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()` | 切换播放/暂停 | - |

**使用示例：**

```vue
<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` | 退出网页全屏 |

## 💡 完整示例

```vue
<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'
  ],
  
  // 高级配置
  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>
```

## 🎨 主题示例

### 纯色主题

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

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

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

### 渐变主题

```javascript
// 科技蓝（默认）
{ 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：

```javascript
import Hls from 'hls.js'

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

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

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

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

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

## 📄 License

MIT License

## 👨‍💻 作者

**鱿鱼溪学院**

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

<div align="center">
如果这个项目对你有帮助，欢迎 ⭐ Star 支持一下！
</div>