<video>: 视频嵌入元素

基线 广泛可用

此功能已得到良好建立,并在许多设备和浏览器版本中运行。它已在浏览器中提供,自 2015 年 7 月.

The <video> HTML 元素将支持视频回放的媒体播放器嵌入到文档中。您也可以使用 <video> 用于音频内容,但 <audio> 元素可能提供更适合的用户体验。

试一试

上面的示例展示了 <video> 元素的简单用法。类似于 <img> 元素,我们在 src 属性中包含要显示的媒体的路径;我们可以包含其他属性来指定信息,例如视频宽度和高度、是否要自动播放和循环,或者显示浏览器的默认视频控件等。

在不支持该元素的浏览器中,<video></video> 标记之间的内容将显示为回退。

属性

与所有其他 HTML 元素一样,此元素支持 全局属性

autoplay

布尔属性;如果指定,视频将在可以播放时立即自动开始播放,而不会停止以完成数据加载。

注意: 现代浏览器阻止音频(或带有未静音音频轨道的视频)自动播放,因为自动播放音频的网站可能对用户来说是一种不愉快的体验。有关如何正确使用自动播放的更多信息,请参阅我们的 自动播放指南

要禁用视频自动播放,autoplay="false" 将不起作用;如果属性存在于 <video> 标记中,则视频将自动播放。要删除自动播放,需要完全删除该属性。

controls

如果存在此属性,浏览器将提供控件,允许用户控制视频播放,包括音量、寻找和暂停/恢复播放。

controlslist

当指定 controlslist 属性时,它将帮助浏览器在浏览器显示其自己的控件集(即,当指定 controls 属性时)时选择要为 video 元素显示的控件。

允许的值为 nodownloadnofullscreennoremoteplayback

如果您想要禁用画中画模式(和控件),请使用 disablepictureinpicture 属性。

crossorigin

枚举 属性指示是否使用 CORS 来获取相关的视频。 启用 CORS 的资源 可在 <canvas> 元素中重复使用,而不会被污染。允许的值为

anonymous

发送没有凭据的跨域请求。换句话说,它发送 Origin: HTTP 标头,没有 cookie、X.509 证书或执行 HTTP 基本身份验证。如果服务器没有向源站点提供凭据(通过不设置 Access-Control-Allow-Origin: HTTP 标头),则资源将被污染,其使用将受到限制。

use-credentials

发送带有凭据的跨域请求。换句话说,它发送 Origin: HTTP 标头,带有 cookie、证书或执行 HTTP 基本身份验证。如果服务器没有通过 Access-Control-Allow-Credentials: HTTP 标头向源站点提供凭据,则资源将被污染,其使用将受到限制。

如果不存在,则在没有 CORS 请求的情况下获取资源(即不发送 Origin: HTTP 标头),从而防止其在 <canvas> 元素中被非污染使用。如果无效,则将其处理为使用枚举关键字 anonymous 的情况。有关更多信息,请参阅 CORS 设置属性

disablepictureinpicture

防止浏览器建议使用画中画上下文菜单或在某些情况下自动请求画中画。

disableremoteplayback

布尔属性,用于禁用通过有线(HDMI、DVI 等)和无线技术(Miracast、Chromecast、DLNA、AirPlay 等)连接的设备中的远程播放功能。

在 Safari 中,您可以使用 x-webkit-airplay="deny" 作为回退。

height

视频显示区域的高度,单位为 CSS 像素(仅绝对值;不包含百分比)。

循环

布尔属性;如果指定,浏览器将在视频结束时自动返回到开头。

静音

布尔属性,指示视频中包含的默认音频静音设置。如果设置,音频将最初静音。其默认值为 false,这意味着视频播放时音频将播放。

内联播放

布尔属性,指示视频应“内联”播放,即在元素的播放区域内播放。请注意,没有此属性 *不* 意味着视频将始终在全屏模式下播放。

海报

视频下载时显示的图像的 URL。如果没有指定此属性,则在第一个帧可用之前不会显示任何内容,然后第一个帧将作为海报帧显示。

预加载

枚举 属性旨在为浏览器提供关于作者认为在视频播放之前加载哪些内容会导致最佳用户体验的提示。它可以具有以下值之一

  • none: 指示不应预加载视频。
  • metadata: 指示仅获取视频元数据(例如,长度)。
  • auto: 指示可以下载整个视频文件,即使用户预计不会使用它。
  • 空字符串: auto 值的同义词。

默认值因浏览器而异。规范建议将其设置为 metadata

注意

  • autoplay 属性优先于 preload。如果指定了 autoplay,浏览器显然需要开始下载视频以进行播放。
  • 规范不要求浏览器遵循此属性的值;它只是一个提示。
来源

要嵌入的视频的 URL。这是可选的;您也可以使用 <source> 元素在视频块中指定要嵌入的视频。

宽度

视频显示区域的宽度,单位为 CSS 像素(仅绝对值;不包含百分比)。

事件

