小程序视频播放教程｜VideoContext 播放全屏、进度续播与打断处理 – MPForge

一、视频播放的问题九成出在「状态没人管」

结论先记住：video 标签谁都能放，VideoContext 的状态才是要设计的东西。播放、暂停、全屏、进度、打断，每一项都有前后两个状态要对齐。

我们见过的典型翻车：列表页十条商品讲解视频，用户划到哪条哪条响，两条叠声；全屏退出后进度条显示和实际播放位置不一致；来电或切后台回来，视频停在半路既不暂停也不续播，用户一脸茫然。这些都不是播放器 bug，是状态管理没做。

分工口径：开发负责实例管理与事件监听，运营负责定「什么场景允许自动播放、什么场景必须点一下」，这条规则要写进需求文档而不是口头约定。

二、VideoContext 的封装步骤

先管住实例，再谈播放体验。按这五步走：

1. 封装统一播放器：把 video 与 VideoContext 包成一个组件，播放、暂停、进度、全屏都走同一套方法，页面不直接操作实例。
2. 监听打断与结束：注册音频打断回调处理来电、其他 App 抢占音频等场景，onEnded 里决定重播或切换下一集。
3. 进度可续播：每 3 秒左右把 currentTime 上报存储，重新进入页面时读取并 seek 到就近位置，超长视频按集数分键存储。
4. 列表页暂停非当前：滚动或切换播放对象时，先暂停上一个实例再播新的，用单一「当前播放 id」控制全局。
5. 真机全屏抽检：iOS 与安卓各测全屏进出、旋转、以及全屏中来电三种情况，核对退出后进度与界面状态一致。

前后台切换的完整事件清单，见 小程序前后台切换事件；音频场景的同类处理思路可参考 小程序背景音频播放注意。

三、全屏、倍速与失败提示的口径

这三个功能都有「默认值陷阱」，逐项核对：

四、续播与打断：把「被中断」当成常态设计

别假设用户会一口气看完：来电、切后台、锁屏都是正常路径。设计原则有三条：

• 打断即暂停：系统打断事件触发时立刻暂停并记录进度，恢复逻辑交给用户点继续，别自动续播吓到人。
• 进度按场景存储：课程视频按「课程 id + 小节 id」分键存，商品讲解按视频 id 存，清理策略跟内容下架联动。
• 弱网降级：加载超时先切低清晰度占位帧，提示用户网络不佳，别直接报错中断。

解码与清晰度选择的底层说明，见 小程序视频解码与清晰度说明。如果视频里嵌了门店或位置信息，记得同步核对后台的 GEO 地理位置配置，那是另一套独立体系。

五、上线前播放自检清单

提审前五分钟过一遍这张表：

六、避坑清单

四条都和「克」制有关：

• 别放开多实例同时播：列表场景只保留一个播放实例，叠声是用户流失最快的体验事故。
• 别默认自动播放：自动播放只留给明确的主视频位且静音起步，其余一律点击触发。
• 别丢掉播放进度：内容型产品续播是留存的基本盘，3 秒粒度存储成本很低。
• 别在全屏里藏关键操作：购买、咨询按钮别只放在全屏层，退出全屏后也要能一键到达。

七、常见问题 FAQ