vue-video-plus 1.2.3 → 1.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 鱿鱼溪学院
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,52 +1,545 @@
-# vueVideo++
-
-使用 Vue3 构建的多功能视频播放器
-
-## 安装
-
-npm 安装
-
-```javascript
-npm i vue-video-plus
-```
-
-pnpm 安装
-
-```javascript
-pnpm i vue-video-plus
-```
-
-yarn 安装
-
-```javascript
-yarn add  vue-video-plus
-```
-
-## 开始使用
-
-#### 全局使用
-
-```javascript
-import { createApp } from 'vue'
-import App from './App.vue'
-let app = createApp(App)
-
-import vueVideoPlus from 'vue-video-plus' // 引入组件
-import 'vue-video-plus/dist/style.css' // 引入css
-app.use(vueVideoPlus)
-
-app.mount('#app')
-```
-
-#### 组件内使用
-
-```javascript
-// 引入样式
-import 'vue-video-plus/dist/style.css'
-import { videoPlay } from 'vue-video-plus'
-export default {
-  components: {
-    videoPlay
-  }
-}
-```
+# 🎬 Vue Video Plus
+
+<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)
+
+</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
+    v-bind="options"
+    @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: '800px',
+  height: '450px',
+  src: 'https://example.com/video.mp4',
+  title: '示例视频',
+  autoPlay: false,
+  muted: false,
+  volume: 0.5
+})
+
+const handlePlay = (event) => {
+  console.log('视频开始播放', event)
+}
+
+const handlePause = (event) => {
+  console.log('视频暂停', event)
+}
+</script>
+```
+
+## 📖 配置项
+
+### 基础配置
+
+| 参数 | 说明 | 类型 | 默认值 |
+|-----|------|------|--------|
+| `src` | 视频源地址（必填） | `String` | - |
+| `width` | 播放器宽度（桌面端） | `String` | `'800px'` |
+| `height` | 播放器高度（桌面端） | `String` | `'450px'` |
+| `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'` |
+
+### 主题配置
+
+| 参数 | 说明 | 类型 | 默认值 |
+|-----|------|------|--------|
+| `colorStart` | 主题起始颜色 | `String` | `'#52a0fd'` |
+| `colorEnd` | 主题结束颜色（空字符串为纯色，否则渐变） | `String` | `'#00e2fa'` |
+| `borderRadius` | 播放器圆角 | `String` | `'0px'` |
+
+**主题示例：**
+
+```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>