事件名称 触发时机
audioprocess 已弃用 ScriptProcessorNode 的输入缓冲区已准备好进行处理。
可以播放 浏览器可以播放媒体,但估计加载的数据不足以播放媒体到结束,而不会因进一步缓冲内容而停止。
可以流畅播放 浏览器估计可以播放媒体到结束,而不会因内容缓冲而停止。
完成 OfflineAudioContext 的渲染已终止。
持续时间更改 duration 属性已更新。
清空 媒体已变为空;例如,如果媒体已加载(或部分加载),并且调用了 load() 方法以重新加载它,则会发送此事件。
结束 由于到达媒体结尾,播放已停止。
错误 获取媒体数据时发生错误,或者资源类型不是支持的媒体格式。
数据已加载 媒体的第一帧已加载完毕。
元数据已加载 元数据已加载。
加载开始 当浏览器开始加载资源时触发。
暂停 播放已暂停。
播放 播放已开始。
正在播放 播放已准备好开始,之前由于数据不足而暂停或延迟。
进度 当浏览器加载资源时定期触发。
速率更改 播放速率已更改。
已搜索 搜索 操作已完成。
正在搜索 搜索 操作已开始。
停顿 用户代理正在尝试获取媒体数据,但数据意外地没有出现。
暂停 媒体数据加载已暂停。
时间更新 currentTime 属性指示的时间已更新。
音量更改 音量已更改。
等待 由于临时缺乏数据,播放已停止。

使用说明

浏览器并不都支持相同的视频格式;您可以在嵌套的 <source> 元素中提供多个来源,然后浏览器将使用它理解的第一个来源。

html
<video controls>
  <source src="myVideo.webm" type="video/webm" />
  <source src="myVideo.mp4" type="video/mp4" />
  <p>
    Your browser doesn't support HTML video. Here is a
    <a href="myVideo.mp4" download="myVideo.mp4">link to the video</a> instead.
  </p>
</video>

我们提供了关于媒体文件类型和 媒体类型和格式指南 以及 支持的视频编解码器指南 的全面而深入的指南。此外,还提供了一个关于 音频编解码器 的指南,这些编解码器可与它们一起使用。

其他使用注意事项

  • 如果您没有指定 controls 属性,视频将不包含浏览器的默认控件;您可以使用 JavaScript 和 HTMLMediaElement API 创建自己的自定义控件。有关更多详细信息,请参见 创建跨浏览器视频播放器
  • 为了允许对您的视频(和音频)内容进行精确控制,HTMLMediaElement 会触发许多不同的 事件。除了提供可控性之外,这些事件还允许您监控媒体下载和播放的进度,以及播放状态和位置。
  • 您可以使用 object-position 属性调整视频在元素框架内的位置,并使用 object-fit 属性控制视频的大小如何调整以适合框架。
  • 要在视频中显示字幕/字幕,您可以使用一些 JavaScript 以及 <track> 元素和 WebVTT 格式。有关更多信息,请参见 向 HTML 视频添加字幕和字幕
  • 您可以使用 <video> 元素播放音频文件。例如,如果您需要使用 WebVTT 脚本执行音频,这将很有用,因为 <audio> 元素不允许使用 WebVTT 添加字幕。
  • 要测试支持该元素的浏览器的回退内容,您可以将 <video> 替换为一个不存在的元素,例如 <notavideo>

有关使用 HTML <video> 的一般信息来源是 视频和音频内容 初学者教程。

使用 CSS 样式

<video> 元素是一个替换元素——它的 display 值默认为 inline——但它在视窗中的默认宽度和高度由嵌入的视频定义。

<video> 进行样式设置没有特殊考虑;一个常见的策略是为它提供 display 值为 block,以使其更容易定位、调整大小等,然后根据需要提供样式和布局信息。 视频播放器样式设置基础 提供了一些有用的样式设置技巧。

添加字幕和其他定时文本轨道

用于字幕、隐藏字幕、章节标题等的定时文本轨道可以通过嵌套 <track> 元素声明性地添加。轨道以 Web 视频文本轨道文件格式 (WebVTT).vtt 文件)指定。

例如,以下 HTML 包含文件 "captions.vtt",如果用户启用了字幕,该文件将用于在视频上叠加隐藏字幕。

html
<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" />
</video>

也可以使用 WebVTT API 以编程方式添加定时文本轨道。

检测轨道添加和删除

您可以使用 addtrackremovetrack 事件来检测何时将轨道添加到 <video> 元素中以及何时从 <video> 元素中删除轨道。但是,这些事件不会直接发送到 <video> 元素本身。相反,它们会发送到 <video> 元素的 HTMLMediaElement 中的轨道列表对象,该对象对应于添加到元素的轨道类型

HTMLMediaElement.audioTracks

一个 AudioTrackList,包含媒体元素的所有音频轨道。为该对象添加一个 addtrack 监听器,以便在将新的音频轨道添加到元素时收到通知。

HTMLMediaElement.videoTracks

一个 VideoTrackList,包含媒体元素的所有视频轨道。为该对象添加一个 addtrack 监听器,以便在将视频轨道添加到元素时收到通知。

HTMLMediaElement.textTracks

