Vue框架使用说明

ZWPlayer 提供了针对 Vue 框架的专用接口包，支持 Vue 2.x 和 Vue 3.x 版本。

1. Vue 3.x

1.1 安装步骤

1. 安装 Vue 接口包

可以通过如下命令安装 zwplayer 的 vue3.x 接口包：

npm i zwplayervue3 --save

2. 验证安装

安装成功后，项目的 public 目录下会自动生成 zwplayer 核心库目录，该目录必须随项目一起构建发布。

3. 版本要求

• Vue 3.x
• 支持 Vite 和 Webpack 构建工具

1.2 组件注册

zwplayervue3 支持两种组件注册方式：局部注册和全局注册。实际项目中推荐使用局部注册方式。

局部注册（推荐）

在需要使用的组件中导入并注册：

import { zwplayer } from 'zwplayervue3'

export default {
  name: 'zwplayer-demo',
  components: {
    zwplayer  // 局部注册组件
  },
  data() {
    return {
      movieUrl: 'https://cdn.zwplayer.com/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
      playerOpen: true,
      player: null
    };
  },
  methods: {
    onPlayerReady() {
      console.log('player ready event.');
      // 获取播放器实例
      this.player = this.$refs.zwplayerRef;
    },
    onPlayerMediaEvent(event) {
      console.log('media event:', event.type);
    },
    sendDanmu(danmuText) {
      console.log('sendDanmu:', danmuText);
      // 调用websocket等方法将弹幕实际发送出去
    }
  }
}

优点：

• 按需加载，减少不必要的代码
• 组件依赖关系更清晰
• 便于代码维护和重构
• 更好的 TypeScript 支持

全局注册（可选）

如果需要在多个组件中使用，可以在 main.js 或 main.ts 文件中进行全局注册：

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

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

以上代码导入 zwplayer 模块，并调用 Vue 3 的 use 方法实现全局注册。全局注册后，播放器组件可在项目任何子组件中使用，无需再单独引入。

支持的组件标签名：

• zwplayer （推荐）
• zero-web-player
• zero-player
• ZPlayer

注意：本示例项目采用的是局部注册方式。

使用 Composition API（Vue 3.2+）

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

const movieUrl = ref('https://cdn.zwplayer.com/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4')
const playerOpen = ref(true)
const zwplayerRef = ref(null)

const onPlayerReady = () => {
  console.log('player ready event.')
  // 获取播放器实例
  console.log('播放器实例:', zwplayerRef.value)
}

const onPlayerMediaEvent = (event) => {
  console.log('media event:', event.type)
}
</script>

1.3 组件使用

基本使用示例

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

弹幕功能示例

<template>
  <div class="demo">
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      :murl="movieUrl"
      @onready="onPlayerReady"
      @onmediaevent="onPlayerMediaEvent"
      :autoplay="false"
      :sendDanmu="sendDanmu"
      :enableDanmu="true"
      danmuBarId="danmu-controlbar"
      :disableMutedConfirm="true"
    />

    <div class="danmubar" id="danmu-controlbar"></div>
  </div>
</template>

<script>
export default {
  methods: {
    sendDanmu(danmuText) {
      if (!danmuText) return;

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

      // 添加弹幕到播放器
      const player = this.$refs.zwplayerRef;
      if (player && player.appendDanmu) {
        player.appendDanmu(danmu);
      }
    }
  }
}
</script>

<style scoped>
/* 弹幕控制条样式穿透 */
.danmubar :deep(.zwp_danmu-controlbar) {
  width: 60%;
}
</style>

Logo 水印示例

<template>
  <zwplayer
    ref="zwplayerRef"
    :murl="movieUrl"
    :logo="logo"
    :poster="poster"
    :autoplay="false"
    :disableMutedConfirm="true"
  />
</template>

<script>
export default {
  data() {
    return {
      logo: {
        icon: 'https://cdn.zwplayer.com/logo.png',
        dock: 'right',      // 位置：left, right
        x: '5%',            // 水平偏移
        y: '5%',            // 垂直偏移
        width: '10%',       // 宽度
        height: '10%',      // 高度
        opacity: 70         // 透明度 0-100
      },
      poster: 'https://www.zwplayer.com/zwplayer-preview.png'
    };
  }
}
</script>

缩略图示例

