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 Standard
# ref-for-dom-element-requestfullscreen①

浏览器兼容性

BCD tables only load in the browser

参见