wq-video-player

原生JS视频播放器，支持mp4、m3u8格式，水印、试看、防录屏、键盘快捷键等功能

功能特性

• ✅ 支持 MP4 和 HLS (m3u8) 视频格式
• ✅ 自适应亮色/暗色主题
• ✅ 自定义播放器宽高
• ✅ 试看时长限制
• ✅ 浮动水印功能
• ✅ 防录屏功能
• ✅ Blob地址加密
• ✅ 播放速度调节（0.5x - 2x）
• ✅ 音量调节/静音控制
• ✅ 画中画模式
• ✅ 全屏播放
• ✅ 进度条拖拽/拖拽跳转
• ✅ 进度条hover时间提示
• ✅ 键盘快捷键支持
• ✅ 自动隐藏控制条
• ✅ 国际化支持
• ✅ 自定义进度条/音量条颜色
• ✅ 控制按钮显隐配置

安装

npm install wq-video-player

说明：播放 HLS(m3u8) 格式视频依赖 hls.js，已包含在依赖中，npm 会自动安装，无需额外操作。只播放 MP4 同样可以正常使用。

快速使用

ES Module 方式

import WQVideoPlayer from 'wq-video-player'

const player = new WQVideoPlayer('#player-container', {
  url: 'https://example.com/video.mp4',
  width: '800px',
  height: '450px'
})

CDN 方式

<div id="player-container"></div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/hls.min.js"></script>
<script src="https://unpkg.com/wq-video-player"></script>
<script>
const player = new WQVideoPlayer('#player-container', {
  url: 'https://example.com/video.mp4'
})
</script>

CommonJS 方式

var WQVideoPlayer = require('wq-video-player')

var player = new WQVideoPlayer('#player-container', {
  url: 'https://example.com/video.mp4'
})

在 Vue/React 等框架中使用（播放 HLS/m3u8）

从 v1.0.6 开始，已自动适配 ES 模块默认导出来的 hls.js，可以直接使用，无需手动传入 Hls 实例：

<template>
  <div ref="playerContainer"></div>
</template>

<script>
import WQVideoPlayer from 'wq-video-player'

export default {
  mounted() {
    this.player = new WQVideoPlayer(this.$refs.playerContainer, {
      url: 'https://example.com/stream.m3u8',
      width: '100%',
      height: '400px'
    })
  },
  beforeUnmount() {
    this.player && this.player.destroy()
  }
}
</script>

如果遇到兼容性问题，依然可以手动传入 Hls 实例：

Vue 示例

<template>
  <div ref="playerContainer"></div>
</template>

<script>
import Hls from 'hls.js'
import WQVideoPlayer from 'wq-video-player'

export default {
  mounted() {
    // 方式1: 全局设置 Hls 实例
    WQVideoPlayer.setHls(Hls)

    this.player = new WQVideoPlayer(this.$refs.playerContainer, {
      url: 'https://example.com/stream.m3u8',
      width: '100%',
      height: '400px'
    })
  },
  beforeUnmount() {
    this.player && this.player.destroy()
  }
}
</script>

方式2: 在构造参数中传入 Hls

const player = new WQVideoPlayer(container, {
  url: 'https://example.com/stream.m3u8',
  Hls: Hls // 直接传入导入的Hls
})

React 示例

import React, { useEffect, useRef } from 'react'
import Hls from 'hls.js'
import WQVideoPlayer from 'wq-video-player'

function VideoPlayer({ url }) {
  const containerRef = useRef(null)
  const playerRef = useRef(null)

  useEffect(() => {
    WQVideoPlayer.setHls(Hls)
    playerRef.current = new WQVideoPlayer(containerRef.current, {
      url: url,
      width: '100%',
      height: '400px'
    })
    return () => {
      playerRef.current && playerRef.current.destroy()
    }
  }, [url])

  return <div ref={containerRef} />
}

export default VideoPlayer

