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

浏览器兼容性

BCD tables only load in the browser

参阅