全屏 API 指南

激活全屏模式

对于您希望以全屏模式显示的元素（例如 <video> 元素），您可以通过调用其 requestFullscreen() 方法将其置于全屏模式。

让我们考虑这个 <video> 元素

<video controls id="my-video">
  <source src="somevideo.webm" />
  <source src="somevideo.mp4" />
</video>

我们可以如下将该视频置于全屏模式：

const elem = document.getElementById("my-video");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}

此代码在调用 requestFullscreen() 方法之前会检查该方法的存在性。

一旦元素进入全屏模式，它就会被 :fullscreen 匹配，这会为其提供一些默认样式，例如占据整个屏幕。它还会被放置在顶层。

如果同时请求多个元素进入全屏模式，它们都会被 :fullscreen 匹配，并都位于顶层。它们会堆叠在一起，最近请求的元素会覆盖较旧的元素。最近请求的元素会被显示，并且可以通过 Document.fullscreenElement 获取。

Notification

当全屏模式成功激活时，包含该元素的文档会接收一个 fullscreenchange 事件。当退出全屏模式时，文档会再次接收一个 fullscreenchange 事件。请注意，fullscreenchange 事件本身不会提供有关文档是进入还是退出全屏模式的任何信息，但如果文档具有非空的 fullscreenElement，您就知道它处于全屏模式。

全屏请求失败时

不能保证您能够切换到全屏模式。例如，<iframe> 元素需要设置 allowfullscreen 属性才能选择允许其内容显示在全屏模式下。此外，某些类型的内容，例如窗口化插件，无法以全屏模式显示。尝试将无法以全屏模式显示（或此类元素的父元素或子元素）的元素置于全屏模式将不起作用。相反，请求全屏的元素将接收一个 fullscreenerror 事件。当全屏请求失败时，Firefox 会在 Web 控制台中记录一条错误消息，解释请求失败的原因。然而，在 Chrome 和较新版本的 Opera 中，不会生成此类警告。

退出全屏模式

用户始终可以自行决定退出全屏模式；请参阅您的用户想知道的事情。您也可以通过调用 Document.exitFullscreen() 方法来以编程方式退出。

如果多个元素处于全屏模式，调用 exitFullscreen() 只会退出最顶层的元素，显示它下面的下一个元素。按下 Esc 或 F11 将退出所有全屏元素。

其他信息

Document 提供了一些额外的、在开发全屏 Web 应用程序时可能很有用的信息。

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement 属性会告诉您当前正在全屏显示的Element。如果此值为非 null，则文档（或 shadow DOM）处于全屏模式。如果此值为 null，则文档（或 shadow DOM）未处于全屏模式。

Document.fullscreenEnabled

fullscreenEnabled 属性会告诉您文档当前是否处于允许请求全屏模式的状态。

移动浏览器中的视口缩放

某些移动浏览器在全屏模式下会忽略视口 meta 标签设置并阻止用户缩放；例如：在全屏模式下显示的页面上，“捏合缩放”手势可能不起作用——即使在非全屏模式下，页面也可以通过捏合缩放进行缩放。

您的用户想知道的事情

您应该确保告知用户他们可以通过按 Esc 键（或 F11）退出全屏模式。

此外，在全屏模式下导航到其他页面、切换标签页或切换到其他应用程序（例如使用 Alt-Tab）也会退出全屏模式。

示例

mdn/dom-examples GitHub 仓库 包含全屏 API 的完整示例。

运行示例并浏览源代码。

规范

浏览器兼容性

api.Document.fullscreenEnabled

api.Document.fullscreen

另见

• 使用全屏模式
• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen