HTML5视频播放结束监听技巧

本文深入解析了HTML5视频播放结束监听的核心机制与实战避坑指南，重点揭示了`ended`事件仅在视频自然播放至末尾且未启用`loop`时才触发的严格条件，并强调必须在`loadedmetadata`事件后绑定监听以确保兼容性与可靠性；同时指出常见失效原因（如绑定过早、源加载失败、iOS自动播放限制等），并提供兼顾鲁棒性的兜底方案——结合`timeupdate`与时间容差判断，真正保障“播放完毕后执行动作”的业务需求落地。

video 元素的 ended 事件到底什么时候触发

它只在视频自然播放到末尾（即播放指针到达 duration 且没有循环）时触发，不是暂停、出错、用户拖拽跳过结尾或网络中断时触发。如果设置了 loop="true"，ended 永远不会触发——浏览器会直接从头重播，不经过“结束”状态。

监听 ended 事件的正确写法（含兼容性注意）

必须确保 video 元素已加载完成、DOM 已就绪，否则绑定无效；现代浏览器支持直接用 addEventListener，但 IE9–10 需用 attachEvent（已基本可忽略）。关键点是：不要等 load 或 canplay，而应至少等到 loadedmetadata 后再绑定，否则部分浏览器（如 Safari）可能漏掉首次结束事件。

const video = document.querySelector('video');
video.addEventListener('loadedmetadata', () => {
  video.addEventListener('ended', () => {
    console.log('视频已自然播放完毕');
    // 这里写你的逻辑，比如显示按钮、跳转、上报埋点
  });
});

常见失效原因和避坑清单

很多情况下写了监听却没反应，实际是以下某个环节断了：

• video 标签缺少 src 或源未加载成功（检查 Network 面板是否有 404 或 CORS 错误）
• 绑定时机太早：脚本在 标签前执行，querySelector 返回 null
• 使用了 onended = function() {...} 但后续又被其他代码覆盖（单次赋值，不可叠加）
• 视频被 JS 调用 pause() 后手动设置 currentTime = video.duration，这不会触发 ended —— 必须靠真实播放流程走到终点
• 移动端 iOS Safari 对自动播放策略严格，若视频无用户手势触发（如点击），可能根本没开始播，自然也不会结束

需要「播放完自动做某事」？别只靠 ended

如果目标是“确保用户看到结尾后执行动作”，仅监听 ended 不够鲁棒。建议组合判断：

video.addEventListener('timeupdate', () => {
  if (video.ended || (video.currentTime >= video.duration - 0.1 && !video.paused && !video.seeking)) {
    // 视频极大概率已结束（加 0.1s 容差，避免浮点误差）
    handleVideoComplete();
  }
});

这种兜底方式能覆盖 ended 未触发的边缘情况，比如某些编码异常导致元数据不准，或浏览器 bug。但注意频繁触发 timeupdate 的开销，上面示例里没做节流，真实项目中建议加简单防抖。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~