track.activeCues 是只读类数组对象,无 forEach 和 length 属性,需用 for 循环或扩展运算符转换;cuechange 时可能含 0+ 个字幕项,须空检查并遍历;时间比对需用容差判断而非严格相等。

track.activeCues 是动态只读列表,不能直接遍历
你写 track.activeCues.forEach(...) 会报错,因为 activeCues 返回的是 TextTrackCueList(类数组对象),不是 Array,不带 forEach 方法。它也没有 length 属性(但有 length 伪属性,需用 Object.keys(cues).length 或循环计数)。常见错误是把它当普通数组用,结果静默失败或抛 TypeError。
正确做法是用传统 for 循环或转成数组:
for (let i = 0; i-
Array.from(track.activeCues).forEach(cue => { ... })(兼容性好,ES6+) -
[...track.activeCues].forEach(...)(更简洁,但 IE 不支持)
cuechange 事件触发时 activeCues 可能为空或含多个 cue
cuechange 并不保证每次只激活一个 cue;尤其在时间点密集、字幕重叠或视频 seek 后,track.activeCues 可能包含 0、1 或多个 TextTrackCue 实例。别假设 activeCues[0] 一定存在。
实际使用中应始终做空检查,并遍历全部:
kind="subtitles"
-
kind="metadata"轨道默认不渲染任何内容,仅提供时间轴信号 - VTT 文件仍需标准格式(
WEBVTT开头 + 时间戳块),但text字段可为空或填任意标识符(如{"action":"showCTA"}) - 注意:部分旧版 iOS Safari 对
metadata轨道支持不稳定,建议 fallback 到timeupdate检测
从 VTT 解析 startTime 需注意浮点精度与帧率偏差
VTT 中写的 00:00:03.500 --> 00:00:04.000,JS 读出的 cue.startTime 可能是 3.4999999999999996,直接用 === 匹配会失败。别写 if (cue.startTime === 3.5)。
安全比对方式是容差判断:
- 用
Math.abs(video.currentTime - cue.startTime) (推荐 0.05~0.1 秒) - 若需精确到帧,可结合
video.videoHeight和已知帧率估算,但多数业务场景 0.1 秒容差足够 - 避免在
cuechange回调里做耗时操作(如 DOM 批量插入),否则可能阻塞后续 cue 触发
真正容易被忽略的是:track 必须处于 mode = "showing" 状态,cuechange 才会触发。哪怕 default 属性已设,加载后仍需手动设置 track.mode = "showing",否则监听器永远收不到事件。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











