全屏模式切换

Fullscreen API 使 Web 站点内容能够以用户屏幕尺寸大小的界面进行显示. 本份文档能够让您了解如何使用该 API.

这个 API 能够让你轻松的指引浏览器将一个元素及它的子节点(如果存在的话)占据整个屏幕，在此期间，会将浏览器的界面及屏幕上的其他应用清除。

激活全屏模式

如果你想使一个元素在全屏模式下展现 (比如说 <video>)，你可以调用该元素的 requestFullscreen() 方法；这个方法在 Gecko 中的实现是 element.mozRequestFullScreen()，在 WebKit 中为 element.webkitRequestFullscreen()。

现在来看看这个 <video> 元素:

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

我们可以通过调用下面这个脚本使视频全屏播放:

var elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
} else if (elem.mozRequestFullScreen) {
  elem.mozRequestFullScreen();
} else if (elem.webkitRequestFullscreen) {
  elem.webkitRequestFullscreen();
}

屏幕显示差异

运行到这里，Gecko 与 WebKit 两个实现中出现了一个值得注意的区别：Gecko 会为元素自动添加 CSS 使其伸展以便铺满屏幕： "width: 100%; height: 100%"。 WebKit 则不会这么做；它会让全屏的元素以原始尺寸居中到屏幕中央，其余部分变为黑色。为了在 WebKit 下也达到与 Gecko 同样的全屏效果，你需要手动为元素增加 CSS 规则"width: 100%; height: 100%;"：

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

如果你想在 Gecko 下模拟 WebKit 的效果，需要把你希望显示的元素放入另一个元素内，反过来让那个元素全屏显示，然后使用 CSS 调整内部元素的样式，以达到你期望的显示效果。

通知

当成功进入全屏模式后，document 会收到一个 mozfullscreenchange 事件。当退出全屏状态后，document 又会收到  mozfullscreenchange 事件。注意 mozfullscreenchange 事件并不会提供关于 document 是否进入或退出全屏状态的任何信息，但是当 document 拥有一个不为空的 mozFullScreenElement 时，你就会知道你已经在全屏模式中了。

全屏调用请求失败时的处理方案

无法保证你能够切换进全屏模式。例如， <iframe> 元素拥有 mozallowfullscreen 属性 (webkitallowfullscreen， 等等) 能够选择让它们的内容在全屏模式内显示。此外，特定类型的内容，例如窗口插件，无法在全屏模式下展现。尝试使一个无法显示的元素(或该元素的父元素或者子元素)进入全屏模式并不会生效。相反的，请求全屏模式的那个元素会收到一个 mozfullscreenerror 事件。当请求全屏模式失败后，Firefox 将会在 Web 控制台记录一条错误日志来解释为什么请求会失败。

退出全屏模式

用户总是可以自愿的退出全屏模式；查看 Things your users want to know。你也可以调用 cancelFullscreen()方法来达到同样效果；该方法在 Gecko 中的实现是 mozCancelFullScreen()，在 WebKit 中为 webkitCancelFullScreen()。

其他相关信息

document 提供了额外一些信息，对开发全屏 web 应用会有所帮助：

fullscreenElement

fullscreenElement 属性会告诉你当前全屏显示的 element。 如果该值为非空，则 document 进入了全屏模式。如果为空则不在全屏模式。

fullscreenEnabled

fullscreenEnabled 属性告诉了你当前 document 是否进入了可以请求全屏模式的状态。

站点使用者会需要知道的事儿

站点开发者在使用该 API 时必须保证得让用户了解按下"ESC"键 (或 F11) 能够退出全屏模式.

还有一点, 在全屏模式下, 页面导航、标签页切换、应用程序切换要与桌面模式下的行为相同.

样例

该示例页面中有一段视频, 点击"回旋"图标样的按钮或按下 Enter 键使播放器全屏, 同样的, 也可以缩小为页面视频窗口.

查看在线演示

观察 Enter 键的行为

当页面加载完后, 下面一段代码将会设置为事件监听组件以监视 'Enter' 键的行为.

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

切换全屏模式

当用户敲击 Enter 键时会运行如下代码，如你在上面所见。

function toggleFullScreen() {
  if (!document.fullscreenElement &&    // alternative standard method
      !document.mozFullScreenElement && !document.webkitFullscreenElement) {  // current working methods
    if (document.documentElement.requestFullscreen) {
      document.documentElement.requestFullscreen();
    } else if (document.documentElement.mozRequestFullScreen) {
      document.documentElement.mozRequestFullScreen();
    } else if (document.documentElement.webkitRequestFullscreen) {
      document.documentElement.webkitRequestFullscreen(Element.ALLOW_KEYBOARD_INPUT);
    }
  } else {
    if (document.cancelFullScreen) {
      document.cancelFullScreen();
    } else if (document.mozCancelFullScreen) {
      document.mozCancelFullScreen();
    } else if (document.webkitCancelFullScreen) {
      document.webkitCancelFullScreen();
    }
  }
}

代码首先检查了 document 上的 fullscreenElement 属性(也检查了带 -moz- 与 -webkit- 两个前缀的)。如果该属性为 null，则 document 当前处于窗口模式，所以我们需要切换进全屏模式。可以通过调用 element.mozRequestFullScreen() 或者 webkitRequestFullscreen()来进入全屏模式，具体调用哪个还要看哪个方法可用。

如果已经激活了全屏模式 (fullscreenElement 非空)，我们调用 document.mozCancelFullScreen() 或 webkitCancelFullScreen()，同样要依赖于我们使用了哪个浏览器。

浏览器兼容性

虽然 Gecko 与 WebKit 同时实现了该 API 的一个草案，但还是存在一些细节区别。该文档并不需要关注这些细节问题。当规范与实现彼此差别不大时，本篇文章会进行修订。

Gecko 下的一些特性

虽然 Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6) 引入了该 API，但在该版本发布时却不是默认开启。若要开启它，需要设置 full-screen-api.enabled 为 true。 该 API 在Gecko 10.0 (Firefox 10.0 / Thunderbird 10.0 / SeaMonkey 2.7) 中为默认开启。在 Gecko 中，所有 API 均拼写为 "fullScreen"。

完整文档

Fullscreen API

使用非标准化的方法进行调用

以下是在标准进入草案前浏览器实现的一些方法。在前面介绍了标准方法后，应该避免再使用这些方法：

• window.fullScreen (Firefox)
• HTMLMediaElement.webkitDisplayingFullscreen
• HTMLMediaElement.webkitEnterFullscreen
• HTMLMediaElement.webkitExitFullscreen
• HTMLMediaElement.webkitSupportsFullscreen

其他详见

• element.mozRequestFullScreen()
• element.mozCancelFullScreen()
• document.mozFullScreen
• document.mozFullScreenElement
• document.mozFullScreenEnabled
• :-moz-full-screen
• :-moz-full-screen-ancestor
• mozallowfullscreen

• 博文: Firefox 下的 HTML full-screen 可在 Nightly 中启用