最近接了个Vue3项目要做课程视频播放模块。一开始我拿原生video标签凑合结果倍速、清晰度切换、键盘快捷键、自定义控制条这些功能写完UI丑得自己都嫌弃。后来换成xgplayer半天就把这块捋顺了。网上关于Vue3集成xgplayer的资料挺多但大多停留在怎么安装包、怎么new一个Player真正把使用步骤和demo细节讲透的很少。这篇就把我在实际项目里跑通过的完整流程、封装思路、踩坑记录都整理出来想在Vue3项目里快速接入播放器的朋友可以直接参考。1. 选型前的自我拷问为什么我放弃了原生video和video.js先交代一下项目背景视频资源有普通mp4和m3u8直播流转码要求支持倍速、高清/标清切换、截图、键盘空格暂停/方向键进退。这些需求如果全部用原生video写意味着我要自己造一套控制栏UI、自己管理全屏API差异、自己处理HLS的MediaSource扩展。说实话不是不能写但周期至少一周起步而且后续维护成本极高。当时对比过两个方案video.js和xgplayer。video.js是老牌播放器插件生态齐全但它默认皮肤的样式确实有点过时而且API风格偏传统在Vue3组件化场景下感觉有点隔阂。xgplayer是字节跳动开源的那款底层还是基于HTML5 video但把UI、事件、控制逻辑都封装好了默认皮肤清爽配置项设计也更贴近现代前端的使用习惯。做个精简对比维度原生videovideo.jsxgplayer控制栏UI自己写内置但样式偏老内置可高度自定义倍速控制自己写原生支持原生支持配置简单HLS支持需要MSE处理插件机制官方插件弹幕/清晰度无第三方插件内置或扩展插件Vue3友好度一般一般无框架依赖直接操作DOM实践中我的结论是如果只是放一个裸视频那原生video足够但项目一旦有交互要求直接上xgplayer能省下大量造轮子的时间。v2版本的xgplayer对Vue3没有特殊适配问题因为它本质上是纯JS库通过传入DOM元素初始化不依赖框架生命周期这对组件化使用非常友好。2. 环境准备与依赖安装先让播放器在开发环境里跑起来2.1 安装核心包和样式用Vite创建的Vue3项目Vue3.4 Vite5里安装命令很简单npm install xgplayer如果用到HLS直播流还需要单独装插件npm install xgplayer-hls.js样式文件需要手动引入。这里有个容易忽略的点只引入JS不引入CSS播放器会以裸video形态出现控制条全乱。正确姿势是同时引入核心样式import xgplayer/dist/index.min.css如果要用到hls插件插件的样式一般会自动包含在核心包里不需要额外引。但版本不匹配时可能出现样式缺失遇到这种情况检查下核心包和插件包版本是否搭。2.2 最小可用demo在组件里直接new播放器先把最朴素的版本跑通。创建一个Vue单文件组件模板里放一个div容器在onMounted里实例化Player。注意xgplayer的初始化必须绑定到已渲染的真实DOM上所以onMounted是安全时机template div refplayerContainer/div /template script setup import { ref, onMounted } from vue import Player from xgplayer import xgplayer/dist/index.min.css const playerContainer ref(null) let player null onMounted(() { player new Player({ el: playerContainer.value, url: https://example.com/video.mp4, width: 100%, height: 360, autoplay: false, videoInit: true }) }) /script这样就实现了最基础的能放视频。监听播放状态后续可以通过player.on(play, () {})来感知。2.3 版本坑提醒这里提个实测遇到的坑xgplayer核心版本和插件版本经常不是同步发布的。比如核心包升到2.x后如果直接把hls插件也升到最新可能出现插件内部引用路径不匹配导致播放器初始化报错。稳妥做法是核心包和插件包保持同一个大版本例如都是2.x的某个小版本测试通过后再锁定package.json里的具体版本号。npm的^符号会自动安装小版本最新所以建议用完直接固定版本避免过段时间重新install后行为漂移。3. 封装可复用组件给播放器加一层Vue3的外壳3.1 为什么要封装直接在业务页面上写new Player不是不行但如果多个页面都要播放视频每个页面复制一遍初始化代码后续要改全局配置比如加logo、水印、统一语言就得逐个页面改。封装成Vue组件后通过props传入视频地址和配置通过事件向父组件通信通过defineExpose暴露播放器实例这才是组件化开发的合理姿势。3.2 组件完整代码我封装了一个XgPlayer.vue支持url、poster、autoplay这几个常用prop同时监听url变化自动切换播放源在组件卸载前调用destroy释放资源。template div classxg-player-wrap refcontainerRef/div /template script setup import { ref, onMounted, onBeforeUnmount, watch, nextTick } from vue import Player from xgplayer import xgplayer/dist/index.min.css const props defineProps({ url: { type: String, required: true }, poster: { type: String, default: }, autoplay: { type: Boolean, default: false }, height: { type: Number, default: 360 } }) const emit defineEmits([ready, play, pause, ended, timeupdate, error]) const containerRef ref(null) let player null // 初始化播放器 const createPlayer async () { if (player) return await nextTick() if (!containerRef.value) return player new Player({ el: containerRef.value, url: props.url, poster: props.poster, autoplay: props.autoplay, width: 100%, height: props.height, playbackRate: [0.5, 0.75, 1, 1.25, 1.5, 2], keyShortcut: true, videoInit: true }) player.on(play, () emit(play)) player.on(pause, () emit(pause)) player.on(ended, () emit(ended)) player.on(timeupdate, () emit(timeupdate, player.currentTime)) player.on(error, (err) emit(error, err)) emit(ready, player) } // 监听url变化实现播放源切换 watch(() props.url, (newUrl) { if (player) { player.src newUrl if (props.autoplay) { player.play() } } }) onMounted(createPlayer) onBeforeUnmount(() { if (player) { player.destroy() player null } }) defineExpose({ player, getPlayer: () player }) /script几个细节说明一下await nextTick()很重要。如果父组件通过v-if异步渲染这个子组件很可能组件onMounted执行时DOM还没真正布局完成容器宽度为0xgplayer初始化会报警。加上nextTick能有效规避。player.src newUrl是切换播放源的直接方式不必重新new一个Player。实测切流很快不需要销毁重建。defineExpose里我既暴露了player字段也提供了getPlayer方法。这里有个Vue3的注意点defineExpose暴露的值在父组件拿到的是响应式包装后的版本直接调用播放器方法时建议用getPlayer()拿原始实例避免被proxy影响。3.3 父组件的使用方式父组件用法如下template XgPlayer :urlvideoUrl :posterposter :autoplayfalse readyhandleReady timeupdatehandleTimeupdate / /template script setup import XgPlayer from /components/XgPlayer.vue const handleReady (player) { console.log(player ready, player) // player.requestFullscreen() 等操作 } const handleTimeupdate (time) { console.log(当前播放时间, time) } /script这样父组件完全不感知xgplayer的内部实现只依赖子组件暴露的属性和事件后续更换其他播放器也不会影响业务代码逻辑。4. 事件监听与状态同步别把事件挂在全局4.1 xgplayer的事件模型xgplayer的事件机制和原生EventTarget类似核心方法就三个on、once、off。事件类型很丰富但实际用到最多的就这么几个事件名触发时机常用场景ready播放器初始化完成隐藏loadingplay开始播放埋点、切换UIpause暂停播放记忆播放进度ended播放结束推荐下一节timeupdate播放时间更新进度条刷新waiting缓冲等待显示loadingplaying缓冲结束后继续播放隐藏loadingerror播放异常错误提示fullscreenchange全屏状态切换同步按钮状态4.2 事件注册的时机和清理在封装组件里我习惯把事件注册集中放在初始化函数中而不是散落在各处。同时要留意如果组件的props.url变化导致重新加载不需要重新绑定事件因为播放器实例没变只是切换了src。但如果父组件通过v-if销毁并重建组件onBeforeUnmount里不仅要destroy()播放器还要确保没有遗留的事件引用。xgplayer的destroy()方法理论上会清理内部监听但如果你额外绑定过自定义事件到window或document比如全屏监听那就必须手动移除。这里贴一段我在真实项目中处理全屏事件的代码// 在创建播放器之后 this._handleFullscreenChange () { emit(fullscreenChange, player.isFullscreen) } document.addEventListener(fullscreenchange, this._handleFullscreenChange) // 在销毁之前 onBeforeUnmount(() { document.removeEventListener(fullscreenchange, this._handleFullscreenChange) player.destroy() })为什么要这样写因为xgplayer的全屏按钮触发的是浏览器全屏API它自己内部监听了fullscreenchange但如果外层业务需要感知全屏状态比如隐藏导航栏最好在外层也监听一份这时代理函数如果不用具名引用卸载时是移除不掉的。4.3 把播放器状态同步到Vue响应式数据还有一个常见需求页面某个地方显示当前播放时间/总时长。不要直接在timeupdate回调里给ref赋值因为timeupdate触发频率很高约250ms一次Vue响应式更新频繁会导致性能浪费。我在组件里是这么处理的let lastTime 0 const handleTimeupdate (time) { // 简单节流每500ms才更新一次响应式数据 if (time - lastTime 0.5) { currentTime.value time lastTime time } }更好的方案是在父组件里用纯事件方式拿时间并自行节流。组件内部的核心原则是高频事件向外抛可以但不要直接改响应式内部状态除非你有明确的节流机制。5. 实用配置项盘点倍速、画中画、懒加载与清晰度切换5.1 常用配置项速查表xgplayer的配置项繁多这里挑实际项目里用得最顺手的列成表格配置项类型默认值说明urlString无视频地址widthString/Number100%宽度支持百分比和像素heightString/Number300高度建议固定高度或按比例计算autoplayBooleanfalse自动播放。需要满足浏览器静音自动播放策略loopBooleanfalse循环播放volumeNumber0.7初始音量 0~1playbackRateArray[]倍速选项例如[0.5,0.75,1,1.25,1.5,2]keyShortcutBoolean/Stringfalse键盘快捷键可设normal或globalfitVideoSizeStringauto视频尺寸适配可设contain、coverdefinitionArray[]多清晰度列表langStringzh-cn语言controlsBooleantrue是否显示控制条5.2 倍速和快捷键的实战配置倍速配置很简单直接在初始化时传playbackRate数组new Player({ // ...省略 playbackRate: [0.5, 0.75, 1, 1.25, 1.5, 2] })播放器控制条上会自动出现倍速按钮点击选择对应倍速不需要额外代码。键盘快捷键默认是关闭的因为视频页面往往有其他交互比如空格滚动页面只在播放器内部聚焦时才应该响应。keyShortcut: normal可以让播放器容器内按空格暂停、按方向键快进快退实测体验很不错按Home键回到开头、按End键跳到结尾的映射也是内置的。5.3 懒加载进入视口才加载播放器课程列表页都放一个播放器性能肯定扛不住。我的习惯是使用IntersectionObserver当播放器容器进入可视区域时再创建实例。在Vue3组合式API中实现起来非常干净const containerRef ref(null) let observer null onMounted(() { observer new IntersectionObserver((entries) { entries.forEach((entry) { if (entry.isIntersecting !player) { createPlayer() observer.unobserve(entry.target) } }) }, { threshold: 0.1 }) if (containerRef.value) { observer.observe(containerRef.value) } }) onBeforeUnmount(() { if (observer) { observer.disconnect() } if (player) { player.destroy() } })这样页面初始加载时只渲染一个占位div滚动到播放器位置才真正初始化视频资源首屏性能提升明显。注意observer.unobserve要执行否则回调还会触发浪费性能组件卸载时也要disconnect。5.4 清晰度切换的正确姿势如果只是单个mp4用definition数组就能让控制条上出现清晰度切换菜单new Player({ el, definition: [ { text: 标清, defaultValue: true, url: https://example.com/video_sd.mp4 }, { text: 高清, url: https://example.com/video_hd.mp4 } ] })点击清晰度选项后播放器会自动切换到对应url并保持当前播放进度实测进度保持逻辑内置不需要自己记录。但如果是HLS流m3u8则要使用xgplayer-hls.js插件import HlsPlayer from xgplayer-hls.js const player new HlsPlayer({ el: containerRef.value, url: https://example.com/stream.m3u8, width: 100%, height: 360 })HlsPlayer是xgplayer的子类用法和Player基本一致。需要注意不同码率的m3u8切换本质上就是切换url可以给HlsPlayer也传入definition字段效果和mp4一致。我测试下来Hls模式的起播速度比原生video配合hls.js手写要快不少尤其是自动降级部分插件处理得更聪明。6. 我踩过的三个坑宽高为0、iframe全屏失败、销毁残留报错6.1 挂载时容器宽高为0播放器直接罢工这个问题在列表页使用v-show时最常见。v-show其实只是把display设为none使用IntersectionObserver懒加载后如果播放器组件在隐藏状态被创建容器宽高是0xgplayer初始化出来的界面就会错乱控制条挤在一起视频区域不可见。我的处理方案是双保险在createPlayer前先判断containerRef.value.getBoundingClientRect().width是否大于0如果是0则等待一个能感知显示状态的时机再创建。给容器设置min-height。即使外层暂时是隐藏的也保证容器本身有占位空间。.xg-player-wrap { min-height: 360px; width: 100%; background: #000; }如果项目必须用v-show最稳妥的解决方案是改用:style{ display: visible ? block : none }搭配创建一个nextTick后的初始化时机。说白了就是保证xgplayer实例化时容器在文档流里是有实际尺寸的。6.2 iframe内全屏按钮没有任何反应项目后台管理系统的内容区很多都是iframe嵌入的。xgplayer默认全屏按钮调用的是浏览器Fullscreen API但iframe要能全屏除了播放器代码html标签上必须加allowfullscreen属性iframe src./video-page.html allowfullscreen allowfullscreen/iframe如果你用的是Vue Router挂在父页面里没有iframe那不会遇到这个问题。但一旦涉及iframe还缺一个步骤在父页面iframe标签上设置allowfullscreen。我在Chrome和Edge上实测不设置的话xgplayer的全屏按钮点击后没有报错但全屏状态不生效控制台会提示Permissions policy violation。这是因为浏览器默认限制iframe调用全屏API必须显式放行。另一个和全屏相关的坑是在弹窗例如el-dialog中播放视频全屏时画面可能出不来或只黑屏。原因一般是弹窗的父级有overflow: hidden且播放器被包裹在动画容器中。解决办法是把播放器容器DOM移到body下再执行全屏xgplayer提供了x5VideoType等兼容参数但更通用的方案是使用它内部的fullscreen钩子player.on(fullscreenchange, () { // 全屏时手动将播放器外层样式改为fixed并置顶 if (player.isFullscreen) { containerRef.value.style.position fixed containerRef.value.style.zIndex 9999 } })当然这个方案需要你控制容器简单粗暴但有效。6.3 组件销毁后控制台报错视频还在放还有一个高频问题跳转路由后页面不播了但浏览器控制台报类似Cannot read properties of null的错误或者后台网络请求里视频还在下载。这是因为组件销毁时没有调用播放器destroy()resize监听、定时器、事件绑定全都残留了。记得在onBeforeUnmount里执行if (player) { player.destroy() player null }这里要注意destroy()之后不能再调用任何播放器方法否则会报错。如果组件卸载后还有异步任务比如请求新的播放地址回调里尝试访问player一定要做空值判断。我在封装组件时习惯统一定义一个_safePlayer()方法包装所有操作否则很容易在边界情况下踩到空引用。另外如果nedestroy后立即重新创建播放器同一个DOM容器可以复用不需要清空内部html吗实测destroy()会把容器内的事件和子元素清理干净可以直接再new不需要手动innerHTML。但稳妥起见销毁后把player置空并在创建时判断存在则先销毁再创建防止重复实例叠加。7. 一个能跑的demoVite Vue3完整接入案例7.1 项目初始化与代码结构我重新建了一个干净的demo项目演示完整流程。用Vite创建npm create vitelatest xgplayer-demo -- --template vue安装xvplayer依赖npm install xgplayer在src/App.vue里直接引用封装好的组件模拟一个最简单的播放页面。完整文件内容如下!-- src/App.vue -- template div classpage h3Vue3 xgplayer demo/h3 XgPlayer :urlvideoUrl :postervideoPoster :autoplayfalse :height400 readyonReady timeupdateonTimeupdate / div classstatus 当前播放时间{{ currentTime.toFixed(1) }}秒 /div /div /template script setup import { ref } from vue import XgPlayer from ./components/XgPlayer.vue const videoUrl ref(https://media.w3.org/2010/05/sintel/trailer.mp4) const videoPoster ref(https://media.w3.org/2010/05/sintel/poster.png) const currentTime ref(0) const onReady (player) { console.log(播放器就绪, player) } const onTimeupdate (time) { // 只更新到响应式数据这里不节流是演示用 currentTime.value time } /script style scoped .page { max-width: 800px; margin: 40px auto; } .status { margin-top: 12px; font-size: 14px; color: #666; } /style组件代码就用上面第三节里的封装版本。注意引入时路径大小写要保持一致XgPlayer.vue中xg-player-wrap的类名不要和其他样式冲突。7.2 体验与踩点记录这个demo跑起来后播放器显示正常控制条上有播放/暂停、时间、音量、倍速、全屏、设置等按钮。我特意试了切换videoUrl的值用定时器三秒后换到另一个视频地址前提是地址允许CORS播放器没有重新黑屏而是直接开始加载新资源。倍速切换后播放速度立即生效进度条的时间计算也是按实际播放进度走不会因为倍速改变而出现时间跳变。如果把keyShortcut: normal打开点击播放器区域后再按空格页面不会滚动而是暂停/播放方向键控制快进快退体验非常跟手。视频结束时显示重播按钮点击可以原地重播不用手动刷新。7.3 再从demo往工程化方向想一步上面的demo适合直接抄。但真实项目里建议再补两个能力错误上报和重试逻辑播放器error事件时要区分网络错误、格式错误、流错误至少做一次自动重试。多实例管理一个页面可能出现多个播放器比如对比视频建议封装一个useXgPlayer组合式函数通过id管理多个实例而不是每个组件里都自己维护player变量。组合式函数内部也可以自动处理销毁逻辑组件代码更干爽。我自己项目里最终就是用useXgPlayer替换了组件内直接逻辑因为列表页要同时挂十几个播放器各自管理生命周期很繁琐。组合式函数的好处是业务层和播放器层完全解耦换用其他播放器库时只需要替换函数内部实现业务组件的代码无需改动。写在实际操作之后的个人体会xgplayer这套玩下来最大的感受是它的API设计比我想象的更适合工程化。核心播放器只是提供一个实例化壳真正好用的是它的事件机制、配置透传和插件体系。事件绑定和销毁的规范丝毫无差只要养成初始化时绑定、卸载时解绑的习惯几乎不会出现泄漏。至于那些宽高为0、iframe全屏限制的坑其实每个播放器库都有提前了解个中原理浏览器全屏策略、DOM尺寸布局时机排查起来就有明确方向。如果你也在Vue3项目里纠结播放器选型我建议不用再试错了直接上xgplayer把上面的demo跑通再根据业务需要慢慢加弹幕、直播、水印这些扩展能力。后面有时间我再写一篇关于xgplayer 弹幕插件在Vue3里集成的实际方案到时继续聊。
Vue3项目集成xgplayer播放器：从封装到踩坑的完整实践
最近接了个Vue3项目要做课程视频播放模块。一开始我拿原生video标签凑合结果倍速、清晰度切换、键盘快捷键、自定义控制条这些功能写完UI丑得自己都嫌弃。后来换成xgplayer半天就把这块捋顺了。网上关于Vue3集成xgplayer的资料挺多但大多停留在怎么安装包、怎么new一个Player真正把使用步骤和demo细节讲透的很少。这篇就把我在实际项目里跑通过的完整流程、封装思路、踩坑记录都整理出来想在Vue3项目里快速接入播放器的朋友可以直接参考。1. 选型前的自我拷问为什么我放弃了原生video和video.js先交代一下项目背景视频资源有普通mp4和m3u8直播流转码要求支持倍速、高清/标清切换、截图、键盘空格暂停/方向键进退。这些需求如果全部用原生video写意味着我要自己造一套控制栏UI、自己管理全屏API差异、自己处理HLS的MediaSource扩展。说实话不是不能写但周期至少一周起步而且后续维护成本极高。当时对比过两个方案video.js和xgplayer。video.js是老牌播放器插件生态齐全但它默认皮肤的样式确实有点过时而且API风格偏传统在Vue3组件化场景下感觉有点隔阂。xgplayer是字节跳动开源的那款底层还是基于HTML5 video但把UI、事件、控制逻辑都封装好了默认皮肤清爽配置项设计也更贴近现代前端的使用习惯。做个精简对比维度原生videovideo.jsxgplayer控制栏UI自己写内置但样式偏老内置可高度自定义倍速控制自己写原生支持原生支持配置简单HLS支持需要MSE处理插件机制官方插件弹幕/清晰度无第三方插件内置或扩展插件Vue3友好度一般一般无框架依赖直接操作DOM实践中我的结论是如果只是放一个裸视频那原生video足够但项目一旦有交互要求直接上xgplayer能省下大量造轮子的时间。v2版本的xgplayer对Vue3没有特殊适配问题因为它本质上是纯JS库通过传入DOM元素初始化不依赖框架生命周期这对组件化使用非常友好。2. 环境准备与依赖安装先让播放器在开发环境里跑起来2.1 安装核心包和样式用Vite创建的Vue3项目Vue3.4 Vite5里安装命令很简单npm install xgplayer如果用到HLS直播流还需要单独装插件npm install xgplayer-hls.js样式文件需要手动引入。这里有个容易忽略的点只引入JS不引入CSS播放器会以裸video形态出现控制条全乱。正确姿势是同时引入核心样式import xgplayer/dist/index.min.css如果要用到hls插件插件的样式一般会自动包含在核心包里不需要额外引。但版本不匹配时可能出现样式缺失遇到这种情况检查下核心包和插件包版本是否搭。2.2 最小可用demo在组件里直接new播放器先把最朴素的版本跑通。创建一个Vue单文件组件模板里放一个div容器在onMounted里实例化Player。注意xgplayer的初始化必须绑定到已渲染的真实DOM上所以onMounted是安全时机template div refplayerContainer/div /template script setup import { ref, onMounted } from vue import Player from xgplayer import xgplayer/dist/index.min.css const playerContainer ref(null) let player null onMounted(() { player new Player({ el: playerContainer.value, url: https://example.com/video.mp4, width: 100%, height: 360, autoplay: false, videoInit: true }) }) /script这样就实现了最基础的能放视频。监听播放状态后续可以通过player.on(play, () {})来感知。2.3 版本坑提醒这里提个实测遇到的坑xgplayer核心版本和插件版本经常不是同步发布的。比如核心包升到2.x后如果直接把hls插件也升到最新可能出现插件内部引用路径不匹配导致播放器初始化报错。稳妥做法是核心包和插件包保持同一个大版本例如都是2.x的某个小版本测试通过后再锁定package.json里的具体版本号。npm的^符号会自动安装小版本最新所以建议用完直接固定版本避免过段时间重新install后行为漂移。3. 封装可复用组件给播放器加一层Vue3的外壳3.1 为什么要封装直接在业务页面上写new Player不是不行但如果多个页面都要播放视频每个页面复制一遍初始化代码后续要改全局配置比如加logo、水印、统一语言就得逐个页面改。封装成Vue组件后通过props传入视频地址和配置通过事件向父组件通信通过defineExpose暴露播放器实例这才是组件化开发的合理姿势。3.2 组件完整代码我封装了一个XgPlayer.vue支持url、poster、autoplay这几个常用prop同时监听url变化自动切换播放源在组件卸载前调用destroy释放资源。template div classxg-player-wrap refcontainerRef/div /template script setup import { ref, onMounted, onBeforeUnmount, watch, nextTick } from vue import Player from xgplayer import xgplayer/dist/index.min.css const props defineProps({ url: { type: String, required: true }, poster: { type: String, default: }, autoplay: { type: Boolean, default: false }, height: { type: Number, default: 360 } }) const emit defineEmits([ready, play, pause, ended, timeupdate, error]) const containerRef ref(null) let player null // 初始化播放器 const createPlayer async () { if (player) return await nextTick() if (!containerRef.value) return player new Player({ el: containerRef.value, url: props.url, poster: props.poster, autoplay: props.autoplay, width: 100%, height: props.height, playbackRate: [0.5, 0.75, 1, 1.25, 1.5, 2], keyShortcut: true, videoInit: true }) player.on(play, () emit(play)) player.on(pause, () emit(pause)) player.on(ended, () emit(ended)) player.on(timeupdate, () emit(timeupdate, player.currentTime)) player.on(error, (err) emit(error, err)) emit(ready, player) } // 监听url变化实现播放源切换 watch(() props.url, (newUrl) { if (player) { player.src newUrl if (props.autoplay) { player.play() } } }) onMounted(createPlayer) onBeforeUnmount(() { if (player) { player.destroy() player null } }) defineExpose({ player, getPlayer: () player }) /script几个细节说明一下await nextTick()很重要。如果父组件通过v-if异步渲染这个子组件很可能组件onMounted执行时DOM还没真正布局完成容器宽度为0xgplayer初始化会报警。加上nextTick能有效规避。player.src newUrl是切换播放源的直接方式不必重新new一个Player。实测切流很快不需要销毁重建。defineExpose里我既暴露了player字段也提供了getPlayer方法。这里有个Vue3的注意点defineExpose暴露的值在父组件拿到的是响应式包装后的版本直接调用播放器方法时建议用getPlayer()拿原始实例避免被proxy影响。3.3 父组件的使用方式父组件用法如下template XgPlayer :urlvideoUrl :posterposter :autoplayfalse readyhandleReady timeupdatehandleTimeupdate / /template script setup import XgPlayer from /components/XgPlayer.vue const handleReady (player) { console.log(player ready, player) // player.requestFullscreen() 等操作 } const handleTimeupdate (time) { console.log(当前播放时间, time) } /script这样父组件完全不感知xgplayer的内部实现只依赖子组件暴露的属性和事件后续更换其他播放器也不会影响业务代码逻辑。4. 事件监听与状态同步别把事件挂在全局4.1 xgplayer的事件模型xgplayer的事件机制和原生EventTarget类似核心方法就三个on、once、off。事件类型很丰富但实际用到最多的就这么几个事件名触发时机常用场景ready播放器初始化完成隐藏loadingplay开始播放埋点、切换UIpause暂停播放记忆播放进度ended播放结束推荐下一节timeupdate播放时间更新进度条刷新waiting缓冲等待显示loadingplaying缓冲结束后继续播放隐藏loadingerror播放异常错误提示fullscreenchange全屏状态切换同步按钮状态4.2 事件注册的时机和清理在封装组件里我习惯把事件注册集中放在初始化函数中而不是散落在各处。同时要留意如果组件的props.url变化导致重新加载不需要重新绑定事件因为播放器实例没变只是切换了src。但如果父组件通过v-if销毁并重建组件onBeforeUnmount里不仅要destroy()播放器还要确保没有遗留的事件引用。xgplayer的destroy()方法理论上会清理内部监听但如果你额外绑定过自定义事件到window或document比如全屏监听那就必须手动移除。这里贴一段我在真实项目中处理全屏事件的代码// 在创建播放器之后 this._handleFullscreenChange () { emit(fullscreenChange, player.isFullscreen) } document.addEventListener(fullscreenchange, this._handleFullscreenChange) // 在销毁之前 onBeforeUnmount(() { document.removeEventListener(fullscreenchange, this._handleFullscreenChange) player.destroy() })为什么要这样写因为xgplayer的全屏按钮触发的是浏览器全屏API它自己内部监听了fullscreenchange但如果外层业务需要感知全屏状态比如隐藏导航栏最好在外层也监听一份这时代理函数如果不用具名引用卸载时是移除不掉的。4.3 把播放器状态同步到Vue响应式数据还有一个常见需求页面某个地方显示当前播放时间/总时长。不要直接在timeupdate回调里给ref赋值因为timeupdate触发频率很高约250ms一次Vue响应式更新频繁会导致性能浪费。我在组件里是这么处理的let lastTime 0 const handleTimeupdate (time) { // 简单节流每500ms才更新一次响应式数据 if (time - lastTime 0.5) { currentTime.value time lastTime time } }更好的方案是在父组件里用纯事件方式拿时间并自行节流。组件内部的核心原则是高频事件向外抛可以但不要直接改响应式内部状态除非你有明确的节流机制。5. 实用配置项盘点倍速、画中画、懒加载与清晰度切换5.1 常用配置项速查表xgplayer的配置项繁多这里挑实际项目里用得最顺手的列成表格配置项类型默认值说明urlString无视频地址widthString/Number100%宽度支持百分比和像素heightString/Number300高度建议固定高度或按比例计算autoplayBooleanfalse自动播放。需要满足浏览器静音自动播放策略loopBooleanfalse循环播放volumeNumber0.7初始音量 0~1playbackRateArray[]倍速选项例如[0.5,0.75,1,1.25,1.5,2]keyShortcutBoolean/Stringfalse键盘快捷键可设normal或globalfitVideoSizeStringauto视频尺寸适配可设contain、coverdefinitionArray[]多清晰度列表langStringzh-cn语言controlsBooleantrue是否显示控制条5.2 倍速和快捷键的实战配置倍速配置很简单直接在初始化时传playbackRate数组new Player({ // ...省略 playbackRate: [0.5, 0.75, 1, 1.25, 1.5, 2] })播放器控制条上会自动出现倍速按钮点击选择对应倍速不需要额外代码。键盘快捷键默认是关闭的因为视频页面往往有其他交互比如空格滚动页面只在播放器内部聚焦时才应该响应。keyShortcut: normal可以让播放器容器内按空格暂停、按方向键快进快退实测体验很不错按Home键回到开头、按End键跳到结尾的映射也是内置的。5.3 懒加载进入视口才加载播放器课程列表页都放一个播放器性能肯定扛不住。我的习惯是使用IntersectionObserver当播放器容器进入可视区域时再创建实例。在Vue3组合式API中实现起来非常干净const containerRef ref(null) let observer null onMounted(() { observer new IntersectionObserver((entries) { entries.forEach((entry) { if (entry.isIntersecting !player) { createPlayer() observer.unobserve(entry.target) } }) }, { threshold: 0.1 }) if (containerRef.value) { observer.observe(containerRef.value) } }) onBeforeUnmount(() { if (observer) { observer.disconnect() } if (player) { player.destroy() } })这样页面初始加载时只渲染一个占位div滚动到播放器位置才真正初始化视频资源首屏性能提升明显。注意observer.unobserve要执行否则回调还会触发浪费性能组件卸载时也要disconnect。5.4 清晰度切换的正确姿势如果只是单个mp4用definition数组就能让控制条上出现清晰度切换菜单new Player({ el, definition: [ { text: 标清, defaultValue: true, url: https://example.com/video_sd.mp4 }, { text: 高清, url: https://example.com/video_hd.mp4 } ] })点击清晰度选项后播放器会自动切换到对应url并保持当前播放进度实测进度保持逻辑内置不需要自己记录。但如果是HLS流m3u8则要使用xgplayer-hls.js插件import HlsPlayer from xgplayer-hls.js const player new HlsPlayer({ el: containerRef.value, url: https://example.com/stream.m3u8, width: 100%, height: 360 })HlsPlayer是xgplayer的子类用法和Player基本一致。需要注意不同码率的m3u8切换本质上就是切换url可以给HlsPlayer也传入definition字段效果和mp4一致。我测试下来Hls模式的起播速度比原生video配合hls.js手写要快不少尤其是自动降级部分插件处理得更聪明。6. 我踩过的三个坑宽高为0、iframe全屏失败、销毁残留报错6.1 挂载时容器宽高为0播放器直接罢工这个问题在列表页使用v-show时最常见。v-show其实只是把display设为none使用IntersectionObserver懒加载后如果播放器组件在隐藏状态被创建容器宽高是0xgplayer初始化出来的界面就会错乱控制条挤在一起视频区域不可见。我的处理方案是双保险在createPlayer前先判断containerRef.value.getBoundingClientRect().width是否大于0如果是0则等待一个能感知显示状态的时机再创建。给容器设置min-height。即使外层暂时是隐藏的也保证容器本身有占位空间。.xg-player-wrap { min-height: 360px; width: 100%; background: #000; }如果项目必须用v-show最稳妥的解决方案是改用:style{ display: visible ? block : none }搭配创建一个nextTick后的初始化时机。说白了就是保证xgplayer实例化时容器在文档流里是有实际尺寸的。6.2 iframe内全屏按钮没有任何反应项目后台管理系统的内容区很多都是iframe嵌入的。xgplayer默认全屏按钮调用的是浏览器Fullscreen API但iframe要能全屏除了播放器代码html标签上必须加allowfullscreen属性iframe src./video-page.html allowfullscreen allowfullscreen/iframe如果你用的是Vue Router挂在父页面里没有iframe那不会遇到这个问题。但一旦涉及iframe还缺一个步骤在父页面iframe标签上设置allowfullscreen。我在Chrome和Edge上实测不设置的话xgplayer的全屏按钮点击后没有报错但全屏状态不生效控制台会提示Permissions policy violation。这是因为浏览器默认限制iframe调用全屏API必须显式放行。另一个和全屏相关的坑是在弹窗例如el-dialog中播放视频全屏时画面可能出不来或只黑屏。原因一般是弹窗的父级有overflow: hidden且播放器被包裹在动画容器中。解决办法是把播放器容器DOM移到body下再执行全屏xgplayer提供了x5VideoType等兼容参数但更通用的方案是使用它内部的fullscreen钩子player.on(fullscreenchange, () { // 全屏时手动将播放器外层样式改为fixed并置顶 if (player.isFullscreen) { containerRef.value.style.position fixed containerRef.value.style.zIndex 9999 } })当然这个方案需要你控制容器简单粗暴但有效。6.3 组件销毁后控制台报错视频还在放还有一个高频问题跳转路由后页面不播了但浏览器控制台报类似Cannot read properties of null的错误或者后台网络请求里视频还在下载。这是因为组件销毁时没有调用播放器destroy()resize监听、定时器、事件绑定全都残留了。记得在onBeforeUnmount里执行if (player) { player.destroy() player null }这里要注意destroy()之后不能再调用任何播放器方法否则会报错。如果组件卸载后还有异步任务比如请求新的播放地址回调里尝试访问player一定要做空值判断。我在封装组件时习惯统一定义一个_safePlayer()方法包装所有操作否则很容易在边界情况下踩到空引用。另外如果nedestroy后立即重新创建播放器同一个DOM容器可以复用不需要清空内部html吗实测destroy()会把容器内的事件和子元素清理干净可以直接再new不需要手动innerHTML。但稳妥起见销毁后把player置空并在创建时判断存在则先销毁再创建防止重复实例叠加。7. 一个能跑的demoVite Vue3完整接入案例7.1 项目初始化与代码结构我重新建了一个干净的demo项目演示完整流程。用Vite创建npm create vitelatest xgplayer-demo -- --template vue安装xvplayer依赖npm install xgplayer在src/App.vue里直接引用封装好的组件模拟一个最简单的播放页面。完整文件内容如下!-- src/App.vue -- template div classpage h3Vue3 xgplayer demo/h3 XgPlayer :urlvideoUrl :postervideoPoster :autoplayfalse :height400 readyonReady timeupdateonTimeupdate / div classstatus 当前播放时间{{ currentTime.toFixed(1) }}秒 /div /div /template script setup import { ref } from vue import XgPlayer from ./components/XgPlayer.vue const videoUrl ref(https://media.w3.org/2010/05/sintel/trailer.mp4) const videoPoster ref(https://media.w3.org/2010/05/sintel/poster.png) const currentTime ref(0) const onReady (player) { console.log(播放器就绪, player) } const onTimeupdate (time) { // 只更新到响应式数据这里不节流是演示用 currentTime.value time } /script style scoped .page { max-width: 800px; margin: 40px auto; } .status { margin-top: 12px; font-size: 14px; color: #666; } /style组件代码就用上面第三节里的封装版本。注意引入时路径大小写要保持一致XgPlayer.vue中xg-player-wrap的类名不要和其他样式冲突。7.2 体验与踩点记录这个demo跑起来后播放器显示正常控制条上有播放/暂停、时间、音量、倍速、全屏、设置等按钮。我特意试了切换videoUrl的值用定时器三秒后换到另一个视频地址前提是地址允许CORS播放器没有重新黑屏而是直接开始加载新资源。倍速切换后播放速度立即生效进度条的时间计算也是按实际播放进度走不会因为倍速改变而出现时间跳变。如果把keyShortcut: normal打开点击播放器区域后再按空格页面不会滚动而是暂停/播放方向键控制快进快退体验非常跟手。视频结束时显示重播按钮点击可以原地重播不用手动刷新。7.3 再从demo往工程化方向想一步上面的demo适合直接抄。但真实项目里建议再补两个能力错误上报和重试逻辑播放器error事件时要区分网络错误、格式错误、流错误至少做一次自动重试。多实例管理一个页面可能出现多个播放器比如对比视频建议封装一个useXgPlayer组合式函数通过id管理多个实例而不是每个组件里都自己维护player变量。组合式函数内部也可以自动处理销毁逻辑组件代码更干爽。我自己项目里最终就是用useXgPlayer替换了组件内直接逻辑因为列表页要同时挂十几个播放器各自管理生命周期很繁琐。组合式函数的好处是业务层和播放器层完全解耦换用其他播放器库时只需要替换函数内部实现业务组件的代码无需改动。写在实际操作之后的个人体会xgplayer这套玩下来最大的感受是它的API设计比我想象的更适合工程化。核心播放器只是提供一个实例化壳真正好用的是它的事件机制、配置透传和插件体系。事件绑定和销毁的规范丝毫无差只要养成初始化时绑定、卸载时解绑的习惯几乎不会出现泄漏。至于那些宽高为0、iframe全屏限制的坑其实每个播放器库都有提前了解个中原理浏览器全屏策略、DOM尺寸布局时机排查起来就有明确方向。如果你也在Vue3项目里纠结播放器选型我建议不用再试错了直接上xgplayer把上面的demo跑通再根据业务需要慢慢加弹幕、直播、水印这些扩展能力。后面有时间我再写一篇关于xgplayer 弹幕插件在Vue3里集成的实际方案到时继续聊。
