Element.requestFullscreen()

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

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

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

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

语法

var Promise = Element.requestFullscreen(options);

参数

options 可选

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

返回值

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

异常

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

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

示例

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

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! (en-US)

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

参阅