全屏 API 指南

本文演示了如何使用全屏 API将给定元素置于全屏模式,以及如何在浏览器进入或退出全屏模式时进行检测。

激活全屏模式

假设您有一个希望以全屏模式呈现的元素(例如<video>),您可以通过调用其requestFullscreen()方法将其置于全屏模式。

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

html
<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>

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

js
const elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}

此代码在调用requestFullscreen()方法之前检查其是否存在。

通知

成功进入全屏模式后,包含该元素的文档将收到一个fullscreenchange事件。退出全屏模式时,文档将再次收到fullscreenchange事件。请注意,fullscreenchange事件本身不会提供任何信息来指示文档是进入还是退出全屏模式,但如果文档具有非空fullscreenElement,则表明您处于全屏模式。

全屏请求失败时

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

注意:全屏请求需要在事件处理程序内调用,否则将被拒绝。

退出全屏模式

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

其他信息

Document提供了一些其他信息,在开发全屏 Web 应用程序时可能很有用

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement属性告诉您当前正在以全屏模式显示的Element。如果此属性非空,则文档(或影子 DOM)处于全屏模式。如果此属性为空,则文档(或影子 DOM)不处于全屏模式。

Document.fullscreenEnabled

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

移动浏览器中的视口缩放

某些移动浏览器在全屏模式下会忽略视口元标记设置并阻止用户缩放;例如:在全屏模式下显示的页面上可能无法使用“捏合缩放”手势——即使在非全屏模式下,页面也可以使用“捏合缩放”进行缩放。

用户想知道的事情

您需要确保让用户知道他们可以按Esc键(或F11)退出全屏模式。

此外,在全屏模式下导航到另一个页面、切换标签或切换到另一个应用程序(例如,使用Alt-Tab)也会退出全屏模式。

示例

在此示例中,视频在网页中呈现。按ReturnEnter键允许用户在视频的窗口化和全屏呈现之间切换。

查看实时示例

监视 Enter 键

页面加载时,将运行此代码以设置一个事件侦听器来监视Enter键。

js
document.addEventListener(
  "keydown",
  (e) => {
    if (e.key === "Enter") {
      toggleFullScreen();
    }
  },
  false,
);

切换全屏模式

如上所示,当用户按下Enter键时,将调用此代码。

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

首先查看documentfullscreenElement属性的值。如果它为null,则文档当前处于窗口化模式,因此我们需要切换到全屏模式。切换到全屏模式是通过调用element.requestFullscreen()来完成的。

如果全屏模式已激活(fullscreenElementnull),则我们调用document.exitFullscreen()

规范

规范
全屏 API 标准
# ref-for-dom-document-fullscreenenabled①
全屏 API 标准
# dom-document-fullscreen

浏览器兼容性

api.Document.fullscreenEnabled

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

api.Document.fullscreen

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