动态创建 track 元素必须作为 audio/video 子元素存在,且需在 src 设置后或 loadedmetadata 事件后添加;必须用 createElement 创建并显式设置 kind、src、srclang;src 需同源或配置 CORS;仅 subtitles/captions 支持 UI 切换,default 属性不保证自动显示。

动态创建 track 元素必须配合 audio 或 video 父节点
单独创建 track 并插入 document.body 是无效的——浏览器会忽略它。它必须作为 audio 或 video 的子元素存在,且需在媒体元素加载元数据后(loadedmetadata 事件之后)或至少在 src 设置之后再添加,否则多数浏览器不触发字幕/描述渲染。
-
track不能靠innerHTML字符串注入生效(如video.innerHTML += '<track kind="subtitles" ...>'</track>),必须用document.createElement('track') - 必须显式设置
kind、src、srclang(若kind="subtitles"或"descriptions")三个属性,缺一不可 -
src必须是同源 URL 或已配置 CORS;跨域 VTT 文件若未带crossorigin属性,会静默失败
track 的 kind 值决定行为,不是所有值都支持 UI 切换
常见 kind 值中,只有 "subtitles" 和 "captions" 会在控件栏显示语言切换菜单;"descriptions"、"chapters"、"metadata" 不出现 UI,但 JS 仍可监听其时间更新(如 cuechange 事件)。
-
kind="subtitles":面向听力正常用户的翻译字幕,通常默认关闭 -
kind="captions":面向听障用户的同步字幕(含音效说明),部分浏览器默认启用 -
kind="descriptions":音频描述轨道,仅在辅助技术启用时激活,普通播放器不显示 - 设置
default属性仅对subtitles/captions有效;设了也未必自动启用——取决于用户系统偏好和浏览器策略
脚本插入顺序错误会导致 track 不加载
典型失败流程:video 元素已存在 → 直接 appendChild(track) → 但 video.src 还没设或尚未触发 load() → track 被忽略。正确时机有且仅有两种:
- 在设置
video.src后,监听loadedmetadata,再 appendtrack - 先创建
track并 append 到空video,再设src(此时 track 会被纳入加载流程)
示例关键代码:
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记(深入)”;
const video = document.getElementById('myVideo');
const track = document.createElement('track');
track.kind = 'subtitles';
track.src = 'zh.vtt';
track.srclang = 'zh';
track.label = '中文';
// ✅ 正确:先 append 再设 src
video.appendChild(track);
video.src = 'movie.mp4'; // 触发 track 加载
调试 track 是否生效的三个检查点
看不到字幕?别只查 HTML 结构,重点看运行时状态:
- 检查
video.textTracks.length—— 应 ≥1;若为 0,说明track未被识别或未挂载成功 - 检查
video.textTracks[0].mode—— 有效值为"disabled"、"hidden"、"showing";设default不等于自动"showing" - 用
video.textTracks[0].cues查看是否解析出 Cue 对象;若为null或空列表,说明 VTT 文件 404、格式错误或 CORS 拒绝
VTT 文件首行必须是 WEBVTT(严格大小写),且需以 UTF-8 无 BOM 编码保存;任何格式偏差都会导致 cues 为空。


















