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

TextTrack: mode property

· 52CE 我爱测

The TextTrack interface's **`mode`** property is a string specifying and controlling the text track's mode: `disabled`, `hidden`, or `showing`. You can read this value to determine the current mode, and you can change this value to switch modes.

WebVTT

The TextTrack interface's mode property is a string specifying and controlling the text track's mode: disabled, hidden, or showing. You can read this value to determine the current mode, and you can change this value to switch modes.

Safari additionally requires the default boolean attribute to be set to true when implementing your own video player controls in order for the subtitles cues to be shown.

Value

A string which indicates the track's current mode. One of:

  • disabled
    • : The text track is currently disabled. While the track's presence is exposed in the DOM, the user agent is otherwise ignoring it. No cues are active, no events are being fired, and the user agent won't attempt to obtain the track's cues. This is the default value, unless the text track has the default Boolean attribute is specified, in which case the default is showing.
  • hidden
    • : The text track is currently active but the cues aren't being displayed. If the user agent hasn't tried to obtain the track's cues yet, it will do so soon (thereby populating the track's TextTrack.cues property). The user agent is keeping a list of the active cues (in the track's TextTrack.activeCues property) and events are being fired at the corresponding times, even though the text isn't being displayed.
  • showing
    • : The text track is currently enabled and is visible. If the track's cues list hasn't been obtained yet, it will be soon. The TextTrack.activeCues list is being maintained and events are firing at the appropriate times; the track's text is also being drawn appropriately based on the styling and the track's TextTrack.kind. This is the default value if the text track's default Boolean attribute is specified.

Usage notes

The default mode is disabled, unless the default Boolean attribute is specified, in which case the default mode is showing. When a text track is loaded in the disabled state, the corresponding WebVTT file is not loaded until the state changes to either showing or hidden. This way, the resource fetch and memory usage are avoided unless the cues are actually needed.

However, that means that if you wish to perform any actions involving the track's cues while handling, for example, the Window/load_event event—in order to process some aspect of the cues upon page load—and the track mode was initially disabled, you'll have to change the mode to either hidden or showing in order to trigger loading of the cues.

When the mode is showing, text tracks are performed. The exact appearance and manner of that performance varies depending on each text track's TextTrack.kind. In general:

  • Tracks whose kind is "subtitles" or "captions" are rendered with the cues overlaid over the top of the video.
  • Tracks whose kind is "descriptions" are presented in a non-visual form (for example, the text might be spoken to describe the action in the video).
  • Tracks whose kind is "chapters" are used by the user agent or the website or web app to construct and present an interface for navigating the named chapters, where each cue in the list represents a chapter in the media. The user can then navigate to the desired chapter, which begins at the cue's start position and ends at the cue's end position.

Example

In this example, we configure the text track's cues so that every time a cue is finished, the video automatically pauses playback. This is done by setting the TextTrackCue.pauseOnExit property on each cue to true. However, to ensure that the track's cues are available, we first set mode to showing.

let trackElem = document.querySelector("track");
let track = trackElem.track;

track.mode = "showing";

for (const cue of track.cues) {
  cue.pauseOnExit = true;
}

Specifications

Browser compatibility

See also

  • WebVTT
  • TextTrack
  • TextTrackList
  • TextTrackCueList
  • VTTCue
  • track
  • HTMLTrackElement

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

资料来源与适用范围

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

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

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