Web API 之 — Fullscreen API

今天突然发现 Fullscreen API 竟然是在 Element 上的方法，之前一直以为是 window 上的，所以今天就来梳理一下这块儿的知识，全面地了解一下。

首先 Fullscreen API 提供的方法都是作用在 Element 和 Document 上的，所以，是可以让某个元素全屏展示的。接下来，我们来看如何全屏和退出全屏。

全屏和退出全屏

全屏对应 Element.requestFullscreen() 和退出全屏对应 Document.exitFullscreen()，你没看错，这两个方法一个是在 Element 上，一个是在 Document 上，感觉比较奇葩。这两个方法都是返回一个 Promise，当全屏或退出全屏结束时，Promise 会被 resolve。

这里有一点要注意的是，由于 requestFullscreen 是作用在某个元素上，所以全屏后的内容只有这个元素，如果你要把整个页面放到全屏，应该作用到 html 元素上，使用 document.documentElement.requestFullscreen()来操作，如果只是作用到 body 上，那么除了 body 的其它内容就没有在全屏中，可能会出现不符合你预期的效果。

获取全屏元素和判断是否可全屏

通过 document.fullscreenElement 可以获取到当前正在全屏的元素，如果没有元素全屏，则返回 null。

document.documentElement.requestFullscreen().then(() => {
	console.log(document.fullscreenElement === document.documentElement)
	// true
})
console.log(document.fullscreenElement === document.documentElement)
// false
1
2
3
4
5
6

通过 document.fullscreenEnabled 可以用来判断元素是否可以全屏展示，如果浏览器全屏模式不支持，则返回 false

关于全屏的事件

关于全屏的事件有两个fullscreenchange 和 fullscreenerror，这两个事件绑定到 Document 或 Element 上，具体含义也都很明显。fullscreenchange 是在全屏模式变化时触发，fullscreenerror 是在全屏模式切换报错时触发。看下具体例子：

document.addEventListener('fullscreenchange', (e) => {
	console.log(e)
})

document.documentElement.requestFullscreen() // 触发 'fullscreenchange' 事件
document.exitFullscreen() // 再次触发 'fullscreenchange' 事件
1
2
3
4
5
6

全屏下的样式

我们先看下，在全屏模式下的默认样式。参考 whatwg 标准的文档[https://fullscreen.spec.whatwg.org/#user-agent-level-style-sheet-defaults]。

*|*:not(:root):fullscreen {
  position:fixed !important;
  top:0 !important; right:0 !important; bottom:0 !important; left:0 !important;
  margin:0 !important;
  box-sizing:border-box !important;
  min-width:0 !important;
  max-width:none !important;
  min-height:0 !important;
  max-height:none !important;
  width:100% !important;
  height:100% !important;
  transform:none !important;

  /* intentionally not !important */
  object-fit:contain;
}

iframe:fullscreen {
  border:none !important;
  padding:0 !important;
}

::backdrop {
  position:fixed;
  top:0; right:0; bottom:0; left:0;
}

*|*:not(:root):fullscreen::backdrop {
  background:black;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

我们看上面的样式，主要是通过 ::backdrop 伪元素和 :fullscreen 伪类来实现的。所以要更改全屏模式的样式也是通过这些来做。

::backdrop 伪元素

默认样式中，backdrop 是一个和视口大小一样的盒子，这个元素就在全屏模式下元素的下面，并且颜色黑色的。

我们通过设置 backdrop 的 background 来改变它的背景色。如：

::backdrop {
	background: yellowgreen;
}

/*
	这样全屏下，背景色就是 yellowgreen 了
*/
1
2
3
4
5
6
7

:fullscreen 伪类

fullscreen 伪类顾名思义就是元素在全屏模式下的样式。

如下我们改变 body 上字体颜色：

body:fullscreen {
	color: blue;
}

/*
	这样，body 元素在全屏模式下，文字颜色就是 blue 了
*/
1
2
3
4
5
6
7

iframe 的全屏

如果某个页面通过 iframe 引入，那么在这个页面中调用 requestFullscreen() 并不会生效，如果想要让 iframe 中的全屏操作生效，就需要在 iframe 标签上写上 allowfullscreen 属性。如下：

<iframe src="http://127.0.0.1:8081/t2.html" allowfullscreen frameborder="0"></iframe>
1

另外 Fullscreen 只允许在 self 的 context 下操作，所以通过 top-level 的 context 操作是不被允许的。

关于 Fullscreen API 的内容基本就这么多，仔细想想，好像各种视频网站用这个 api 会比较多，因为视频有全屏播放的需求，所以全屏的操作作用到 Element 上确实是比较舒服的设计。好了，今天又水了一篇文章。