核心代码已完全兼容 ES5 标准，支持 UMD 模块格式，可以在各类旧版本打包工具和浏览器环境中直接使用。

配置选项

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | url | string | - | 视频地址，支持mp4和m3u8 | | width | string | '100%' | 播放器宽度 | | height | string | 'auto' | 播放器高度 | | previewSeconds | number | 0 | 试看时长（秒），0表示不限制 | | watermarkText | string | '' | 水印文本 | | enableAntiRecord | boolean | false | 是否启用防录屏 | | enableBlobEncrypt | boolean | true | 是否启用Blob地址加密 | | showPurchaseButton | boolean | false | 试看结束是否显示购买按钮 | | purchaseButtonText | string | '' | 购买按钮文字 | | language | string | 'auto' | 界面语言，支持'auto'(自动检测)、'zh-CN'(中文)、'en-US'(英文) | | showVolumeControl | boolean | true | 是否显示音量控制按钮 | | showSpeedButton | boolean | true | 是否显示倍速调节按钮 | | showPipButton | boolean | true | 是否显示画中画按钮 | | showFullscreenButton | boolean | true | 是否显示全屏按钮 | | progressFillColor | string | '#3b82f6' | 进度条填充颜色 | | progressHandleColor | string | '#ffffff' | 进度条拖动按钮颜色 | | volumeFillColor | string | '#3b82f6' | 音量条填充颜色 | | volumeHandleColor | string | '#ffffff' | 音量条拖动按钮颜色 | | i18n | object | 中文 | 国际化文本配置 | | onTimeUpdate | function | - | 时间更新回调 | | onPlay | function | - | 播放回调 | | onPause | function | - | 暂停回调 | | onEnded | function | - | 播放结束回调 | | onPreviewEnded | function | - | 试看结束回调 |

国际化配置

默认中文文本：

i18n: {
  'video.play': '播放',
  'video.pause': '暂停',
  'video.unmute': '取消静音',
  'video.mute': '静音',
  'video.playbackSpeed': '播放速度: {speed}x',
  'video.pictureInPicture': '画中画',
  'video.exitFullscreen': '退出全屏',
  'video.fullscreen': '全屏',
  'video.previewEnded': '试看结束',
  'video.previewDescription': '您已观看{seconds}秒试看内容',
  'video.purchaseFullContent': '购买完整内容'
}

方法API

play()

播放视频

player.play()

pause()

暂停视频

player.pause()

seek(time)

跳转到指定时间（秒）

player.seek(30) // 跳转到30秒位置

setVolume(volume)

设置音量，范围0-1

player.setVolume(0.5) // 50%音量

setSpeed(speed)

设置播放速度，支持0.5, 0.75, 1, 1.25, 1.5, 2

player.setSpeed(1.5) // 1.5倍速

fullscreen(enable)

切换全屏

player.fullscreen() // 切换全屏
player.fullscreen(true) // 进入全屏
player.fullscreen(false) // 退出全屏

updateUrl(url)

更新视频地址

player.updateUrl('https://example.com/new-video.mp4')

destroy()

销毁播放器

player.destroy()

键盘快捷键

| 快捷键 | 功能 | |--------|------| | 空格 | 播放/暂停 | | M | 静音/取消静音 | | F | 全屏/退出全屏 | | ← | 快退5秒 | | → | 快进5秒 | | ↑ | 音量+10% | | ↓ | 音量-10% | | 0-9 | 跳转到对应百分比进度 |

事件监听

可以通过两种方式监听事件：

1. 配置回调函数

const player = new WQVideoPlayer('#player-container', {
  url: 'video.mp4',
  onPlay: () => {
    console.log('视频开始播放')
  },
  onTimeUpdate: (currentTime) => {
    console.log('当前播放时间:', currentTime)
  }
})

2. 事件监听

player.playerContainer.addEventListener('play', () => {
  console.log('视频开始播放')
})

