Fullscreen API - 添加了在全屏模式下展示特定元素的方法

Fullscreen API 添加了在全屏模式下展示特定 Element（及其后代）的方法，并在不再需要时退出全屏模式。这使得可以使用用户的整个屏幕来呈现所需的内容（例如在线游戏），在全屏模式关闭之前，将所有的浏览器用户界面元素和其他应用程序从屏幕上移除。

有关如何使用 API 的详细信息，请参阅文章全屏 API 指南。

注意： 对该 API 的支持因浏览器而异，许多浏览器需要供应商前缀和 / 或未实现最新规范。有关此 API 支持的详细信息，请参阅下面的浏览器兼容性部分。您可能希望考虑使用诸如 Fscreen 之类的，与浏览器无关的库来实现对 Fullscreen API。

接口

全屏 API 没有自己的接口。相反，它增强了其他几个接口来增加提供全屏功能所需的方法、属性和事件处理程序。以下部分列出了这些内容。

方法

全屏 API 向 Document 和 Element 接口添加了方法，以允许关闭和打开全屏模式。

Document 接口上的方法

Document.exitFullscreen()

请求用户代理从全屏模式切换回窗口模式。返回一个 Promise ，它在全屏模式完全关闭后解析。

Element 接口上的方法

Element.requestFullscreen()

要求用户代理将指定元素（以及其后代）置于全屏模式，从屏幕上移除所有浏览器的 UI 元素以及所有其他应用程序。返回一个 Promise ，一旦全屏模式被激活，它就会被解析。

属性

Document 接口提供的属性可用于确定是否支持和可用全屏模式，以及全屏模式当前是否处于活动状态，哪个元素正在使用屏幕。

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement 属性告诉您当前在 DOM（或 shadow DOM）上以全屏模式显示的 Element。如果它是 null，则文档（或 shadow DOM）不处于全屏模式。

document.fullscreenEnabled

fullscreenEnabled 属性告诉您是否可以使用全屏模式。如果由于任何原因全屏模式不可用（例如不允许使用 "fullscreen" 功能，或不支持全屏模式），则它是 false。

事件处理程序

Fullscreen API 定义了两个事件，可用于检测全屏模式何时开启和关闭，以及在全屏模式和窗口模式之间切换的过程中何时发生错误。这些事件的事件处理程序在 Document 和 Element 接口上可用。

注意： 这些事件处理程序属性不可用作 HTML 内容属性。换句话说，您不能在 HTML 内容中为 fullscreenchange 和 fullscreenerror 指定事件处理程序。它们必须通过 JavaScript 代码添加。

文档上的事件处理程序

Document.onfullscreenchange

fullscreenchange 事件的事件处理程序，当文档中的任何 Element 被放入全屏模式或退出全屏模式时冒泡到 Document。

Document.onfullscreenerror

fullscreenerror 事件的事件处理程序，，当文档中的任何 Element 尝试启用或禁用全屏模式时发生错误时, 该事件会冒泡到 Document。

元素上的事件处理程序

Element.onfullscreenchange

当 fullscreenchange 事件发送到元素时调用的事件处理程序，指示该元素已置于全屏模式或从全屏模式中移除。

Element.onfullscreenerror

fullscreenerror 事件的事件处理程序，当发送到在进入或退出全屏模式时遇到错误的元素时。

过时的属性

Document.fullscreen

一个布尔值，如果文档有当前以全屏模式显示的元素，则为 true；否则为 false。注意： 使用 fullscreenElement 属性在 Document 或 ShadowRoot 代替；如果它不是 false，那么它是一个当前以全屏模式显示的 Element。

注意：请改用 Document 或 ShadowRoot 上的 fullscreenElement 属性；如果它不为 null，则它是当前以全屏模式显示的 Element。

事件

Fullscreen API 定义了两个事件，可用于检测全屏模式何时打开和关闭，以及在全屏模式和窗口模式之间切换的过程中何时发生错误。

fullscreenchange

当它进入或退出全屏模式时发送到 Element。

fullscreenerror

如果在尝试将其切换到或切换出全屏模式时发生错误，则发送到 Element。

字典

FullscreenOptions

提供您可以在调用 requestFullscreen() 时指定的可选设置。

控制访问

可以使用 Feature Policy 控制是否可用全屏模式。全屏模式功能由字符串 "fullscreen" 标识，默认允许列表值为 "self"，这意味着在顶级文档上下文中，以及从与最顶层文档相同的来源加载的嵌套浏览上下文允许全屏模式。

请参阅 使用功能策略 以了解有关使用功能策略控制对 API 的访问的更多信息。

使用说明

用户可以选择按 ESC（或 F11）键退出全屏模式，而不是等待网站或应用程序以编程方式退出。确保在用户界面的某处提供适当的用户界面元素，通知用户此选项可供他们使用。

注意： 使用任何应用程序切换器（或 Alt - Tab ）导航到另一个页面、更改选项卡或切换到另一个应用程序同样会退出全屏模式。

实例

简单的全屏使用

在此实例中，视频显示在网页中。按 Enter 键可以让用户在视频的窗口和全屏演示之间切换。

查看在线实例

监听回车键

加载页面时，运行此代码以设置事件侦听器以监听 Enter 键。

document.addEventListener("keypress", function(e) {
  if (e.keyCode === 13) {
    toggleFullScreen();
  }
}, false);

切换全屏模式

当用户按下 Enter 键时，上面的事件处理程序会调用此代码。

function toggleFullScreen() {
  if (!document.fullscreenElement) {
      document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}

首先查看 document 的 fullscreenElement 属性的值。在实际部署中，此时，您需要检查它的前缀版本（例如，mozFullScreenElement、msFullscreenElement 或 webkitFullscreenElement）。如果值为 null，则文档当前处于窗口模式，所以我们需要切换到全屏模式；否则，它是当前处于全屏模式的元素。通过在 <video> 元素上调用 Element.requestFullscreen() 来切换到全屏模式。

如果全屏模式已经激活（fullscreenElement 不是 null），我们在 document 上调用 exitFullscreen() 来关闭全屏模式。

规范

规范	状态
Fullscreen API	现行的标准

浏览器兼容性

Document.fullscreen

桌面浏览器兼容性

移动浏览器兼容性

1. 通过 webkitIsFullscreen 支持。

2. 通过 mozFullScreen 支持。

3. 通过 webkitIsFullScreen 支持。

Document.fullscreenElement

桌面浏览器兼容性

暂无兼容数据

Document.fullscreenEnabled

桌面浏览器兼容性

移动浏览器兼容性

1. 通过 mozFullScreenEnabled 支持。

2. 通过 msFullscreenEnabled 支持。

Document.exitFullscreen

桌面浏览器兼容性

移动浏览器兼容性

1. 通过 mozCancelFullScreen 支持。

2. 通过 msExitFullscreen 支持。

Element.requestFullscreen

桌面浏览器兼容性

移动浏览器兼容性

1. 在 Firefox 44 之前，Firefox 错误地允许 <frame> 或 <object> 元素来请求和被授予全屏。在 Firefox 44 及以后的版本中，此问题已得到修复：只有顶级文档或具有 allowfullscreen 属性的 <frame> 元素可以全屏显示。

2. 通过 mozRequestFullScreen 支持。

3. 在 Firefox 44 之前，Firefox 错误地允许 <frame> 或 <object> 元素来请求和被授予全屏。在 Firefox 44 及以后的版本中，此问题已得到修复：只有顶级文档或具有 allowfullscreen 属性的 <frame> 元素可以全屏显示。

4. 仅适用于 iPad，不适用于 iPhone。显示无法禁用的叠加按钮。

相关链接

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