在微信小程序开发中，视频播放功能几乎是内容类、电商类、教育类小程序的标配，而实现视频播放离不开video这个媒体组件。别看它只是个标签，里面涉及的属性、事件、平台差异和层级问题非常多，很多人第一次用都会遇到各种莫名其妙的状况。这篇文章就把video组件的常用属性、事件回调机制，以及实际开发中的高频问题一次性讲清楚。
video组件的基础属性详解
video组件最核心的属性就是src，用来指定视频的资源地址。这个地址支持网络路径和本地临时文件路径，但要注意必须是有明确后缀或正确Content-Type的视频资源，否则部分机型会直接黑屏播放失败。如果你拿到的视频链接是动态生成的，建议先通过wx.downloadFile下载到本地临时目录再用临时路径播放，稳定性会好很多。
除了src之外，几个控制播放行为的属性也很常用。autoplay控制是否自动播放，默认是false，而且就算设置为true，在部分安卓机型上也会因为系统策略被拦截，需要用户主动点击才能出声。loop控制循环播放，muted控制静音，controls控制是否显示默认播放控件，默认为true。如果你打算完全自定义控制条，可以把controls设为false，然后自己写进度条和按钮，通过createVideoContext或createSelectorQuery拿到的video上下文来调用play、pause、seek等方法。
还有一个容易被忽略的属性是object-fit，它决定视频画面如何填充组件区域，可选值有contain（包含，可能留黑边）、fill（填充，可能拉伸变形）、cover（覆盖，可能裁剪画面）。做全屏背景视频时一般选cover，做普通课程视频时选contain更合适。另外poster属性可以设置视频封面的网络地址，在视频未播放时展示，这对用户体验很重要，没有封面的黑框观感很差。
弹幕功能与进阶配置
video组件原生支持弹幕，这在小程序里算是个惊喜功能。通过danmu-list属性传入弹幕数组，每条弹幕包含text（文字）、color（颜色）、time（出现的秒数）、border（是否带描边）等字段。也可以用video上下文的sendDanmu方法在播放过程中动态发送弹幕，配合输入框就能实现一个简易的弹幕互动功能。
进阶配置方面，enable-play-gesture控制是否开启手势控制（滑动调整音量和进度），enable-progress-gesture控制进度手势，show-center-play-btn控制中间播放按钮的显示。倍速播放可以用playback-rate属性或上下文的playbackRate方法，支持0.5倍到2倍。如果是做直播场景，还可以用live属性切换直播模式，不过直播更多时候推荐用live-player组件。
需要注意的是，同一页面如果存在多个video组件，部分低版本基础库可能出现播放状态互相干扰的情况，建议非当前展示的视频及时调用pause方法暂停，或者用条件渲染控制只保留一个实例，这样既能省内存也能避免声音叠加的问题。
常用事件回调与触发时机
video组件提供了丰富的事件回调，搞清楚触发时机是写好交互逻辑的前提。bindplay在视频开始或继续播放时触发；bindpause在暂停时触发；bindended在播放到末尾时触发，常用来做自动播放下一个视频或弹出完课弹窗。bindtimeupdate会在播放进度变化时触发，默认触发频率是250毫秒一次，是做自定义进度条、播放计时、断点续播的核心事件。
另外还有bindwaiting（视频加载中）、binderror（播放出错）、bindfullscreenchange（全屏状态切换）、bindloadedmetadata（元数据加载完成）等。特别说一下bindloadedmetadata，视频的时长duration会在回调的detail中返回，如果你的业务需要在播放前展示视频总时长，就在这个回调里取值。binderror则一定要监听，线上视频资源经常会出现链接过期、跨域、转码格式不支持等问题，没有错误处理的话用户只会看到一直转圈的加载状态。
常见问题与解决办法
第一个高频问题是层级问题。video组件是原生组件，层级默认高于普通组件，就算你给弹窗设置了再高的z-index也压不住它，按钮会被视频挡住。官方给的解决方案是用同层渲染，也就是给video加上相同层渲染支持后，原生组件会被渲染在WebView层内，可以用普通方式覆盖。如果同层渲染表现不稳定，还可以在弹窗出现时给video套上cover-view或者干脆用wx:if临时卸载视频，弹窗关闭后再重建。
第二个问题是全屏相关。调用requestFullScreen进入全屏时，direction参数可以指定全屏方向，0表示正常竖向，90和-90是横屏。有的开发者反馈退出全屏后视频尺寸错乱，这通常是因为全屏切换回调里没有重新处理布局，建议在bindfullscreenchange回调里根据isFullscreen的值动态调整容器样式。另外自动全屏在某些安卓机型上会被系统拦截，需要用户手动触发。
第三个问题是宽高设置不生效。video组件必须显式设置width和height，不设置的话可能默认是300像素宽、225像素高，跟你的预期完全对不上。用style设置百分比时，记得父容器也要有确定的高度，否则高度塌陷。做16比9的响应式视频区域时，可以用calc配合vw单位，或者用padding-top的百分比技巧来撑高度。
最后一个常见坑是iOS和安卓的表现差异。比如自动播放，iOS要求必须有muted为true才允许静音自动播放；倍速设置在部分老安卓机上不生效；某些mov格式的视频iOS能播而安卓不行。建议统一使用H.264编码的mp4格式，兼容性最好。同时开发时务必用真机调试而不是只在开发者工具里看效果，因为开发者工具用的是浏览器播放器模拟，很多原生行为和真机并不一致。
开发实践小结
总体来说，用好video组件的关键在于三点：一是属性配置要贴合业务场景，比如object-fit和poster的选择直接影响观感；二是事件监听要完整，尤其是error和timeupdate，前者保障异常兜底，后者支撑核心交互；三是重视原生组件的特性，层级问题和平台差异提前在真机上验证，比上线后修bug成本低得多。
建议在项目里把video封装成自定义组件，统一处理封面、错误重试、断点记忆这些逻辑，外部只传入视频地址和必要的配置。这样不仅复用方便，后期遇到基础库升级导致的兼容问题，也只需要改一处。掌握了这些知识点，video组件基本就不会再给你出难题了。
微信小程序video组件小程序媒体组件video属性修改时间：2026-09-12 05:10:33