<template>
  <zwplayer
    ref="zwplayerRef"
    :murl="movieUrl"
    :thumbnails="thumbnails"
    :fluid="true"
  />
</template>

<script>
export default {
  data() {
    return {
      thumbnails: {
        url: 'https://cdn.zwplayer.com/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg',
        width: 160,
        height: 90,
        row: 9,
        col: 9,
        total: 74
      }
    };
  }
}
</script>

章节分段示例

<template>
  <zwplayer
    ref="zwplayerRef"
    :murl="movieUrl"
    :chapterButton="true"
    @onready="onPlayerReady"
  />
</template>

<script>
export default {
  methods: {
    onPlayerReady() {
      const player = this.$refs.zwplayerRef;

      const chapters = [{
          title: "分段1",
          desc: "分段1描述",
          time: 0,
          duration: 50,
          thumb: null
        },
        {
          title: "分段2",
          desc: "分段2描述",
          time: 50,
          duration: 100,
          style: {
            background: "blue"
          },
          image: null
        },
        {
          title: "分段3",
          desc: "分段3描述",
          time: 100,
          duration: 200,
          style: {
            background: "green"
          },
          image: null
        }
      ];

      player.setChapters(chapters);
    }
  }
}
</script>

1.4 变动属性

zwplayervue3 标签的属性与原生 zwplayer 构造函数参数对象的属性大部分相同，但 zwplayervue3 对部分属性做了调整：

常用属性说明

显示控制相关：

• autoplay: 是否自动播放（boolean，默认 false）
• fluid: 是否启用流体布局（boolean，默认 false）
• snapshotButton: 是否显示截图按钮（boolean）
• optionButton: 是否显示选项按钮（boolean）
• infoButton: 是否显示信息按钮（boolean）
• chapterButton: 是否显示章节菜单按钮（boolean），不影响章节数据的加载和进度条标记
• enableDanmu: 是否启用弹幕功能（boolean）

媒体相关：

• murl: 媒体地址（string、object 或 array）
• poster: 封面图地址（string）
• thumbnails: 缩略图配置（object）

功能相关：

• sendDanmu: 弹幕发送回调函数（function）
• disableMutedConfirm: 是否禁用静音确认（boolean）
• keepAudioWindow: 是否保持音频窗口（boolean）
• localPlayback: 是否本地播放（boolean）
• recordButton: 是否显示录制按钮（boolean）
• segmentButton: 是否显示分段按钮（boolean）

1.5 事件

zwplayervue3 组件提供了以下事件：

详细事件说明请参见事件说明文档。

事件使用示例

<template>
  <zwplayer
    ref="zwplayerRef"
    :murl="movieUrl"
    @onready="onPlayerReady"
    @onmediaevent="onPlayerMediaEvent"
  />
</template>

<script>
export default {
  methods: {
    onPlayerReady() {
      console.log('播放器已就绪');
      const player = this.$refs.zwplayerRef;
      // 可以在这里调用播放器方法
    },
    onPlayerMediaEvent(event) {
      console.log('媒体事件:', event.type);
      // 常见的 event.type: play, pause, ended, timeupdate 等
    }
  }
}
</script>

1.6 方法调用

zwplayer 的 Vue 组件提供了与原生 zwplayer 一样的方法。要调用这些方法，请通过 Vue 的 ref 属性获取组件引用。

获取播放器实例

// 方式1：在 onready 事件中获取
onPlayerReady() {
  const player = this.$refs.zwplayerRef;
  console.log('播放器实例:', player);
}

// 方式2：直接获取
const player = this.$refs.zwplayerRef;

常用方法示例

// 播放/暂停
player.play();
player.pause();

// 跳转到指定时间（秒）
player.seekTo(30);

// 设置音量（0-100）
player.setVolume(50);

// 添加弹幕
player.appendDanmu({
  border: '1px solid #ccc',
  text: '这是一条弹幕',
  color: '#ff6b6b'
});

// 设置章节
player.setChapters([{
  title: "分段1",
  desc: "分段1描述",
  time: 0,
  duration: 50
}]);

// 获取当前播放时间
const currentTime = player.currentTime();

// 获取视频总时长
const duration = player.duration();

2. Vue 2.x

2.1 安装步骤

1. 安装 Vue 接口包

可以通过如下命令安装 zwplayer 的 vue2.x 接口包：

npm i zwplayer-vue2x --save

