Fullscreen API

接口

全屏 API 没有自己的接口。相反，它扩展了几个其他接口，以添加提供全屏功能所需的方法、属性和事件处理程序。这些在以下各节中列出。

实例方法

全屏 API 向 Document 和 Element 接口添加了方法，以允许打开和关闭全屏模式。

Document 接口上的实例方法

Document.exitFullscreen()

请求 用户代理 从全屏模式切换回窗口模式。返回一个 Promise，在全屏模式完全关闭后得到解决。

Element 接口上的实例方法

Element.requestFullscreen()

请求用户代理将指定元素（及其后代元素）置于全屏模式，移除所有浏览器 UI 元素以及屏幕上的所有其他应用程序。返回一个 Promise，在全屏模式激活后得到解决。

实例属性

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement 属性会告诉你当前在 DOM（或 shadow DOM）中以全屏模式显示的 Element。如果此属性为 null，则表示文档（或 shadow DOM）未处于全屏模式。

Document.fullscreenEnabled

fullscreenEnabled 属性告诉你是否可以启用全屏模式。如果由于任何原因（例如“fullscreen”功能不允许，或不支持全屏模式）全屏模式不可用，则此属性为 false。

已废弃的属性

Document.fullscreen 已弃用

一个布尔值，如果文档当前显示全屏元素，则为 true；否则返回 false。

注意：请改用 fullscreenElement 属性在 Document 或 ShadowRoot 上；如果不为 null，则表示当前以全屏模式显示的 Element。

事件

fullscreenchange

当 Element 进入或退出全屏模式时发送。

fullscreenerror

尝试将 Element 切换到全屏模式或退出全屏模式时发生错误时发送。

控制访问

全屏模式的可用性可以通过 权限策略 进行控制。全屏模式功能由字符串 "fullscreen" 标识，默认允许列表值为 "self"，这意味着在顶级文档上下文中以及与最顶层文档同源的嵌套浏览上下文中允许全屏模式。

用法说明

用户可以通过按 ESC（或 F11）键退出全屏模式，而不是等待网站或应用程序以编程方式执行此操作。请确保在用户界面中提供适当的用户界面元素，告知用户此选项可用。

示例

简单的全屏使用

在此示例中，视频在一个网页中呈现。按 Enter 键可让用户在视频的窗口模式和全屏模式之间切换。

查看实时示例

监听 Enter 键

页面加载时，运行此代码以设置事件监听器来监听 Enter 键。

const video = document.getElementById("video");

// On pressing ENTER call toggleFullScreen method
document.addEventListener("keydown", (e) => {
  if (e.key === "Enter") {
    toggleFullScreen(video);
  }
});

切换全屏模式

当用户按下 Enter 键时，上面的事件处理程序会调用此代码。

function toggleFullScreen(video) {
  if (!document.fullscreenElement) {
    // If the document is not in full screen mode
    // make the video full screen
    video.requestFullscreen();
  } else {
    // Otherwise exit the full screen
    document.exitFullscreen?.();
  }
}

这首先查看 document 的 fullscreenElement 属性值。如果该值为 null，则表示文档当前处于窗口模式，因此我们需要切换到全屏模式；否则，它就是当前处于全屏模式的元素。通过在 <video> 元素上调用 Element.requestFullscreen() 来切换到全屏模式。

如果全屏模式已激活（fullscreenElement 不为 null），我们将在 document 上调用 exitFullscreen() 来关闭全屏模式。

规范

浏览器兼容性

api.Document.fullscreenElement

api.Document.fullscreenEnabled

api.Document.exitFullscreen

api.Element.requestFullscreen

api.Document.fullscreen

另见

• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen