zwplayervue3

基于 Vue 3.x 的 zwplayer 组件封装，提供简单易用的视频播放能力。

关于 zwplayer

zwplayer（Zero Web Player）是一款秉持"智能傻瓜式"设计理念的网页播放器，致力于将开发者的使用成本降至无限接近于零。

核心特点

✅ 零费用成本 - 完全免费，永久免费，无需支付任何费用

✅ 零学习成本 - 提供统一简洁的 API，智能引擎自动处理所有流媒体技术细节

✅ 零升级成本 - API 永久固化，版本升级仅需替换文件

✅ 零风险成本 - 代码纯净，无广告、无统计、无联网后门

✅ 零部署成本 - 不依赖第三方库和 CDN，私网、内网均可使用

主要功能

• 广泛协议支持：HLS、DASH、HTTP-FLV、HTTP-TS、WS、WebRTC（WHEP/ARTC/BRTC/TRTC）
• 特色协议：支持 RTSP 网页播放（无需插件）
• 本地文件播放：支持直接播放用户设备上的本地视频/音频文件
• 智能字幕：支持双字幕、字幕搜索、章节搜索、拖拽加载本地字幕、章节文件
• 丰富功能：弹幕、进度条预览、画面调节、截图、音量增益、AB循环、录制、音频提取等
• 直播优化：超低延时直播、直播追帧、多码流切换
• 灵活模式：画中画、网页全屏、自动小窗口、强制锁定模式

更多详情请访问：

• zwplayer 官网
• 在线体验
• Vue 框架集成指南

使用说明

安装

npm install zwplayervue3 --save

安装注意事项

⚠️ 重要：本组件依赖 zwplayer 核心库，安装时请注意以下事项：

1. 自动配置：npm install 会自动执行 postinstall 脚本，该脚本会：

   • 创建 public 目录（如果不存在）
   • 将 zwplayer 核心库复制到 public/zwplayer 目录

2. 核心库必须发布：public/zwplayer 目录必须随项目一起发布到生产环境

   • 确保该目录完整包含所有 zwplayer 相关文件
   • 不要在部署时忽略此目录

3. 动态加载机制：zwplayer 采用动态加载机制

   • 支持无缝升级，无需修改业务代码
   • 升级时只需替换 public/zwplayer 目录中的文件即可

4. 内网/私网部署：zwplayer 不依赖 CDN，完全支持内网和离线环境部署

组件注册

全局注册

在 src/main.js 中添加：

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

createApp(App)
  .use(ZwModule)
  .mount('#app')

全局注册后，可在项目任何组件中使用 <zwplayer> 组件。

局部注册

在组件中单独注册：

import { zwplayer } from 'zwplayervue3'

export default {
  name: 'MyComponent',
  components: {
    zwplayer   //局部注册组件
  },
  data() {
    return {
      movieUrl: 'https://d2zihajmogu5jn.cloudfront.net/elephantsdream/ed_hd.mp4',
      playerOpen: true
    }
  },
  props: {
    msg: String
  },
  methods: {
    onPlayerReady() {
      console.log('player ready event.')
    },
    onPlayerMediaEvent(event) {
      console.log('media event:', event.type)
    },
    sendDanmu(danmu) {
      console.log('sendDanmu:', danmu)
      // 调用websocket等方法将弹幕实际发送出去
    }
  }
}

组件使用

基础使用示例

在模板中使用组件：

<template>
  <div class="player-container">
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      nodeid="main-player"
      :murl="movieUrl"
      @onready="onPlayerReady"
      @onmediaevent="onPlayerMediaEvent"
      :snapshotButton="true"
      :optionButton="true"
      :infoButton="true"
      :enableDanmu="true"
      :chapterButton="true"
      :disableMutedConfirm="true"
      danmuBar="danmu-controlbar"
    />
  </div>
</template>

带缩略图的示例

<template>
  <div class="player-container">
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      nodeid="main-player"
      :murl="movieUrl"
      :thumbnails="thumbnails"
      :fluid="true"
      :autoplay="false"
      @onready="onPlayerReady"
    />
  </div>
</template>

<script>
import { zwplayer } from 'zwplayervue3'

export default {
  name: 'ThumbnailExample',
  components: {
    zwplayer
  },
  data() {
    return {
      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
      playerOpen: true,
      thumbnails: {
        url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
        width: 160,
        height: 90,
        row: 9,
        col: 9,
        total: 74
      }
    }
  },
  methods: {
    onPlayerReady() {
      console.log('播放器已就绪')
    }
  }
}
</script>

弹幕功能示例

<template>
  <div>
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      :murl="movieUrl"
      :enableDanmu="true"
      :sendDanmu="sendDanmu"
      :disableMutedConfirm="true"
      @onready="onPlayerReady"
    />

    <!-- 弹幕控制条容器 -->
    <div class="danmubar" id="danmu-controlbar"></div>
  </div>
</template>

<script>
import { zwplayer } from 'zwplayervue3'

export default {
  name: 'DanmuExample',
  components: {
    zwplayer
  },
  data() {
    return {
      movieUrl: 'https://cdn.zwplayer.cn/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
      playerOpen: true,
      player: null
    }
  },
  methods: {
    onPlayerReady() {
      // 获取播放器实例
      this.player = this.$refs.zwplayerRef

      // 添加测试弹幕
      if (this.player && this.player.appendDanmu) {
        const testDanmu = {
          border: '1px solid #ccc',
          text: '欢迎来到 zwplayer 弹幕演示！',
          color: '#ff6b6b'
        }
        this.player.appendDanmu(testDanmu)
      }
    },
    sendDanmu(danmuText) {
      console.log('发送弹幕:', danmuText)

      if (!danmuText) return

      // 解析弹幕数据
      let danmu
      try {
        const jtext = JSON.parse(danmuText)
        danmu = {
          border: '1px solid #ccc',
          text: jtext['text']
        }
      } catch (e) {
        danmu = {
          border: '1px solid #ccc',
          text: danmuText
        }
      }

      // 添加弹幕到播放器
      if (this.player && this.player.appendDanmu) {
        this.player.appendDanmu(danmu)
      }
    }
  }
}
</script>

