全屏模式切换

Fullscreen API提供了一种使用用户的整个屏幕呈现Web内容的简单方法。该API允许您轻松地定向浏览器,使元素及其子元素(如果有)占据全屏,从而在屏幕上消除所有浏览器用户界面和其他应用程序。

注意: 目前,并非所有浏览器都使用无前缀版本的API。请参阅表格,总结它们之间的前缀和名称差异

激活全屏模式

给定一个要在全屏模式下显示的元素 (例如 <video>),您可以通过简单地调用其 requestFullscreen() 方法以全屏模式呈现。

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

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

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

let elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
    elem.requestFullscreen();
}

let 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中获得相同的全屏行为,您需要添加自己的“width:100%; height:100%;” CSS规则到元素自己

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

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

通知

当成功进入全屏模式后,document 会收到一个  fullscreenchange 事件。当退出全屏状态后,document 又会收到一个  fullscreenchange  事件。请注意,  fullscreenchange 事件本身不提供关于文档是否进入或退出全屏模式的任何信息,但如果文档有一个非null  fullscreenElement,你就知道你处于全屏模式。

当一个全屏请求失败时

它不能保证你将能够切换到全屏模式。例如,<iframe> 元素具有allowfullscreen 属性,以便选择允许其内容以全屏模式显示。

此外,特定类型的内容,例如窗口插件,无法在全屏模式下展现。尝试使一个无法显示的元素(或该元素的父元素或者子元素)进入全屏模式并不会生效。相反的,请求全屏模式的那个元素会收到一个 mozfullscreenerror 事件。当请求全屏模式失败后,Firefox 将会在 Web 控制台记录一条错误日志来解释为什么请求会失败。

注意:全屏请求需要在事件处理程序内调用,否则将被拒绝。

退出全屏模式

用户总是有能力自己退出全屏模式;请参阅  Things your users want to know。您也可以程序化通过调用 exitFullscreen() 方法这样做。

其他相关信息

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

fullscreenElement
fullscreenElement 属性会告诉你当前全屏显示的 element。 如果该值为非空,则 document 进入了全屏模式。如果为空则不在全屏模式。
fullscreenEnabled
fullscreenEnabled 属性告诉了你当前 document 是否进入了可以请求全屏模式的状态。

用户想知道的事情

您需要确保让用户知道他们可以按  ESC 键(或 F11)退出全屏模式。

此外,导航到其他页面,更改标签页或切换到其他应用程序 (使用例如, Alt-Tab) 在全屏模式下退出全屏模式也是如此。

样例

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

在该示例中,在一个网页中呈现一个视频。按 Return 键或 Enter键可让用户在视频的窗口和全屏显示之间切换。

查看在线演示

监听 Enter键的行为

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

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

切换全屏模式

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

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


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




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

 如果全屏模式已经激活(fullscreenElement 为非null),我们调用document.exitFullscreen()

Prefixing

目前不是所有的浏览器都实现了API的非前缀版本。下面是汇总前缀和名称之间差异的表格:

Standard 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 onmsfullscreenchange onwebkitfullscreenchange onwebkitfullscreenchange
Document.onfullscreenerror onwebkitfullscreenerror onmozfullscreenerror onmsfullscreenerror onwebkitfullscreenerror onwebkitfullscreenerror
Document.exitFullscreen() webkitExitFullscreen() mozCancelFullScreen() msExitFullscreen() webkitExitFullscreen() webkitExitFullscreen()
Element.requestFullscreen() webkitRequestFullscreen() mozRequestFullScreen() msRequestFullscreen() webkitRequestFullscreen() webkitRequestFullscreen()

规范

Specification Status Comment
Fullscreen API Living Standard Initial version.

浏览器兼容性

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

特性 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本支持属性 15 -webkit 9.0 (9.0) -moz ? 12.10 5.0 -webkit
fullscreenEnabled 20 -webkit 10.0 (10.0) -moz ? 12.10 5.1 -webkit
特性 Android Firefox Mobile (Gecko) IE (移动设备) Opera (移动设备) Safari (移动设备)
基本支持属性 ? 9.0 (9.0)-moz ? ? ?
fullscreenEnabled ? 10.0 (10.0) moz ? ? ?

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

其他详见

文档标签和贡献者

标签: 
 此页面的贡献者: xgqfrms-GitHub, sunnylost, Technommy
 最后编辑者: xgqfrms-GitHub,