浏览器 Fullscreen API

[tcatche]

本文博客地址：浏览器 Fullscreen API.

Fullscreen API 支持以全屏模式展示特定元素及其后代。这使得它可以将特定内容（如游戏，大屏可视化看板等）铺满整个屏幕。并在不再需要时退出全屏模式。

本文看一下全屏相关内容的操作：

进入全屏和退出全屏

Element.requestFullscreen

Element.requestFullscreen() 方法异步地使元素进入全屏模式，此方法返回一个 Promise。

var Promise = Element.requestFullscreen(options);

调用此API并不能保证元素能进入全屏模式。如果元素成功进入全屏模式，返回的 Promise 的状态会变为 resolve；如果失败，Promise 状态会变成 rejected。

document.body.onclick = function (event) {
  document.body.requestFullscreen()
    .then(() => console.log('进入全屏成功'))
    .catch(err => {
      console.log('进入全屏失败')
      console.error(err)
    })
}

注意，本方法调用必须在响应用户操作才会生效，也就是说才方法需要放在如 click 事件的回调函数中，直接调用会失败。

// 全屏模式只允许用户操作触发，此操作会发生错误
document.documentElement.requestFullscreen();

// 全屏模式只允许用户操作触发，此操作会成功
document.body.onclick = function () {
  document.documentElement.requestFullscreen();
}

注意，允许多个元素进入全屏状态，浏览器会内部维护一个全屏状态元素的列表。

Document.exitFullscreen

Document.exitFullscreen 方法，能够从当前全屏模式退回到上一次调用 Element.requestFullscreen 之前的状态。

与 Element.requestFullscreen 类似，本方法也返回一个 Promise 对象。

document.body.onclick = function (event) {
  if (document.fullscreenElement) {
    document.exitFullscreen()
      .then(() => console.log("退出成功"))
      .catch((err) => {
        console.log('退出失败')
        console.error(err)
      })
  } else {
    document.body.requestFullscreen();
  }
}

注意，本方法调用一次只会关闭上次调用 Element.requestFullscreen 进入的全屏模式，如果有多次调用 Element.requestFullscreen 进入的全屏模式，此时仍处于全屏模式。

如果想要全部退出全屏，可以参考下面代码：

// 所有的全屏元素都退出全屏
async function exitFullscreenAll() {
  while (document.fullscreenElement) {
    console.log(document.fullscreenElement)
    await document.exitFullscreen()
      .then(() => console.log("退出成功"))
      .catch((err) => {
        console.log('退出失败')
        console.error(err)
      })
  }
}

exitFullscreenAll();

注意，这个方法是挂载在 Document 对象而不是 Element 对象上的。

注意，通常可以通过按 Esc 或 F11 键退出全屏模式。

全屏事件

总共有两类事件 fullscreenchange 和 fullscreenerror：

• fullscreenchange: 进入或退出全屏成功后触发事件。
• fullscreenerror: 进入或退出全屏发生错误后触发事件。

document.onfullscreenchange = function ( event ) {
  console.log("全屏状态改变成功")
};
document.onfullscreenerror = function ( event ) {
  console.log("全屏状态改变失败")
};

// 全屏模式只允许用户操作触发，此操作会发生错误
document.documentElement.requestFullscreen();

// 全屏模式只允许用户操作触发，此操作会成功
document.body.onclick = function () {
  document.documentElement.requestFullscreen();
}

注意，它们可以挂在 Document 对象监听文档中的所有元素进入/退出全屏状态或进入/退出出错，也可以挂在 Element 对象上监听某个元素进入/退出全屏状态或进入/退出出错。

相关属性

document.fullscreenEnabled 属性

document.fullscreenEnabled 属性返回一个布尔值，表明浏览器是否支持全屏模式。

document.fullscreenElement 属性

document.fullscreenElement 可以用来获得当前全屏的元素，如果没有全屏的元素则返回 null。

// 指定元素是否全屏
function isElementInFullscreen(ele) {
  return document.fullscreenElement && document.fullscreenElement === ele;
}

document.mozFullScreen

~~document.fullscreen~~ 属性返回一个布尔值，表示当前是否以全屏模式显示内容。
该方法已经被废弃，不建议使用，可以使用上面的 document.fullscreenElement 属性替代。

相关的 CSS

对应的有两个伪类和伪元素和全屏状态有关 :fullscreen 伪类 和 ::backdrop 伪元素。

:fullscreen 伪类

CSS :fullscreen 伪类匹配当前处于全屏模式的每个元素。如果当前有多个元素处于全屏模式，则会选择所有元素。

/* 非全屏下，按钮的颜色为蓝色 */
button:not(:fullscreen) {
  background-color: blue;
}

/* 全屏下，按钮的颜色为红色 */
button:fullscreen {
  background-color: red;
}

::backdrop 伪元素

::backdrop 伪元素是一个与视口大小相同的框，它在全屏模式下直接呈现在全屏元素的下方。

/*
  button 全屏时，button元素背后的颜色为红色
  注意，不是 button 的 background
 */
button:backdrop {
  background-color: red;
}

参考

• MDN: Fullscreen API
• caniuse :fullscreen
• caniuse ::backdrop