<style scoped>
.danmubar {
  height: 50px;
  background-color: #232323;
  padding: 8px;
  box-sizing: border-box;
}

/* 弹幕控制条宽度设置 */
.danmubar :deep(.zwp_danmu-controlbar) {
  width: 60%;
}
</style>

主要属性说明

| 属性名称 | 说明 | 备注 | |---------|------|------| | murl | 媒体地址参数（string/object/array），支持动态切换 | 运行时变动会自动调用 play 方法 | | autoplay | 是否自动播放 | true/false | | fluid | 是否启用流体布局，使播放器自适应容器宽度 | true/false | | thumbnails | 缩略图配置对象 | 参见下方缩略图配置 | | enableDanmu | 是否启用弹幕功能 | true/false | | sendDanmu | 发送弹幕的回调函数 | function | | snapshotButton | 是否显示截图按钮 | true/false | | optionButton | 是否显示设置按钮 | true/false | | infoButton | 是否显示信息按钮 | true/false | | chapterButton | 是否显示章节按钮 | true/false | | disableMutedConfirm | 禁用静音确认提示 | true/false | | 其它 | 请参考 zwplayer 播放器构造函数参数 | - |

缩略图配置示例

thumbnails: {
  url: 'https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
  width: 160,    // 单个缩略图宽度
  height: 90,    // 单个缩略图高度
  row: 9,        // 缩略图行数
  col: 9,        // 缩略图列数
  total: 74      // 缩略图总数
}

事件

组件提供了 onready、onmediaevent 等事件，详细说明请参考 zwplayer 事件文档。

| 事件名称 | 说明 | 回调参数 | |---------|------|---------| | onready | 播放器初始化完成 | - | | onmediaevent | 媒体事件 | event 对象，包含 type 等属性 |

方法调用

通过 ref 引用调用播放器方法：

// 在 onready 事件中获取播放器实例
methods: {
  onPlayerReady() {
    // 获取播放器实例
    const player = this.$refs.zwplayerRef
    this.player = player
  },

  // 播放控制
  playVideo() {
    this.player.play()
  },

  pauseVideo() {
    this.player.pause()
  },

  // 跳转到指定时间（秒）
  seekTo(time) {
    this.player.seekTime(time)
  },

  // 添加弹幕
  addDanmu(text, color = '#fff') {
    if (this.player && this.player.appendDanmu) {
      const danmu = {
        border: '1px solid #ccc',
        text: text,
        color: color
      }
      this.player.appendDanmu(danmu)
    }
  },

  // 切换视频源
  changeVideo(newUrl) {
    this.movieUrl = newUrl  // 通过修改 murl 属性自动切换
  }
}

常用方法列表

| 方法名 | 说明 | 示例 | |-------|------|-----------------------------------------------------| | play() | 播放视频 | player.play() | | pause() | 暂停视频 | player.pause() | | seekTime(time) | 跳转到指定时间（秒） | player.seekTime(120) | | appendDanmu(danmu) | 添加弹幕 | player.appendDanmu({text: '弹幕内容', color: '#fff'}) | | 其他方法 | 请参考 zwplayer API 文档 | - |

示例项目

完整示例项目包含了以下演示场景：

• 基础使用 - 播放器基本功能演示

• 缩略图预览 - 进度条缩略图功能

• 弹幕功能 - 实时弹幕发送和接收

• 自动播放 - 自动播放配置

• 截图功能 - 视频截图功能

• 字幕功能 - 多字幕支持

• 章节功能 - 视频章节导航

• Logo 设置 - 自定义播放器 Logo

• 播放控制 - 自定义播放控制

• 小窗口模式 - 画中画等功能

• 流体布局 - 自适应容器宽度

• Gitee: https://gitee.com/chenfanyu/zwplayervue3-demo

• GitHub: https://github.com/chenfanyu/zwplayervue3-demo

常见问题

1. 播放器实例未定义？

确保在 onready 事件中获取播放器实例：

onPlayerReady() {
  this.player = this.$refs.zwplayerRef
}

2. 如何实现视频源动态切换？

直接修改 murl 绑定的变量即可：

this.movieUrl = 'https://example.com/new-video.mp4'

组件会自动调用 play 方法加载新视频源。

3. public/zwplayer 目录的作用？

该目录包含 zwplayer 核心库文件，采用动态加载机制：

• 支持无缝升级，无需重新编译项目
• 必须随项目一起发布到生产环境
• 可以随时替换升级，不影响业务代码

其他版本

Vue 2.x

如果你使用 Vue 2.x，请安装 zwplayer-vue2x：

npm install zwplayer-vue2x --save

详细文档：zwplayer-vue2x

相关资源

官方文档

• ZWPlayer 官网
• 在线体验
• Vue 框架集成指南
• 配置参数文档
• API 方法文档
• 事件文档

示例项目

• Vue 3 示例 (Gitee)
• Vue 3 示例 (GitHub)
• Vue 2 示例 (Gitee)
• Vue 2 示例 (GitHub)

许可证

本组件遵循 MIT 许可证。ZWPlayer 核心库完全免费使用。

技术支持

如有问题或建议，请通过以下方式联系：

• 邮箱：[email protected]
• QQ：893366640
• 微信：zwplayerX
• 公众号：zwplayer