全屏 API 为使用用户的整个屏幕展现网络内容提供了一种简单的方式。这种API让你可以简单地控制浏览器,使得一个元素与其子元素,如果存在的话,可以占据整个屏幕,并在此期间,从屏幕上隐藏所有的浏览器用户界面以及其他应用。

当前并不是所有的浏览器都使用API的无前缀版本。查阅该前缀以及它们之间的命名差异总结表 (你也可以使用 Fscreen 来提供跨浏览器API访问).

激活全屏模式

给出一个你想要以全屏模式展示的元素 (比如说,像 <video>,),你可通过简单调用它的Element.requestFullscreen() 方法以全屏模式展示它。

让我们考虑这个 <video> 元素:

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

我们可以用如下的脚本将视频置为全屏模式。

var elem = document.getElementById("myvideo");
elem.addEventListener('click',function () {
  if (elem.requestFullscreen) {
    elem.requestFullscreen();
  } else if (elem.msRequestFullscreen) {
    elem.msRequestFullscreen();
  } else if (elem.mozRequestFullScreen) {
    elem.mozRequestFullScreen();
  } else if (elem.webkitRequestFullscreen) {
    elem.webkitRequestFullscreen();
  }
});//然后点击视频,看看会发生什么

显示差异

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

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

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

通知

当成功进入全屏模式时,包含该元素的文档会收到一个 fullscreenchange 事件。当退出全屏模式时,文档会再一次收到  fullscreenchange 事件。注意此 fullscreenchange 事件本身,不管在文档进入和退出全屏模式时,都不会提供任何信息,但如果文档有一个非空的 fullscreenElement,你就可以得知你处于全屏模式中。

当全屏请求失败时

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

注意: 全屏请求必须在事件处理函数中调用,否则将会被拒绝。 

退出全屏模式

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

其他信息

 document 提供了一些额外的信息, 在开发全屏网络应用时会很有用:

fullscreenElement
fullscreenElement 属性可以告诉你当前以全屏模式显示的元素 element。若此项非空,文档处于全屏模式中,否则不在该模式中。
fullscreenEnabled
fullscreenEnabled 属性可以告诉你文档当前是否为允许请求进入全屏幕模式的状态。

你的用户想了解的信息

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

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

示例

在这个例子中,网页中显示了一个视频。按下 Return 或 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 && !document.msFullscreenElement ) {  // current working methods
    if (document.documentElement.requestFullscreen) {
      document.documentElement.requestFullscreen();
    } else if (document.documentElement.msRequestFullscreen) {
      document.documentElement.msRequestFullscreen();
    } else if (document.documentElement.mozRequestFullScreen) {
      document.documentElement.mozRequestFullScreen();
    } else if (document.documentElement.webkitRequestFullscreen) {
      document.documentElement.webkitRequestFullscreen(Element.ALLOW_KEYBOARD_INPUT);
    }
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    } else if (document.msExitFullscreen) {
      document.msExitFullscreen();
    } else if (document.mozCancelFullScreen) {
      document.mozCancelFullScreen();
    } else if (document.webkitExitFullscreen) {
      document.webkitExitFullscreen();
    }
  }
}

其将首先检查 documentfullscreenElement 属性的值 (亦要检查带有前缀 moz, ms, or webkit的该属性)。如果其为 null,文档当前处于窗口模式中,所以我们需要切换到全屏模式。通过调用 element.requestFullscreen(),可以切换到全屏模式。

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

前缀

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

标准 Blink (Chrome & Opera) Gecko (Firefox) Internet Explorer 11 Edge Safari (WebKit)
Document.fullscreen webkitIsFullScreen mozFullScreen - webkitIsFullScreen webkitIsFullScreen
Document.fullscreenEnabled webkitFullscreenEnabled mozFullScreenEnabled msFullscreenEnabled webkitFullscreenEnabled webkitFullscreenEnabled
Document.fullscreenElement webkitFullscreenElement mozFullScreenElement msFullscreenElement webkitFullscreenElement webkitFullscreenElement
Document.onfullscreenchange onwebkitfullscreenchange onmozfullscreenchange MSFullscreenChange onwebkitfullscreenchange onwebkitfullscreenchange
Document.onfullscreenerror onwebkitfullscreenerror onmozfullscreenerror MSFullscreenError onwebkitfullscreenerror onwebkitfullscreenerror
Document.exitFullscreen() webkitExitFullscreen() mozCancelFullScreen() msExitFullscreen() webkitExitFullscreen() webkitExitFullscreen()
Element.requestFullscreen() webkitRequestFullscreen() mozRequestFullScreen() msRequestFullscreen() webkitRequestFullscreen() webkitRequestFullscreen()

规范

规范 状态 备注
Fullscreen API Living Standard 初始版本.

非标准方法

这里有一些方法,是各浏览器在标准草案制定前实现的。请使用上述的标准方法,最好避免使用下面的方法:

 

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

 

浏览器兼容性

所有的浏览器都实现了这个API。然而一些带有前缀的实现在拼写上略微有些差别;例如,不同于 requestFullscreen(), 存在一个 MozRequestFullScreen().

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
Basic support 15 -webkit (Yes) 9.0 (9.0) -moz
47 (47) (behind full-screen-api.unprefix.enabled)
11 -ms 12.10 5.0 -webkit
fullscreenEnabled 20 -webkit (Yes) 10.0 (10.0) -moz
47 (47) (behind full-screen-api.unprefix.enabled)
11 -ms 12.10 5.1 -webkit
Feature Android Chrome Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? 28 -webkit (Yes) 9.0 (9.0)-moz
47.0 (47) (behind full-screen-api.unprefix.enabled)
? ? ?
fullscreenEnabled ? 28 -webkit (Yes) 10.0 (10.0) moz
47.0 (47) (behind full-screen-api.unprefix.enabled)
? ? ?

另见

文档标签和贡献者

标签: 
此页面的贡献者: wbamberg, codeofjackie
最后编辑者: wbamberg,