或者从本地 tgz 包安装：

npm install ./zwplayer-vue2x-1.0.32.tgz --save

2. 验证安装

安装成功后，项目的 public 目录下会自动生成 zwplayer 核心库目录，该目录必须随项目一起构建发布。

3. 版本要求

• Vue 2.6+
• 支持 Vue CLI 4.x/5.x

2.2 与 Vue 3 的主要差异

Vue 2.x 版本在使用上与 Vue 3.x 版本基本一致，主要差异在于：

注意：组件属性、事件和方法调用方式完全相同。

2.3 组件注册与使用

局部注册（推荐）

import { zwplayer } from 'zwplayer-vue2x'

export default {
  name: 'zwplayer-demo',
  components: {
    zwplayer  // 局部注册组件
  },
  data() {
    return {
      movieUrl: 'https://cdn.zwplayer.com/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
      playerOpen: true,
      player: null
    };
  },
  methods: {
    onPlayerReady() {
      console.log('player ready event.');
      this.player = this.$refs.zwplayerRef;
    },
    onPlayerMediaEvent(event) {
      console.log('media event:', event.type);
    }
  }
}

2.5 样式穿透

Vue 2.x 中使用 /deep/ 或 ::v-deep 进行样式穿透：

/* 方式1：使用 /deep/ */
.danmubar /deep/ .zwp_danmu-controlbar {
  width: 60%;
}

/* 方式2：使用 ::v-deep */
.danmubar ::v-deep .zwp_danmu-controlbar {
  width: 60%;
}

2.5 完整示例

<template>
  <div class="demo-page">
    <zwplayer
      v-if="playerOpen"
      ref="zwplayerRef"
      :murl="movieUrl"
      @onready="onPlayerReady"
      @onmediaevent="onPlayerMediaEvent"
      :autoplay="false"
      :snapshotButton="true"
      :optionButton="true"
      :infoButton="true"
      :enableDanmu="true"
      :chapterButton="true"
      :disableMutedConfirm="true"
      :fluid="true"
      danmuBar="danmu-controlbar"
    />
  </div>
</template>

<script>
import { zwplayer } from 'zwplayer-vue2x'

export default {
  name: 'zw-basic',
  components: {
    zwplayer
  },
  data() {
    return {
      movieUrl: 'https://cdn.zwplayer.com/media/VMAP9lxJvRpgn5sP3lV6rQ9qkzQmh5psggso3185.mp4',
      playerOpen: true
    };
  },
  methods: {
    onPlayerReady() {
      console.log('player ready event.');
      const player = this.$refs.zwplayerRef;
      // 调用播放器方法
    },
    onPlayerMediaEvent(event) {
      console.log('media event:', event.type);
    }
  }
}
</script>

<style scoped>
.danmubar /deep/ .zwp_danmu-controlbar {
  width: 60%;
}
</style>

2.6 组件属性和方法

Vue 2.x 版本的组件属性、事件和方法与 Vue 3.x 版本完全一致，详见上述 Vue 3.x 的相关说明：

• 组件属性：参见 1.4 变动属性
• 事件说明：参见 1.5 事件
• 方法调用：参见 1.6 方法调用
• 更多示例：参见 1.3 组件使用 中的各个示例

3. 示例仓库

3.1 Vue 3.x 示例

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

3.2 Vue 2.x 示例

• Gitee: https://gitee.com/chenfanyu/zwplayer-vue2x-demo
• GitHub: https://github.com/chenfanyu/zwplayer-vue2x-demo

4. 注意事项

4.1 项目配置

1. 目录结构: 安装前确保项目存在 public 目录
2. 核心库: public/zwplayer 目录必须随项目一起发布
3. 动态加载: zwplayer 采用动态加载机制，支持无缝升级，不会被打包进最终的 bundle
4. 方法调用: 通过 ref 引用调用播放器方法

4.2 最佳实践

1. 使用 v-if 控制显示

   <zwplayer v-if="playerOpen" ref="zwplayerRef" :murl="movieUrl" />

   使用 v-if 而不是 v-show，可以确保播放器正确初始化和销毁。

2. 等待播放器就绪后再调用方法

   onPlayerReady() {
     const player = this.$refs.zwplayerRef;
     // 播放器就绪后才能调用方法
     player.play();
   }

