这篇翻译不完整。请帮忙从英语翻译这篇文章

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

可以在全屏 API 指南这篇文章了解更多细节。

注意:当前并不是所有的浏览器都使用 API 的无前缀版本。下面的浏览器兼容性表 Browser compatibility可以看到各个浏览器对此的支持(你也可以使用 Fscreen 来提供跨浏览器 API 访问)。

接口

全屏 API 没有它自己的接口实现。相反,它提供了一些其他接口以供实现全屏所需的方法、属性、事件处理函数。接下来会列出所有细节。

方法

 

全屏 API 在 DocumentElement 接口中增加了一些方法,可用于允许打开关闭全屏模式。

Document 中的方法

Document.exitFullscreen()
用于请求从全屏模式切换到窗口模式,会返回一个 Promise,会在全屏模式完全关闭的时候被置为 resolved 状态。

Element 中的方法

Element.requestFullscreen()
请求浏览器(user agent)将特定元素(甚至延伸到它的后代元素)置为全屏模式,隐去屏幕上的浏览器所有 UI 元素,以及其它应用。返回一个 Promise,并会在全屏模式被激活的时候变成 resolved 状态。

 

属性

Document 提供了可以用于判断是否支持和启用全屏模式的属性,也能得知现在是否处在全屏模式、哪一个元素在使用屏幕等信息。

DocumentOrShadowRoot.fullscreenElement
fullscreenElement 属性提供了当前在 DOM (或者 shadow DOM)里被展示为全屏模式的 Element,如果这个值为 null,文档不处于全屏模式。
 
Document.fullscreenEnabled
fullscreenEnabled 属性提供了启用全屏模式的可能性。当它的值是 false 的时候,表示全屏模式不可用(可能的原因有 "fullscreen" 特性不被允许,或全屏模式不被支持等 )。

事件处理程序

Fullscreen API 定义了两个事件,可用于检测全屏模式的打开和关闭,以及在全屏和窗口模式之间切换过程中发生的错误。Document  Element 接口提供了这些事件的事件处理函数。

注意:这些事件处理函数特性不可以当成 HTML 内容属性来使用。 换句话说,你无法在 HTML 内容中为 fullscreenchange  和 fullscreenerror  指定事件处理程序,你必须通过  JavaScript 代码添加它们。

 

Document 上的事件处理程序

Document.onfullscreenchange

fullscreenchange事件的处理程序,当进入全屏或退出全屏时,事件将被发送到Document上。此处理程序仅在整个文档全屏模式更改时有效。
Document.onfullscreenerror

fullscreenerror 事件的处理程序,当进入全屏或退出全屏出错时,事件将被发送到Document 上,仅对整个稳定的全屏模式更改出错时候有效。
 

Element 上的事件处理程序

Element.onfullscreenchange
fullscreenchange 事件的处理程序,当指定的Element进入退出全屏程序时,事件将被发送到该指定的 Element 上。
Element.onfullscreenerror
fullscreenerror  事件的处理程序,当指定Element改变全屏模式时候出现错误,该事件将被发送到指定的Element 上。

废弃属性

Document.fullscreen 
一个布尔值,文档内任意一个元素以全屏模式程序时该值为true,否则为 false

Note:请改用  ShadowRoot 或 Document 上的 fullscreenElement 属性;如果它不是 null, 则它是就是当前在全屏模式下显示的元素。

 

 

事件

 

全屏API定义了两个事件:1.可用来检测全屏模式何时打开和关闭。2.在全屏模式和窗口模式之间切换过程中何时发生错误。

fullscreenchange
当全屏或退出全屏时发送消息给(监听的)的 Document 或 Element
fullscreenerror
当全屏或退出全屏是发生了错误时,将错误消息发送给(监听的)的 Document 或 Element

Dictionaries

 

FullscreenOptions
在调用requestFullscreen() 时可以设置选项。

Controlling access

 

The availability of full-screen mode can be controlled using Feature Policy. The full-screen mode feature is identified by the string "fullscreen", with a default allow-list value of "self", meaning that full-screen mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document.

See Using Feature Policy to learn more about using Feature Policy to control access to an API.

 

使用说明

用户通过按 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) {
      document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen(); 
    }
  }
}

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

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

规范

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

浏览器兼容性

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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
fullscreen
Deprecated
Chrome No support No
Alternate Name
No support No
Alternate Name
Alternate Name Uses the non-standard name: webkitIsFullScreen
Edge ? Firefox Full support 64
Full support 64
No support 49 — 65
Disabled
Disabled From version 49 until version 65 (exclusive): this feature is behind the full-screen-api.unprefix.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
No support 9 — 65
Alternate Name
Alternate Name Uses the non-standard name: mozFullScreen
IE ? Opera ? Safari Full support Yes
Alternate Name
Full support Yes
Alternate Name
Alternate Name Uses the non-standard name: webkitIsFullScreen
WebView Android No support NoChrome Android No support No
Alternate Name
No support No
Alternate Name
Alternate Name Uses the non-standard name: webkitIsFullScreen
Edge Mobile ? Firefox Android Full support 64
Full support 64
No support 49 — 65
Disabled
Disabled From version 49 until version 65 (exclusive): this feature is behind the full-screen-api.unprefix.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
No support 9 — 65
Alternate Name
Alternate Name Uses the non-standard name: mozFullScreen
Opera Android ? Safari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
User must explicitly enable this feature.
User must explicitly enable this feature.
Uses a non-standard name.
Uses a non-standard name.

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
fullscreenEnabledChrome Full support 45
Full support 45
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Full support 12Firefox Full support 64
Full support 64
No support 47 — 65
Disabled
Disabled From version 47 until version 65 (exclusive): this feature is behind the full-screen-api.unprefix.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
No support 10 — 65
Alternate Name
Alternate Name Uses the non-standard name: mozFullScreenEnabled
IE Full support 11
Alternate Name
Full support 11
Alternate Name
Alternate Name Uses the non-standard name: msFullScreenEnabled
Opera ? Safari ? WebView Android Full support 45
Full support 45
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Chrome Android Full support 45
Full support 45
Full support Yes
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Mobile ? Firefox Android Full support 64
Full support 64
No support 47 — 65
Disabled
Disabled From version 47 until version 65 (exclusive): this feature is behind the full-screen-api.unprefix.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
No support 10 — 65
Alternate Name
Alternate Name Uses the non-standard name: mozFullScreenEnabled
Opera Android ? Safari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown
User must explicitly enable this feature.
User must explicitly enable this feature.
Uses a non-standard name.
Uses a non-standard name.
Requires a vendor prefix or different name for use.
Requires a vendor prefix or different name for use.

 

另见

文档标签和贡献者

此页面的贡献者: vaynewang, mdnwebdocs-bot, Soyaine, wbamberg, codeofjackie
最后编辑者: vaynewang,