一个 TextTrackList,包含媒体元素的所有文本轨道(用于字幕、隐藏字幕等)。为该对象添加一个 addtrack 监听器,以便在将文本轨道添加到元素时收到通知。

例如,要检测何时将音频轨道添加到 <video> 元素中或从 <video> 元素中删除,您可以使用以下代码

js
const elem = document.querySelector("video");

elem.audioTracks.onaddtrack = (event) => {
  trackEditor.addTrack(event.track);
};

elem.audioTracks.onremovetrack = (event) => {
  trackEditor.removeTrack(event.track);
};

此代码监听音频轨道被添加到元素中和从元素中删除,并在轨道编辑器上调用一个假设的函数来注册和删除轨道编辑器中可用轨道列表中的轨道。

您也可以使用 addEventListener() 来监听 addtrackremovetrack 事件。

服务器对视频的支持

如果服务器上的视频 MIME 类型设置不正确,视频可能不会显示,或者显示一个包含 X 的灰色框(如果启用了 JavaScript)。

如果您使用 Apache Web Server 来提供 WebM 视频,您可以通过将视频文件类型扩展名添加到 video/webm MIME 类型(最常见的 WebM 文件扩展名是 .webm)来解决此问题。为此,请编辑 /etc/apache 中的 mime.types 文件或在 httpd.conf 中使用 AddType 配置指令

AddType video/webm .webm

您的网站托管商可能会为新技术提供用于 MIME 类型配置更改的简单界面,直到自然发生全局更新。

无障碍性

视频应提供字幕和准确描述其内容的脚本(有关如何实施这些内容,请参阅 向 HTML 视频添加字幕和字幕)。字幕使听力障碍者能够在视频播放时理解视频的音频内容,而脚本使需要额外时间的人能够以对他们来说舒适的速度和格式查看音频内容。

值得注意的是,虽然您可以为纯音频媒体添加字幕,但您只能在 <video> 元素中播放音频时这样做,因为该元素的视频区域用于显示字幕。这是在视频元素中播放音频有用的特殊情况之一。

如果使用自动字幕服务,重要的是要查看生成的内容以确保它准确地反映源视频。

除了口语对话之外,字幕和脚本还应识别传达重要信息的音乐和音效。这包括情感和语气

14
00:03:14 --> 00:03:18
[Dramatic rock music]

15
00:03:19 --> 00:03:21
[whispering] What's that off in the distance?

16
00:03:22 --> 00:03:24
It's… it's a…

16 00:03:25 --> 00:03:32
[Loud thumping]
[Dishes clattering]

字幕不应遮挡视频的主要主题。可以使用 align VTT 提示设置 对其进行定位。

示例

单一来源

此示例在激活时播放视频,为用户提供浏览器的默认视频控件来控制播放。

HTML

html
<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a>
  and watch it with your favorite video player!
</video>

结果

在视频开始播放之前,poster 属性中提供的图像将显示在它所在的位置。如果浏览器不支持视频播放,它将显示回退文本。

多个来源

此示例基于最后一个示例,提供了三种不同的媒体来源;这允许观看视频,无论浏览器支持哪些视频编解码器。

HTML

html
<!-- Using multiple sources as fallbacks for a video tag -->
<!-- 'Elephants Dream' by Orange Open Movie Project Studio, licensed under CC-3.0, hosted by archive.org -->
<!-- Poster hosted by Wikimedia -->
<video
  width="620"
  controls
  poster="https://upload.wikimedia.org/wikipedia/commons/e/e8/Elephants_Dream_s5_both.jpg">
  <source
    src="https://archive.org/download/ElephantsDream/ed_hd.avi"
    type="video/avi" />
  <source
    src="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    type="video/mp4" />

  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a
    href="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    download="ed_1024_512kb.mp4">
    download the MP4
  </a>
  and watch it with your favorite video player!
</video>

结果

首先尝试使用 AVI。如果无法播放,则尝试使用 MP4。如果视频元素不受支持,将显示回退消息,但如果所有来源都失败,则不会显示。

某些媒体文件类型允许您使用 codecs 参数(作为文件类型字符串的一部分)提供更具体的信息。一个相对简单的示例是 video/webm; codecs="vp8, vorbis",它表示该文件是使用 WebM 视频(使用 VP8 用于视频,Vorbis 用于音频)的视频。

技术摘要

内容类别 流动内容、短语内容、嵌入内容。如果它具有 controls 属性:交互式内容和可感知内容。
允许的内容

如果元素具有 src 属性:零个或多个 <track> 元素,后面跟不包含媒体元素的透明内容——即不包含 <audio><video>

否则:零个或多个 <source> 元素,后面跟零个或多个 <track> 元素,后面跟不包含媒体元素的透明内容——即不包含 <audio><video>

标签省略 无,开始和结束标签都是必需的。
允许的父级 任何接受嵌入内容的元素。
隐式 ARIA 角色 没有相应的角色
允许的 ARIA 角色 application
DOM 接口 HTMLVideoElement

规范

规范
HTML 标准
# the-video-element

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