waiting事件用于监听媒体因缓冲不足而暂停播放的状态，常见于网络慢、拖动进度条或preload设为metadata/none时，配合buffered和currentTime可精准判断卡顿类型。
在 HTML5 中，waiting 事件用于监听媒体（如 <video> 或 <audio>）因缓冲不足而暂停播放、等待更多数据加载的状态。它通常发生在网络较慢、带宽波动或服务器响应延迟时，是检测“卡顿”最直接的原生事件之一。
waiting 事件触发的典型场景
当媒体元素处于 playing 状态，但因当前缓冲区（buffered）不足以支撑连续播放，浏览器会自动暂停并触发 waiting。注意：它不表示加载失败，而是“暂时等数据”，后续可能恢复（如触发 canplay 或 playing）。
- 用户拖动进度条到未缓冲区域
- 初始播放时首帧未就绪，且
preload设为metadata或none - 边播边下过程中网速下降，已缓存时长
如何正确监听 waiting 事件
使用 addEventListener 绑定 waiting，推荐配合 waiting 的对立事件（如 playing、canplay）做状态同步，避免重复响应：
const video = document.querySelector('video');
video.addEventListener('waiting', () => {
console.log('视频进入等待缓冲状态');
// 可在此显示“加载中”提示、暂停 UI 动画、记录卡顿次数等
});
video.addEventListener('playing', () => {
console.log('视频恢复播放');
// 隐藏加载提示、重置卡顿计时器等
});
结合 buffered 和 currentTime 做更精准判断
仅靠 waiting 无法区分是“首次加载卡顿”还是“中途卡顿”。可通过检查 buffered 范围是否覆盖当前播放位置，增强逻辑鲁棒性：
立即学习“前端免费学习笔记（深入）”；
video.addEventListener('waiting', () => {
const { buffered, currentTime } = video;
let isBufferedAhead = false;
for (let i = 0; i < buffered.length; i++) {
if (buffered.start(i) <= currentTime && currentTime <= buffered.end(i)) {
isBufferedAhead = true;
break;
}
}
if (!isBufferedAhead) {
console.warn('waiting 触发，但 currentTime 不在任何 buffered 区间内 → 真实卡顿');
}
});
实用建议与注意事项
-
不要只依赖 waiting 判断“播放失败”：它和
stalled不同，stalled表示资源加载明显受阻（如 HTTP 超时），更适合监控异常；waiting更偏向正常缓冲行为 - 避免频繁 DOM 操作：如果显示加载 UI，建议防抖（如 300ms 内只显示一次），防止快速闪现
-
移动端需注意 autoplay 限制：iOS Safari 等可能延迟触发
waiting，直到用户手势后才开始加载，此时首次waiting可能被忽略 -
可搭配 MediaSource API 或 MSE：对自定义分片加载场景，
waiting仍有效，但更推荐监听sourceopen+updateend做细粒度控制