player.playerContainer.addEventListener('timeUpdate', (e) => {
  console.log('当前播放时间:', e.detail[0])
})

支持的事件：

• timeUpdate - 时间更新，参数：currentTime
• play - 播放
• pause - 暂停
• ended - 播放结束
• previewEnded - 试看结束

示例

基础示例

<!DOCTYPE html>
<html>
<head>
  <title>视频播放器示例</title>
</head>
<body>
  <div id="player" style="width: 800px; margin: 50px auto;"></div>

  <script type="module">
    import WQVideoPlayer from './index.js'

    const player = new WQVideoPlayer('#player', {
      url: 'https://www.w3schools.com/html/mov_bbb.mp4',
      width: '100%',
      height: '450px',
      watermarkText: '内部使用',
      previewSeconds: 60, // 试看60秒
      showPurchaseButton: true,
      onPreviewEnded: () => {
        alert('试看结束，请购买完整内容')
      }
    })
  </script>
</body>
</html>

m3u8 示例

const player = new WQVideoPlayer('#player', {
  url: 'https://example.com/stream.m3u8',
  width: '100%',
  enableAntiRecord: true
})

自定义颜色和按钮配置示例

const player = new WQVideoPlayer('#player', {
  url: 'video.mp4',
  width: '100%',
  height: '500px',
  // 自定义颜色
  progressFillColor: '#10b981', // 绿色进度条
  progressHandleColor: '#ffffff',
  volumeFillColor: '#10b981',
  volumeHandleColor: '#ffffff',
  // 隐藏不需要的按钮
  showSpeedButton: false,
  showPipButton: false,
  // 英文界面
  language: 'en-US'
})

模块兼容性

• ✅ ES6+ Module (import/export)
• ✅ ES5 UMD (CommonJS/AMD/全局变量)
• ✅ CDN 直接引用

浏览器兼容性

核心代码兼容 ES5，支持：

• Chrome 50+
• Firefox 45+
• Safari 9+
• Edge 12+
• IE 11 (需要 HLS 不支持，MP4 可正常工作)

注：HLS(m3u8) 播放需要 hls.js，hls.js 最低支持 Chrome 50+

更新日志

v1.0.7 (2026-03-18)

• 🐛 修复 Vue 环境中音量条样式显示异常和拖拽失效问题
• 🔧 重构音量条为和进度条一致的 DOM 结构，彻底解决兼容性问题
• ✨ 保持点击、拖拽交互体验，和进度条行为统一
• 🐛 修复静音后拖动音量条无法恢复声音的 bug
• 🔧 调整音量控件与倍速按钮之间间距

v1.0.6 (2026-03-18)

• 🐛 修复 Vue/webpack 环境中 Hls is not a constructor 报错
• 🔧 正确处理 hls.js ES模块默认导出，现在无需手动传入即可在 Vue/React 中正常使用
• ✨ 增强自动导入兼容性，同时支持 CommonJS 和 ES 模块导出格式

v1.0.5 (2026-03-18)

• 🔧 完整 ES5 语法改造，兼容更广泛的打包工具和浏览器环境
• ✨ 改进 HLS 引入方式，支持在 Vue/React 等模块化项目中手动传入 Hls 实例
• 📝 添加 Vue/React 使用文档

v1.0.3 (2026-03-18)

• 🔧 hls.js 移回 dependencies，确保 npm 6 及所有版本都能自动安装
• 📝 更新文档说明

v1.0.2

• 🔧 将 hls.js 移至 peerDependencies，作为可选依赖
• 📝 完善文档添加 HLS 安装说明

v1.0.1

• ✨ 新增自定义进度条/音量条颜色配置
• 🐛 修复进度条圆形按钮裁切问题
• 🎨 优化进度条拖拽鼠标样式

v1.0.0

• 🎉 初始版本发布
• 支持 MP4/HLS 播放、水印、试看、防录屏等功能

License

MIT