全屏指南
====

本文主要说明如何使用全屏 API 将给定元素设置为全屏模式，以及如何检测浏览器何时进入或退出全屏模式。

激活全屏模式
------

对于一个你想要以全屏模式展示的元素（例如 `<video>`），你通过调用它的 `Element.requestFullscreen()` 方法就能简单地激活它的全屏模式。

我们来看看 `<video>` 这个元素：


```html
<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>
```


我们可以用下面的代码让视频进入全屏模式：


```js
var elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}
```


这段代码会在调用 `requestFullscreen()` 方法之前先检验它是否存在。

### 显示差异

值得留意的是，目前 Gecko 和 WebKit 的实现之间的关键差异：Gecko 自动为元素添加了 CSS 规则，使其拉伸以填满屏幕： "`width: 100%; height: 100%`"。WebKit 没有这样做，相反地，它将全屏元素居中，不改变大小，而屏幕的其他部分为黑色。为了在 Webkit 中获得相同的全屏行为，你需要自行为元素添加 CSS "`width: 100%; height: 100%;`"：


```css
#myvideo:-webkit-full-screen {
  width: 100%;
  height: 100%;
}
```


另一方面，如果你尝试在在 Gecko 上模拟 WebKit 的行为，你需要把你想要呈现的元素放在另一个实际调整为全屏幕的元素中，并使用 CSS 规则调整内部的元素，从而达到你想要的样式。

### 通知

当成功进入全屏模式时，包含该元素的文档会收到一个 `fullscreenchange` 事件。当退出全屏模式时，文档会再一次收到 `fullscreenchange` 事件。注意此 `fullscreenchange` 事件，不管在文档进入和退出全屏模式时，都不会提供任何信息，但如果文档的 `fullscreenElement` 为非空（`null`），即处于全屏模式中。

### 当全屏请求失败时

你并不总是可以进入全屏模式。例如 `<iframe>` 元素具有 `allowfullscreen` 属性，可选择是否将其内容以全屏模式显示。另外，几种特定的内容，比如窗体插件（windowed plug-ins），不能以全屏模式显示。尝试将不能以全屏模式显示的元素（或者此元素的父元素和后代元素）的时候，全屏请求是无效的。而相应元素会收到一个 `mozfullscreenerror` 事件。当全屏请求失败时，Firefox 会在 Web 控制台上打一条错误信息解释请求为什么失败。但是在 Chrome 和新版的 Opera 中，不会生成这样的警告。

**备注：** 全屏请求必须在事件处理函数中调用，否则将会被拒绝。

退出全屏模式
------

用户总是可以自行退出全屏模式；详见 Things your users want to know。你也可以以编程方式通过调用 `Document.exitFullscreen()` 方法来做到这点。

其他信息
----

`Document` 提供了一些额外的信息，在开发全屏网络应用时会很有用：

`DocumentOrShadowRoot.fullscreenElement`

`fullscreenElement` 属性可以告诉你当前以全屏模式显示的元素 `Element` 。若此项非空，文档处于全屏模式中，否则不在。

`Document.fullscreenEnabled`

`fullscreenEnabled` 属性可以告诉你文档当前是否为允许请求进入全屏幕模式的状态。

你的用户想了解的信息
----------

你可能想确保使你的用户得知他可以按 `ESC` 键 (或 `F11`) 退出全屏模式。

此外，当处在全屏模式中，浏览其他页面、切换标签页、或者切换到其他应用 (例如使用 `Alt`-`Tab`) 也会导致退出全屏模式。

示例
--

在这个例子中，网页中显示了一个视频。按下 `Return` 或 `Enter` 键让用户在视频的窗口显示和全屏显示之间切换。

View Live Examples

### 监听 `Enter` 键

当页面加载完成时，这段代码可以设置一个事件监听器以监听 `Enter` 键。


```js
document.addEventListener(
  "keydown",
  function (e) {
    if (e.keyCode == 13) {
      toggleFullScreen();
    }
  },
  false,
);
```

### 切换全屏模式

当用户按下 `Enter` 键时，这段代码会被调用，像上面示例看到的那样。


```js
function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}
```


这段代码首先检查 `document` 的`fullscreenElement` 属性的值（亦要检查带有前缀 `moz`、`ms`、`webkit`）。如果其为 `null`，文档当前处于窗口模式中，所以我们需要切换到全屏模式。通过调用`element.requestFullscreen()`，可以切换到全屏模式。

如果全屏模式已经激活 (`fullscreenElement` 不为 `null`)，我们可以调用 `document.exitFullscreen()`（或其前缀化的版本，这取决于你使用的浏览器）。

前缀
--

**备注：** 现在，只有 Firefox 64 和 Chrome 71 支持无前缀。

目前并不是所有的浏览器都实现了 API 的无前缀版本（你可以使用 Fscreen 获取跨浏览器全屏 API），这里有一份表格总结了前缀和它们之间的命名区别：

| Standard | WebKit (Safari) / Blink (Chrome & Opera) / Edge | Gecko (Firefox) | Internet Explorer |
| --- | --- | --- | --- |
| `Document.fullscreen` 
已弃用
 | `webkitIsFullScreen` | `mozFullScreen` | - |
| `Document.fullscreenEnabled` | `webkitFullscreenEnabled` | `mozFullScreenEnabled` | `msFullscreenEnabled` |
| `DocumentOrShadowRoot.fullscreenElement` | `webkitFullscreenElement` | `mozFullScreenElement` | `msFullscreenElement` |
| `Document.onfullscreenchange` | `onwebkitfullscreenchange` | `onmozfullscreenchange` | `onMSFullscreenChange` |
| `Document.onfullscreenerror` | `onwebkitfullscreenerror` | `onmozfullscreenerror` | `onMSFullscreenError` |
| `Document.exitFullscreen()` | `webkitExitFullscreen()` | `mozCancelFullScreen()` | `msExitFullscreen()` |
| `Element.requestFullscreen()` | `webkitRequestFullscreen()` | `mozRequestFullScreen()` | `msRequestFullscreen()` |

规范
--

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |
| Fullscreen API Standard # dom-document-fullscreen |

浏览器兼容性
------

### api.Document.fullscreenEnabled

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.fullscreen

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

扩展链接
----

* 全屏 API
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreen`
* `Document.fullscreenElement`
* `:fullscreen`, `::backdrop`
* `allowfullscreen`