全屏 API | Web API

在此页

接口
方法
特性
事件
字典
控制访问
用法注意事项
范例
规范
浏览器兼容性
另请参阅
相关话题

全屏 API adds methods to present a specific 元素 (and its descendants) in full-screen mode, and to exit full-screen mode once it is no longer needed. This makes it possible to present desired content—such as an online game—using the user's entire screen, removing all browser user interface elements and other applications from the screen until full-screen mode is shut off.

See the article 全屏 API 指南 for details on how to use the API.

注意： Support for this API varies somewhat across browsers, with many requiring vendor prefixes and/or not implementing the latest specification. See the 浏览器兼容性 section below for details on support for this API. You may wish to consider using a library such as Fscreen for vendor agnostic access to the Fullscreen API.

接口

The Fullscreen API has no interfaces of its own. Instead, it augments several other interfaces to add the methods, properties, and event handlers needed to provide full-screen functionality. These are listed in the following sections.

方法

The Fullscreen API adds methods to the Document and 元素 interfaces to allow turning off and on full-screen mode.

文档接口方法

Document.exitFullscreen(): Requests that the 用户代理 switch from full-screen mode back to windowed mode. Returns a Promise which is resolved once full-screen mode has been completely shut off.

Methods on the Element interface

Element.requestFullscreen(): Asks the user agent to place the specified element (and, by extension, its descendants) into full-screen mode, removing all of the browser's UI elements as well as all other applications from the screen. Returns a Promise which is resolved once full-screen mode has been activated.

特性

Document interface provides properties that can be used to determine if full-screen mode is supported and available, and if full-screen mode is currently active, which element is using the screen.

DocumentOrShadowRoot.fullscreenElement: fullscreenElement property tells you the 元素 that's currently being displayed in full-screen mode on the DOM (or shadow DOM). If this is null , the document is not in full-screen mode.
document.fullscreenEnabled: fullscreenEnabled property tells you whether or not it is possible to engage full-screen mode. This is false if full-screen mode is not available for any reason (such as the "fullscreen" feature not being allowed, or full-screen mode not being supported).

事件处理程序

The Fullscreen API defines two events which can be used to detect when full-screen mode is turned on and off, as well as when errors occur during the process of changing between full-screen and windowed modes. Event handlers for these events are available on the Document and 元素 接口。

注意： These event handler properties are not available as HTML content attributes. In other words, you cannot specify event handlers for fullscreenchange and fullscreenerror in the HTML content. They must be added by JavaScript code.

文档事件处理程序

Document.onfullscreenchange: An event handler for the fullscreenchange event that's sent to a Document when that document is placed into full-screen mode, or when that document exits full-screen mode. This handler is called only when the entire document is presented in full-screen mode.
Document.onfullscreenerror: An event handler for the fullscreenerror event that gets sent to a Document when an error occurs while trying to enable or disable full-screen mode for the entire document.

元素事件处理程序

Element.onfullscreenchange: An event handler which is called when the fullscreenchange event is sent to the element, indicating that the element has been placed into, or removed from, full-screen mode.
Element.onfullscreenerror: An event handler for the fullscreenerror event when sent to an element which has encountered an error while transitioning into or out of full-screen mode.

过时特性

Document.fullscreen: A Boolean value which is true if the document has an element currently being displayed in full-screen mode; otherwise, this returns false . 注意： 使用 fullscreenElement property on the Document or ShadowRoot instead; if it's not null , then it's an 元素 currently being displayed in full-screen mode.

事件

fullscreenchange: 发送给 Document or 元素 when it transitions into or out of full-screen mode.
fullscreenerror: 发送给 Document or 元素 if an error occurs while attempting to switch it into or out of full-screen mode.

字典

FullscreenOptions: Provides optional settings you can specify when calling requestFullscreen() .

控制访问

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.

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

用法注意事项

Users can choose to exit full-screen mode simply by pressing the ESC (或 F11 ) key, rather than waiting for the site or app to programmatically do so. Make sure you provide, somewhere in your user interface, appropriate user interface elements that inform the user that this option is available to them.

注意： Navigating to another page, changing tabs, or switching to another application using any application switcher (or Alt - Tab ) will likewise exit full-screen mode.

范例

In this example, a video is presented in a web page. Pressing the 返回 or Enter key lets the user toggle between windowed and full-screen presentation of the video.

View Live Examples

Watching for the Enter key

When the page is loaded, this code is run to set up an event listener to watch for the Enter key.

