Element.requestFullscreen()

您正在阅读此内容的英文版本,因为该语系尚未翻译。 帮助我们翻译此文章吧!

Element.requestFullscreen() 方法用于发出异步请求使元素进入全屏模式。

调用此API并不能保证元素一定能够进入全屏模式。如果元素被允许进入全屏幕模式,返回的Promise会resolve,并且该元素会收到一个fullscreenchange事件,通知它已经进入全屏模式。如果全屏请求被拒绝,返回的promise会变成rejected并且该元素会收到一个fullscreenerror事件。如果该元素已经从原来的文档中分离,那么该文档将会收到这些事件。

早期的Fullscreen API实现总是会把这些事件发送给document,而不是调用的元素,所以你自己可能需要处理这样的情况。参考 Browser compatibility in [Page not yet written] 来得知哪些浏览器做了这个改动。

注意:这个方法只能在用户交互或者设备方向改变的时候调用,否则将会失败。

语法

var Promise = Element.requestFullscreen(options);

参数

options 可选

一个FullscreenOptions对象提供切换到全屏模式的控制选项。目前,唯一的选项是navigationUI,这控制了是否在元素处于全屏模式时显示导航条UI。默认值是"auto",表明这将由浏览器来决定是否显示导航条。

返回值

在完成切换全屏模式后,返回一个已经用值 undefined resolved的Promise

异常

requestFullscreen() 通过拒绝返回的 Promise来生成错误条件,而不是抛出一个传统的异常。拒绝控制器接收以下的某一个值:

TypeError
在以下几种情况下,会抛出TypeError
  • 文档中包含的元素未完全激活,也就是说不是当前活动的元素。
  • 元素不在文档之内。
  • 因为功能策略限制配置或其他访问控制,元素不被允许使用"fullscreen"功能。
  • 元素和它的文档是同一个节点。 

示例

在调用requestFullScreen()之前,可以对fullscreenchange 和 fullscreenerror事件进行监听,这样在请求进入全屏模式成功或者失败时都能收到事件通知。

API规格

Specification Status Comment
Fullscreen API
Element.requestFullScreen()
Living Standard Initial definition

浏览器兼容性

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 Internet Explorer Edge Opera Safari
Basic support (Yes)webkit[1] (Yes) 9.0 (9.0) as mozRequestFullScreen[2]
47.0 (47.0) (behind full-screen-api.unprefix.enabled
11ms[3] (Yes)[3] ? ?
Feature Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? (Yes) 9.0 (9.0) as mozRequestFullScreen[2]
47.0 (47.0) (behind full-screen-api.unprefix.enabled
? ? ?

[1] 同样以webkitRequestFullScreen方法实现。

[2] 使用带有浏览器前缀的mozRequestFullScreen方法实现。在火狐44之前版本,Gecko浏览器内核错误地允许frame里面元素以及object元素进入全屏模式。而在之后的版本,这个漏洞被修复:仅允许位于顶部文档(top-level document)的元素,以及拥有allowfullscreen属性的iframe的内部元素进入全屏显示。. 

[3] 使用IE时,最后的screen的s为小写,也即msRequestFullscreen,否则无效

[4] 谷歌浏览器前缀webkitRequestFullScreen()里最后的Screen的S也可以为小写s,建议写成驼峰命名法

[5]将浏览器前缀兼容封装成函数

function toFullVideo(){

  if(videoDom.requestFullscreen){

    return videoDom.requestFullscreen();

  }else if(videoDom.webkitRequestFullScreen){

    return videoDom.webkitRequestFullScreen();

  }else if(videoDom.mozRequestFullScreen){

    return videoDom.mozRequestFullScreen();

  }else{

    return videoDom.msRequestFullscreen();

  }

}

[6] 详见 documentation on MSDN.

参阅