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] 一定存在。
实际使用中应始终做空检查,并遍历全部:
立即学习“前端免费学习笔记(深入)”;
track.oncuechange = () => {
const cues = track.activeCues;
if (cues.length === 0) return;
for (let i = 0; i < cues.length; i++) {
const cue = cues[i];
if (cue.startTime === 8.5) {
showQuiz();
}
}
};metadata 轨道的 cue 不显示但可触发逻辑,需显式设置 kind="metadata"
如果目标是纯时间点控制(比如在 12s 弹窗、23s 切换广告),不要用 kind="subtitles"——用户看到字幕干扰体验,且浏览器可能默认隐藏非活动轨道。应改用 kind="metadata":
<track kind="metadata" src="logic.vtt" label="Logic Triggers"></track>-
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",否则监听器永远收不到事件。



















