标签必须在HTML解析阶段作为的子节点存在,动态创建并追加的元素不会被浏览器注册,因其需为“parser-inserted”而非“script-inserted”,导致video.textTracks为空且字幕不显示。

标签必须在 内部声明,且不能靠 JavaScript 动态创建后追加——浏览器只在解析 初始 HTML 时扫描并注册 ,运行时插入的节点会被忽略。
为什么 document.createElement('track') + appendChild 不生效
这是最常踩的坑。即便你用 JS 创建了 元素、设置了 kind、src、srclang 等属性,并成功 append 到 上,video.textTracks 里依然看不到它,字幕也不会出现。
原因在于:HTML5 规范要求 必须是 的“parser-inserted”子节点,即在初始 HTML 解析阶段就存在;动态插入的 被视为“script-inserted”,浏览器直接跳过加载与注册流程。
- 错误写法:
const track = document.createElement('track'); track.src = '/sub.vtt'; video.appendChild(track); - 正确前提:
必须写在 HTML 源码里,或通过innerHTML在关闭标签前一次性写入(但不推荐) - 例外情况:只有当
尚未开始解析(比如还没插入 DOM),你提前设置好innerHTML包含,再挂载,才可能被识别——但不可靠,不建议依赖
脚本控制字幕开关与语言切换的可靠方式
只要 已在初始 HTML 中声明,后续所有操作都可通过 video.textTracks API 安全控制。
-
textTracks是实时集合,包含所有已注册轨道(含默认禁用的) - 启用某条字幕:
track.mode = 'showing'(不是track.enabled = true,后者无效) - 关闭全部:
for (const t of video.textTracks) t.mode = 'disabled' - 按语言筛选:
const zhTrack = Array.from(video.textTracks).find(t => t.language === 'zh') - 监听变化:
video.textTracks.onaddtrack可捕获新轨道添加(如通过切换视频后触发),但对初始不触发
动态加载 .vtt 文件内容并注入字幕轨道(绕过 src 限制)
当字幕内容需运行时生成(如用户翻译、AI 实时转录),无法预置 src,可用 VTTCue + TextTrack 手动注入。
- 先获取或创建一个
TextTrack:const track = video.addTextTrack('subtitles', 'AI 字幕', 'zh') - 用
fetch('/api/transcribe')获取 WebVTT 字符串,用WebVTT.Parser(需 polyfill)或正则粗解析时间戳和文本 - 对每段内容新建
new VTTCue(startTime, endTime, text),调用track.addCue(cue) - 注意:手动添加的 cue 不会自动触发显示,需确保
track.mode = 'showing',且当前播放时间落入 cue 时间范围内 - 风险点:
VTTCue构造函数在旧版 Safari 中不支持;WebVTT.Parser非标准 API,需引入 vtt.js 或自行实现轻量解析器
容易被忽略的加载失败静默点
加载失败不会抛错,也不会出现在控制台,只能靠主动检查。
- 检查网络面板:确认
.vtt请求返回 200 且Content-Type: text/vtt(不是text/plain) - 检查 CORS:若
vtt与页面跨域,服务器必须返回Access-Control-Allow-Origin - 检查
video.textTracks.length是否为预期值;若为 0,说明根本没被注册 - 检查
track.readyState:0=not loaded, 1=loading, 2=loaded, 3=error —— 仅当为 2 时才能安全调用addCue或设mode - 调试技巧:在 DevTools 控制台执行
video.textTracks[0].cues,看是否为空;空则大概率是格式或 MIME 问题
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











