网页视频用Track API动态控制字幕的核心是操作textTracks列表中轨道的mode属性;需确保track元素正确声明、srclang为标准语言码、src可访问;切换时仅一个轨道设为"showing",其余"disabled";支持onaddtrack和oncuechange事件监听及动态addTextTrack添加。

网页视频用 Track API 动态控制字幕,核心是操作 textTracks 列表中每个轨道的 mode 属性,而不是修改 HTML 或重新加载文件。浏览器原生支持这一机制,无需第三方库。
确保 track 元素已正确声明
多个 <track></track> 必须作为 <video></video> 的直接子元素,且位于所有 <source></source> 之后:
-
kind="subtitles"不可省略,不能写成caption或漏掉 -
srclang必须是标准语言码(如zh、en-US),这是 JS 匹配的唯一依据 -
label用于菜单显示,不影响逻辑,但建议写清楚(如“中文(简体)”) -
src必须为可访问的相对或绝对 URL,不支持 Blob URL
用 JavaScript 切换当前激活字幕
通过遍历 video.textTracks,将目标轨道设为 "showing",其余设为 "disabled":
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
- 每次只允许一个字幕轨道处于
"showing"状态 -
"disabled"表示彻底关闭(不解析、不触发事件);"hidden"仍会解析但不显示,一般不用 - 切换后浏览器自动渲染对应时间点的字幕,无需手动同步时间轴
示例函数:
<script><br> function switchTo(lang) {<br> const tracks = video.textTracks;<br> for (let t of tracks) {<br> if (t.kind === 'subtitles') {<br> t.mode = t.srclang === lang ? 'showing' : 'disabled';<br> }<br> }<br> }<br> switchTo('en'); // 切到英文<br> </script>监听字幕状态变化与用户交互
增强体验需结合事件响应:
-
video.textTracks.onaddtrack:捕获动态添加的轨道(如接口返回字幕地址后调用addTextTrack()) -
track.oncuechange:当前激活轨道更新字幕块时触发,适合高亮当前句或记录观看进度 - 实时检查
track.mode === 'showing'可同步 UI 按钮选中状态 - 不要轮询
track.readyState,VTT 加载完成会自动触发load事件
动态添加字幕轨道(非预置情况)
当字幕 URL 来自接口或需运行时生成时:
- 调用
video.addTextTrack('subtitles', '临时名称', 'zh')创建空轨道 - 用
fetch获取 VTT 文本,解析后逐条调用track.addCue(cue) - 最后设
track.mode = 'showing'启用,不能改src属性 - 注意:动态轨道默认
mode = 'disabled',且不支持src赋值

