document.addEventListener("keypress", function(e) {
  if (e.keyCode === 13) {
    toggleFullScreen();
  }
}, false);

切换全屏模式

This code is called by the event handler above when the user hits the Enter key.

function toggleFullScreen() {
  if (!document.fullscreenElement) {
      document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}

This starts by looking at the value of the document 's fullscreenElement attribute. In a real-world deployment, at this time, you'll want to check for prefixed versions of this ( mozFullScreenElement , msFullscreenElement ，或 webkitFullscreenElement , for example). If the value is null , the document is currently in windowed mode, so we need to switch to full-screen mode; otherwise, it's the element that's currently in full-screen mode. Switching to full-screen mode is done by calling Element.requestFullscreen() 在 <video> 元素。

If full-screen mode is already active ( fullscreenElement 不是 null ), we call exitFullscreen() 在 document to shut off full-screen mode.

规范

规范	状态
全屏 API	实时标准

浏览器兼容性

`Document.fullscreen`

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`fullscreen` 弃用	Chrome 71 71 15 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullscreen`	Edge ≤79 ≤79 ≤79 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullscreen`	Firefox 64 64 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. 9 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozFullScreen`	IE 不支持 No	Opera 58 58 15 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullscreen`	Safari 6 Alternate Name 6 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullScreen`	WebView Android 71 71 ≤37 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullscreen`	Chrome Android 71 71 18 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullscreen`	Firefox Android 64 64 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. 9 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozFullScreen`	Opera Android 50 50 14 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullscreen`	Safari iOS 6 Alternate Name 6 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullScreen`	Samsung Internet Android 10.0 10.0 1.0 Alternate Name Alternate Name Uses the non-standard name: `webkitIsFullscreen`

图例

完整支持
不支持
弃用。不要用于新网站。
用户必须明确启用此特征。
使用非标名称。

`Document.fullscreenElement`

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`fullscreenElement`	Chrome 53 Prefixed 53 Prefixed Prefixed Implemented with the vendor prefix: webkit	Edge ≤18 Prefixed ≤18 Prefixed Prefixed Implemented with the vendor prefix: webkit 12 Prefixed Prefixed Implemented with the vendor prefix: ms	Firefox 64 64 不支持 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. 不支持 9 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozFullScreenElement`	IE Yes Prefixed Yes Prefixed Prefixed Implemented with the vendor prefix: ms	Opera 40 Prefixed 40 Prefixed Prefixed Implemented with the vendor prefix: webkit	Safari Yes Prefixed Yes Prefixed Prefixed Implemented with the vendor prefix: webkit	WebView Android 53 Prefixed 53 Prefixed Prefixed Implemented with the vendor prefix: webkit	Chrome Android 53 Prefixed 53 Prefixed Prefixed Implemented with the vendor prefix: webkit	Firefox Android 64 64 不支持 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. 不支持 9 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozFullScreenElement`	Opera Android 41 Prefixed 41 Prefixed Prefixed Implemented with the vendor prefix: webkit	Safari iOS 部分支持 12 Alternate Name 部分支持 12 注意事项 Alternate Name 注意事项 Full-screen mode is only supported on the iPad. Alternate Name Uses the non-standard name: `webkitFullscreenElement`	Samsung Internet Android 6.0 Prefixed 6.0 Prefixed Prefixed Implemented with the vendor prefix: webkit

图例

完整支持
部分支持
见实现注意事项。
用户必须明确启用此特征。
使用非标名称。
要求使用供应商前缀或不同名称。

`Document.fullscreenEnabled`

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`fullscreenEnabled`	Chrome 45 45 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit	Edge 12	Firefox 64 64 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. 10 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozFullScreenEnabled`	IE 11 Alternate Name 11 Alternate Name Alternate Name Uses the non-standard name: `msFullScreenEnabled`	Opera Yes	Safari ?	WebView Android 45 45 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit	Chrome Android 45 45 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit	Firefox Android 64 64 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. 10 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozFullScreenEnabled`	Opera Android Yes	Safari iOS ?	Samsung Internet Android 5.0 5.0 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit

图例

完整支持
兼容性未知 ?
用户必须明确启用此特征。
使用非标名称。
要求使用供应商前缀或不同名称。

`Document.exitFullscreen`

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`exitFullscreen`	Chrome 45 45 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit	Edge 12	Firefox 64 64 不支持 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. 不支持 9 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozCancelFullScreen`	IE 11 Alternate Name 11 Alternate Name Alternate Name Uses the non-standard name: `msExitFullscreen`	Opera 15 Prefixed 15 Prefixed Prefixed Implemented with the vendor prefix: webkit	Safari 5.1 Prefixed 5.1 Prefixed Prefixed Implemented with the vendor prefix: webkit	WebView Android 45 45 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit	Chrome Android 45 45 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit	Firefox Android 64 64 不支持 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. 不支持 9 — 65 Alternate Name Alternate Name Uses the non-standard name: `mozCancelFullScreen`	Opera Android Yes	Safari iOS 不支持 No	Samsung Internet Android 5.0 5.0 Yes Prefixed Prefixed Implemented with the vendor prefix: webkit
返回 `Promise`	Chrome 71	Edge 79	Firefox 64	IE 不支持 No	Opera ?	Safari ?	WebView Android 71	Chrome Android 71	Firefox Android 64	Opera Android ?	Safari iOS 不支持 No	Samsung Internet Android 10.0

图例

完整支持
不支持
兼容性未知 ?
用户必须明确启用此特征。
使用非标名称。
要求使用供应商前缀或不同名称。

`Element.requestFullscreen`

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`requestFullscreen`	Chrome 69 69 15 Prefixed Prefixed Implemented with the vendor prefix: webkit	Edge 79 79 79 Prefixed Prefixed Implemented with the vendor prefix: webkit 不支持 12 — 14 Prefixed Prefixed Implemented with the vendor prefix: webkit	Firefox 64 64 不支持 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. 不支持 9 — 65 注意事项 Alternate Name 注意事项 Before Firefox 44, Firefox incorrectly allowed elements inside a `<frame>` or `<object>` element to request, and to be granted, fullscreen. In Firefox 44 and onwards this has been fixed: only elements in the top-level document or in an `<iframe>` element with the `allowfullscreen` attribute can be displayed fullscreen. Alternate Name Uses the non-standard name: `mozRequestFullScreen`	IE 11 Prefixed 11 Prefixed Prefixed Implemented with the vendor prefix: ms	Opera 58 58 15 Prefixed Prefixed Implemented with the vendor prefix: webkit 不支持 12 — 15 Prefixed Prefixed Implemented with the vendor prefix: o	Safari 6 Prefixed 6 Prefixed Prefixed Implemented with the vendor prefix: webkit	WebView Android 69 69 ≤37 Prefixed Prefixed Implemented with the vendor prefix: webkit	Chrome Android 69 69 18 Prefixed Prefixed Implemented with the vendor prefix: webkit	Firefox Android 64 64 不支持 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. 不支持 9 — 65 注意事项 Alternate Name 注意事项 Before Firefox 44, Firefox incorrectly allowed elements inside a `<frame>` 或 `<object>` to request, and to be granted, fullscreen. In Firefox 44 and onwards this has been fixed: only elements in the top-level document or in an `<iframe>` 采用 `allowfullscreen` attribute can be displayed fullscreen. Alternate Name Uses the non-standard name: `mozRequestFullScreen`	Opera Android 50 50 14 Prefixed Prefixed Implemented with the vendor prefix: webkit 不支持 12 — 14 Prefixed Prefixed Implemented with the vendor prefix: o	Safari iOS 6 Prefixed 6 Prefixed 注意事项 Prefixed Implemented with the vendor prefix: webkit 注意事项 Only available on iPad, not on iPhone. Shows an overlay button which can not be disabled.	Samsung Internet Android 10.0 10.0 1.0 Prefixed Prefixed Implemented with the vendor prefix: webkit
`选项` 参数	Chrome 71	Edge 79	Firefox 64	IE 不支持 No	Opera ?	Safari ?	WebView Android 71	Chrome Android 71	Firefox Android 64	Opera Android ?	Safari iOS ?	Samsung Internet Android 10.0
返回 `Promise`	Chrome 71	Edge 79	Firefox 64	IE 不支持 No	Opera 不支持 No	Safari 不支持 No	WebView Android 71	Chrome Android 71	Firefox Android 64	Opera Android 不支持 No	Safari iOS 不支持 No	Samsung Internet Android 10.0

图例


不支持
兼容性未知 ?
见实现注意事项。
用户必须明确启用此特征。
使用非标名称。
要求使用供应商前缀或不同名称。

另请参阅

元数据

最后修改： Aug 14, 2020

在此页

接口

方法