Element：requestFullscreen() 方法

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Element.requestFullscreen() 方法用于发出异步请求使元素进入全屏模式。

调用此方法并不能保证元素一定能够进入全屏模式。如果元素被允许进入全屏幕模式，返回的 Promise 会兑现，并且该元素会收到一个 fullscreenchange 事件，通知它已经进入全屏模式。如果全屏请求被拒绝，返回的 promise 会被拒绝并且该元素会收到一个 fullscreenerror 事件。如果该元素已经从原来的文档中分离，那么该文档将会收到这些事件。

语法

js
requestFullscreen()
requestFullscreen(options)

参数

options 可选

控制全屏模式转换行为的对象。可用选项包括：

控制元素处于全屏模式时是否显示导航 UI。默认值为 "auto"，表示浏览器应该决定要做什么。

"hide"

浏览器的导航界面将被隐藏，并且整个屏幕尺寸将分配给显示元素。

"show"

浏览器将显示页面导航控件和可能的其他用户界面；元素的尺寸（以及感知的屏幕尺寸）将被限制以便为该用户界面留出空间。

"auto"

浏览器将选择应用上述哪种设置。这是默认值。

screen 可选

指定要在哪个屏幕上将元素置于全屏模式。这需要代表所选屏幕的 ScreenDetailed 对象作为值。

返回值

一个 Promise，当全屏模式完成时，兑现 undefined。

异常

requestFullscreen() 通过拒绝返回的 Promise来生成错误条件，而不是抛出一个传统的异常。拒绝处理器接收以下的某一个值：

TypeError

在以下几种情况下，会抛出 TypeError：

  • 文档中包含的元素未完全激活，也就是说不是当前活动的元素。
  • 元素不在文档之内。
  • 因为权限策略配置或其他访问控制特性，元素不被允许使用 fullscreen 特性。
  • 元素和它的文档是同一个节点。
  • 该元素是一个弹出窗口，已通过 HTMLElement.showPopover() 显示。

安全性

需要瞬态用户激活。用户必须与页面或 UI 元素进行交互才能使用此功能。

使用说明

兼容元素

你希望置于全屏模式的元素必须满足一些简单的要求：

此外，任何设置的权限策略都必须允许使用此特性。

检测全屏激活

你可以使用 requestFullscreen() 返回的 Promise 来确定切换到全屏模式的尝试是否成功，如下面的示例所示。

要了解其他代码何时打开和关闭全屏模式，你应该为 Document 上的 fullscreenchange 事件创建监听器。监听 fullscreenchange 也很重要，例如，当用户手动切换全屏模式时，或者当用户切换应用程序时，导致应用程序暂时退出全屏模式。

示例

请求全屏模式

此函数可将文档中找到的第一个 <video> 元素切换为全屏模式或退出全屏模式。

js
function toggleFullscreen() {
  let elem = document.querySelector("video");

  if (!document.fullscreenElement) {
    elem.requestFullscreen().catch((err) => {
      alert(`尝试启用全屏模式时出错：${err.message}（${err.name}）`);
    });
  } else {
    document.exitFullscreen();
  }
}

如果文档尚未处于全屏模式（通过查看 document.fullscreenElement 是否有值来检测），我们将调用视频的 requestFullscreen() 方法。如果成功，我们不需要做任何特殊的事情，但如果请求失败，我们的 promise 的 catch() 处理器会显示带有适当错误消息的警报。

另一方面，如果全屏模式已经生效，我们将调用 document.exitFullscreen() 来禁用全屏模式。

你可以在 Glitch 上查看此示例的实际操作或查看或重新混合代码。

使用 navigationUI

在此示例中，通过在文档的 Document.documentElement（即文档的根 <html> 元素）上调用 requestFullscreen()，将整个文档置于全屏模式。

js
let elem = document.documentElement;

elem
  .requestFullscreen({ navigationUI: "show" })
  .then(() => {})
  .catch((err) => {
    alert(`尝试切换到全屏模式时发生错误：${err.message}（${err.name}）`);
  });

promise 的解析处理器不执行任何操作，但如果 promise 被拒绝，则会通过调用 alert() 显示错误消息。

使用 screen 选项

如果你想让元素在主操作系统屏幕上全屏显示，你可以使用如下代码：

js
try {
  const primaryScreen = (await getScreenDetails()).screens.find(
    (screen) => screen.isPrimary,
  );
  await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
  console.error(err.name, err.message);
}

Window.getScreenDetails() 方法用于检索当前设备的 ScreenDetails 对象，其中包含代表不同可用屏幕的 ScreenDetailed 对象。

规范

Specification
Fullscreen API
# ref-for-dom-element-requestfullscreen①

浏览器兼容性

参见