HTML5的play()不处理字幕,字幕显示需依赖正确配置的元素、loadedmetadata事件后设置track.mode="showing",以及符合规范的VTT文件和浏览器环境支持。

HTML5 play() 本身不处理字幕
直接调用 play() 不会自动加载或显示字幕。字幕支持依赖 元素和正确的媒体资源准备,不是 play() 的功能延伸。很多开发者误以为调用 play() 后字幕“应该跟着出来”,结果发现空白或报错——问题通常出在轨道未就绪或未启用。
必须在 play() 前挂载且 kind="subtitles"
浏览器只识别 kind="subtitles"(或 "captions")的 ,且必须作为 的子元素存在、src 可访问、srclang 明确。常见漏点:
-
写在外面,或动态 append 但没等load事件就调play() -
src是相对路径,但当前页面 URL 有 hash 或 query,导致 CORS 或 404 - 遗漏
default属性,或没手动设置track.mode = "showing"
示例正确结构:
字幕显示需等 loadedmetadata 后操作 track.mode
play() 调用前或后立刻设 track.mode 很可能失败,因为轨道元数据还没加载完。可靠做法是监听 loadedmetadata 或 canplay,再启用字幕:
立即学习“前端免费学习笔记(深入)”;
const v = document.getElementById('v');
const track = v.textTracks[0];
v.addEventListener('loadedmetadata', () => {
if (track) track.mode = 'showing'; // 必须是 'showing',不是 'enabled'
});
注意:textTracks[0] 是动态集合,需确保 已解析;若多个轨道,需按 kind 和 srclang 筛选;mode 只接受 "disabled" / "hidden" / "showing",写错值无效果。
VTT 文件格式错误会导致字幕静默失败
浏览器对 WebVTT 格式极其敏感:首行必须是 WEBVTT(无空格、大小写敏感),时间戳格式必须为 HH:MM:SS.mmm --> HH:MM:SS.mmm,且每段之间空一行。常见静默失败原因:
- 用记事本保存 VTT 导致 BOM 头(改用 VS Code / Sublime 并存为 UTF-8 no BOM)
- 时间戳里用了中文冒号或全角空格
- 文件后缀是
.txt但服务器返回text/plainMIME 类型(需配服务器返回text/vtt)
可在浏览器 Network 面板检查 VTT 请求是否 200、Response 是否以 WEBVTT 开头、无乱码。
textTracks 和渲染层,play() 只是触发播放流程的开关。最容易被忽略的是:即使一切配置正确,如果用户设备禁用了字幕(如系统辅助功能关闭字幕渲染),track.mode = "showing" 也会被浏览器忽略——这时没有错误,也没有提示。