3. 样式穿透

   当需要修改播放器内部样式时，需要使用样式穿透：

   Vue 3.x：

   /* 在 scoped 样式中修改弹幕控制条宽度 */
   .danmubar :deep(.zwp_danmu-controlbar) {
     width: 60%;
   }

   Vue 2.x：

   /* 使用 /deep/ 或 ::v-deep */
   .danmubar /deep/ .zwp_danmu-controlbar {
     width: 60%;
   }
   
   /* 或 */
   .danmubar ::v-deep .zwp_danmu-controlbar {
     width: 60%;
   }

4. 响应式布局

   .player-container {
     width: 100%;
     max-width: 1280px;
     margin: 0 auto;
   }
   
   @media (max-width: 768px) {
     .player-container {
       width: 100%;
       height: auto;
       aspect-ratio: 16/9;
     }
   }

4.3 常见问题

Q: 为什么播放器无法显示？

A: 检查以下几点：

1. 确保使用了 v-if 而不是 v-show
2. 确保媒体 URL 可访问
3. 检查浏览器控制台是否有错误信息
4. 确认 public/zwplayer 目录存在且包含必需的文件

Q: 如何动态切换视频？

A: 直接修改 murl 属性的值，组件会自动重新加载：

this.movieUrl = 'new-video-url.mp4';

Q: 弹幕控制条样式如何自定义？

A: 使用 CSS 样式穿透。

Vue 3.x：

.danmubar :deep(.zwp_danmu-controlbar) {
  width: 60%;
  background-color: #232323;
}

Vue 2.x：

.danmubar /deep/ .zwp_danmu-controlbar {
  width: 60%;
  background-color: #232323;
}

Q: 如何获取播放器的当前状态？

A: 通过 ref 获取播放器实例后调用相应方法：

const player = this.$refs.zwplayerRef;
const currentTime = player.currentTime();
const duration = player.duration();
const isPlaying = player.isPlaying();  // 如果有此方法

4.4 项目结构建议

Vue 3.x 项目结构（Vite）：

your-vue3-project/
├── public/
│   └── zwplayer/           # 播放器核心库（自动生成，必须发布）
├── src/
│   ├── components/
│   │   └── Player.vue      # 播放器封装组件
│   ├── views/
│   │   └── VideoPage.vue   # 使用播放器的页面
│   ├── App.vue
│   └── main.js
├── package.json
└── vite.config.js

Vue 2.x 项目结构（Vue CLI）：

your-vue2-project/
├── public/
│   └── zwplayer/           # 播放器核心库（自动生成，必须发布）
├── src/
│   ├── components/
│   │   └── Player.vue      # 播放器封装组件
│   ├── views/
│   │   └── VideoPage.vue   # 使用播放器的页面
│   ├── App.vue
│   └── main.js
├── package.json
└── vue.config.js

4.5 调试建议

1. 开启开发模式日志

   onPlayerReady() {
     console.log('播放器已就绪:', this.$refs.zwplayerRef);
   }

2. 监听所有媒体事件

   onPlayerMediaEvent(event) {
     console.log('媒体事件:', event.type, event);
   }

3. 使用浏览器开发者工具

   • 检查网络请求，确认 zwplayer.js 正确加载
   • 查看控制台是否有错误信息
   • 使用元素检查器查看 DOM 结构

4.6 性能优化

1. 延迟加载: 对于非首屏的播放器，使用 v-if 延迟加载
2. 销毁实例: 组件销毁时确保播放器实例也被正确清理
3. 资源预加载: 对于关键视频，可以考虑预加载
4. CDN 加速: 将 zwplayer 核心库部署到 CDN，使用 zwplayerlib 属性指定

5. 更新日志

Vue 3.x (zwplayervue3)

• v1.0.33: 优化 Vue 3 兼容性，支持 Composition API
• v1.0.30: 新增缩略图、章节、弹幕等功能
• v1.0.20: 初始版本，支持基本播放功能

Vue 2.x (zwplayer-vue2x)

• v1.0.32: 优化 Vue 2 兼容性，修复已知问题
• v1.0.30: 新增缩略图、章节、弹幕等功能
• v1.0.20: 初始版本，支持基本播放功能

6. 相关链接

• ZWPlayer 官方文档
• Vue 3 官方文档
• Vue 2 官方文档
• Vue 3 示例代码
• Vue 2 示例代码