第一部分: 接口
全屏 API 没有它自己的接口实现。相反,它提供了一些其他接口以供实现全屏所需的方法、属性、事件处理函数。接下来会列出所有细节。
也就是说, 没有全屏的专有接口, 而是在其他接口上 ( document 和 Element ) 定义了一些方法, 属性, 事件
第二部分 方法
全屏 API 在 Document 和 Element 接口中增加了一些方法,可用于允许打开关闭全屏模式。
Document中的方法
- Document.exitFullscreen(): 退出全屏
/**
* @name: 让当前文档退出全屏模式, 调用这个方法会让文档回退到上一个调用Element.requestFullscreen()方法进入全屏模式之前的状态。
* @return: 返回一个 Promise,会在全屏模式完全关闭的时候被置为 resolved 状态
*/
document.exitFullscreen();
/*
1. 如果一个元素A在请求进去全屏模式之前,已经存在其他元素处于全屏状态,当这个元素A退出全屏模式之后,之前的元素仍然处于全屏状态。浏览器内部维护了一个全屏元素栈用于实现这个目的。
2. 可通过Document.exitFullscreen()方法让全屏元素栈的栈顶元素退出全屏状态,并让新的栈顶的元素进入全屏状态。此特征在Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8)中被实现.
*/
Element中的方法
-
Element.requestFullscreen(): 打开全屏
/** * @name: 用于发出异步请求使元素进入全屏模式。 * @params: { options?: 控制选项 => 唯一的选项是navigationUI,这控制了是否在元素处于全屏模式时显示导航条UI。默认值是"auto",表明这将由浏览器来决定是否显示导航条。 } * @return: 返回一个 Promise,会在全屏模式完全关闭的时候被置为 resolved 状态 */ /* 1. 调用此API并不能保证元素一定能够进入全屏模式。如果元素被允许进入全屏幕模式,返回的Promise会resolve,并且该元素会收到一个fullscreenchange事件,通知它已经进入全屏模式。如果全屏请求被拒绝,返回的promise会变成rejected并且该元素会收到一个fullscreenerror事件。如果该元素已经从原来的文档中分离,那么该文档将会收到这些事件。 */
第三部分 属性
document提供了可以用于判断是否支持和启用全屏模式的属性, 也能得知现在是否处在全屏模式、哪一个元素在使用屏幕等信息
-
DocumentOrShadowRoot.fullscreenElement
fullscreenElement 属性提供了当前在 DOM (或者 shadow DOM)里被展示为全屏模式的 Element,如果这个值为 null,文 档不处于全屏模式。
-
Document.fullscreenEnabled
fullscreenEnabled 属性提供了启用全屏模式的可能性。当它的值是 false 的时候,表示全屏模式不可用(可能的原因有 "fullscreen" 特性不被允许,或全屏模式不被支持等 )。
第四部分 事件
Fullscreen API 定义了两个事件,可用于检测全屏模式的打开和关闭,以及在全屏和窗口模式之间切换过程中发生的错误。Document 和 Element 接口提供了这些事件的事件处理函数
注意:这些事件处理函数特性不可以当成 HTML 内容属性来使用。 换句话说,你无法在 HTML 内容中为 fullscreenchange 和 fullscreenerror 指定事件处理程序,你必须通过 JavaScript 代码添加它们。
-
fullscreenchange
当全屏或退出全屏时发送消息给(监听的)的 Document 或 Element
-
fullscreenerror
当全屏或退出全屏是发生了错误时,将错误消息发送给(监听的)的 Document 或 Element
第五部分 使用说明
用户通过按 ESC 键(或 F11) 即可退出全屏模式,而不是等着站点或应用的代码来做这件事。确定你在你的用户界面里提供合适的界面元素来告知用户这个可选项。
注意: 当处在全屏模式中,浏览其他页面,切换标签页,或者切换到其他应用 (例如使用 Alt-Tab) 也会导致退出全屏模式。
注意:全屏请求必须在事件处理函数中调用,否则将会被拒绝。
前缀
注意:现在,只有 Firefox 64 和 Chrome 71 支持无前缀。
目前并不是所有的浏览器都实现了 API 的无前缀版本, 这里有一份表格总结了前缀和它们之间的命名区别
可使用插件 Fscreen