track设kind="chapters"后页面不显示章节列表,因浏览器原生播放器不渲染chapters轨道UI,仅通过JS API暴露时间点,需手动读取cue、生成DOM菜单并绑定跳转逻辑。

track 元素本身不生成目录菜单,它只提供数据;章节导航必须靠 JavaScript 驱动 + chapters 类型轨道配合。
为什么track设kind="chapters"后页面没出现章节列表?
浏览器原生播放器(Chrome、Safari、Edge)压根不渲染 chapters 轨道的 UI。它只把 WebVTT 里的章节时间点暴露给 JS API,你得自己读、自己画菜单、自己绑定点击跳转。
-
chapters是纯数据轨道,不是 UI 组件 —— 它的用途是让脚本知道“第 3 分钟开始是‘安装步骤’”,而不是帮你弹出一个侧边栏 - 所有主流播放器都忽略
label和default属性对chapters的设置,设了也白设 - 如果想看到章节条(如 YouTube 那种进度条上的小竖线),得用
video.textTracks手动监听cuechange事件,再操作 DOM 渲染
WebVTT 章节文件怎么写才被识别为chapters?
必须满足三个硬性条件,缺一不可:首行是 WEBVTT、每段有有效时间轴、文本内容不能为空。
- 时间格式严格为
HH:MM:SS.mmm --> HH:MM:SS.mmm,比如00:02:15.000 --> 00:04:30.500,毫秒位必须三位 - 每段文本不能为空行或纯空格,哪怕只写一个汉字或数字也算有效,否则该 cue 会被跳过
- 文件编码必须是 UTF-8 无 BOM,用 VS Code 或 Sublime 打开时右下角应显示 “UTF-8” 而非 “UTF-8 with BOM”
- 示例
chapters.vtt:
WEBVTT 1 00:00:00.000 --> 00:01:20.000 引言 2 00:01:20.000 --> 00:03:45.000 环境准备 3 00:03:45.000 --> 00:06:10.000 代码实现
怎么用 JS 把章节数据变成可点击的目录?
核心是监听 textTracks[0].mode = "hidden" 后遍历 cues,再生成 标签并绑定 video.currentTime 跳转。
- 必须等
video加载完成且textTracks就绪后再读取 cues,否则cues.length === 0 - 不要直接用
cues[i].text当链接文字 —— 它可能含换行或多余空格,建议.trim().replace(/\s+/g, ' ') - 跳转前检查视频是否已就绪:
if (video.readyState >= 2) video.currentTime = cue.startTime,否则会静默失败 - 简单绑定示例:
const video = document.getElementById('my-video');
const track = video.textTracks[0];
track.mode = 'hidden';
track.addEventListener('load', () => {
const list = document.getElementById('chapter-list');
for (let i = 0; i {
e.preventDefault();
video.currentTime = cue.startTime;
video.play();
});
list.appendChild(a);
}
});
移动端 Safari 点击章节跳转失败的常见原因
不是代码写错,而是 Safari 对自动播放策略极其敏感:只要 video.play() 不在用户手势上下文中触发,就会被拒。
- 解决办法:把
video.play()移到click事件回调最外层,且确保该是真实点击(非 programmatic click) - 别用
setTimeout(() => video.play(), 0)绕过 —— Safari 会判定为非用户触发 - 如果视频初始是静音的,加
muted属性能大幅提高play()成功率 - 部分 iOS 版本要求
video必须已进入视口(getBoundingClientRect().top )才能响应 play
真正卡住人的地方从来不是怎么写 track 标签,而是误以为它能自动生成菜单 —— 实际上你得亲手把 WebVTT 里的时间点翻译成 DOM 节点,再扛住各浏览器对自动播放的限制,最后还得处理滚动定位和焦点管理。这些环节漏掉任意一个,章节导航就只是个摆设。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











