大网数据广告活动
Web 标准与前端开发

<track>:嵌入文本轨元素

· 52CE 我爱测

**`<track>`** HTML 元素作为媒体元素 audio 和 video 的子元素使用。每个文本轨元素允许你指定一个定时文本轨(或基于时间的数据),可以与媒体元素并行显示,例如在视频上叠加字幕或隐藏式字幕,或与音频轨一起显示。

<track> HTML 元素作为媒体元素 audio 和 video 的子元素使用。每个文本轨元素允许你指定一个定时文本轨(或基于时间的数据),可以与媒体元素并行显示,例如在视频上叠加字幕或隐藏式字幕,或与音频轨一起显示。

可以为一个媒体元素指定多个轨道,包含不同种类的定时文本数据,或为不同区域翻译的定时文本数据。使用的数据将是已设置为默认的轨道,或者基于用户偏好的类型和语言翻译。

轨道格式为 WebVTT 格式(.vtt 文件)——Web 视频文本轨。

HTML Demo: <track>

<video controls src="/shared-assets/videos/friday.mp4">
  <track
    default
    kind="captions"
    srclang="en"
    src="/shared-assets/misc/friday.vtt" />
  Download the
  <a href="/shared-assets/videos/friday.mp4">MP4</a>
  video, and
  <a href="/shared-assets/misc/friday.vtt">subtitles</a>.
</video>
video {
  width: 250px;
}

video::cue {
  font-size: 1rem;
}

属性

此元素包含全局属性。

  • default

    • : 此属性表示应启用该轨道,除非用户的偏好表明另一个轨道更合适。每个媒体元素只能在一个 track 元素上使用此属性。
  • kind

    • : 文本轨的使用方式。如果省略,默认的类型是 subtitles。如果属性包含无效值,则会使用 metadata。允许使用以下关键字:
      • subtitles

        • 字幕提供观众无法理解的内容的翻译。例如在英语电影中,非英语的语言或文本。
        • 字幕可能包含额外的内容,通常是额外的背景信息。例如《星球大战》电影开头的文字,或场景的日期、时间和地点。
      • captions

        • 隐藏式字幕提供音频的文字记录,并可能包含翻译。
        • 它可能包含重要的非语言信息,例如音乐提示或音效。它可能表示提示的来源(例如音乐、文本、角色)。
        • 适合听力障碍用户或当声音被静音时使用。
      • chapters

        • 章节标题用于用户浏览媒体资源时使用。
      • metadata

        • 由脚本元素使用的轨道。对用户不可见。
  • label

    • : 用户可读的文本轨标题,浏览器在列出可用文本轨时使用。
  • src

    • : 轨道(.vtt 文件)的地址。必须是一个有效的 URL。必须指定此属性,并且其 URL 值必须与文档具有相同的来源——除非 track 元素的父元素 audio 或 video 有 crossorigin 属性。
  • srclang

    • : 轨道文本数据的语言。它必须是一个有效的 BCP 47 语言标签。如果 kind 属性设置为 subtitles,则必须定义 srclang。

使用说明

轨道数据类型

track 添加到媒体中的数据类型由 kind 属性设置,该属性可以取值 subtitles、captions、chapters 或 metadata。该元素指向一个包含定时文本的源文件,当用户请求附加数据时,浏览器会暴露该文件。

一个媒体元素不能有多个具有相同 kind、srclang 和 label 的 track。

检测提示的变化

每当显示的提示(cue)发生变化时,由 HTMLTrackElement.track 属性表示的底层 TextTrack 都会接收到一个 cuechange 事件。即使轨道未关联媒体元素,也会发生这种情况。

如果轨道与媒体元素关联,并且 <track> 元素作为 audio 或 video 元素的子元素使用,则 cuechange 事件也会发送到 HTMLTrackElement。

let textTrackElem = document.getElementById("text-track");

textTrackElem.addEventListener("cuechange", (event) => {
  let cues = event.target.track.activeCues;
});

以编程方式添加文本轨

表示 <track> 元素的 JavaScript 接口是 HTMLTrackElement。与元素关联的文本轨可以通过 HTMLTrackElement.track 属性获取,其类型为 TextTrack。

TextTrack 对象也可以使用 HTMLMediaElement.addTextTrack() 方法添加到 HTMLVideoElement 或 HTMLAudioElement。与媒体元素关联的 TextTrack 对象存储在 TextTrackList 中,可以通过 HTMLMediaElement.textTracks 属性获取。

示例

<video controls poster="/images/sample.gif">
  <source src="sample.mp4" type="video/mp4" />
  <source src="sample.ogv" type="video/ogv" />
  <track kind="captions" src="sampleCaptions.vtt" srclang="zh" />
  <track kind="chapters" src="sampleChapters.vtt" srclang="zh" />
  <track kind="subtitles" src="sampleSubtitles_de.vtt" srclang="de" />
  <track kind="subtitles" src="sampleSubtitles_en.vtt" srclang="en" />
  <track kind="subtitles" src="sampleSubtitles_ja.vtt" srclang="ja" />
  <track kind="subtitles" src="sampleSubtitles_oz.vtt" srclang="oz" />
  <track kind="metadata" src="keyStage1.vtt" srclang="zh" label="第 1 阶段" />
  <track kind="metadata" src="keyStage2.vtt" srclang="zh" label="第 2 阶段" />
  <track kind="metadata" src="keyStage3.vtt" srclang="zh" label="第 3 阶段" />
  
  …
</video>

技术概要

<table class="properties"> <tbody> <tr> <th scope="row"> <a href="/zh-CN/docs/Web/HTML/Guides/Content_categories">内容分类</a> </th> <td>无</td> </tr> <tr> <th scope="row">允许的内容</th> <td>无;它是void element。</td> </tr> <tr> <th scope="row">标签省略</th> <td>必须有开始标签,且不能有结束标签。</td> </tr> <tr> <th scope="row">允许的父元素</th> <td> <p> 媒体元素,audio 或 video。 </p> </td> </tr> <tr> <th scope="row">隐含的 ARIA 角色</th> <td> <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">没有对应的角色</a> </td> </tr> <tr> <th scope="row">允许的 ARIA 角色</th> <td>没有允许的 <code>role</code></td> </tr> <tr> <th scope="row">DOM 接口</th> <td>HTMLTrackElement</td> </tr> </tbody> </table>

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。