元素: requestFullscreen() 方法

有限可用性

此功能不是基线，因为它在一些使用最广泛的浏览器中无法正常工作。

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 来确定您的全屏模式切换尝试是否成功，如下面的 示例 中所示。

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

示例

请求全屏模式

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

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

  if (!document.fullscreenElement) {
    elem.requestFullscreen().catch((err) => {
      alert(
        `Error attempting to enable fullscreen mode: ${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(
      `An error occurred while trying to switch into fullscreen mode: ${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 对象。

规范

规范
全屏 API 标准
# ref-for-dom-element-requestfullscreen①

浏览器兼容性

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

另请参阅