全屏 API

接口

全屏 API 没有自己的接口。相反，它通过增强多个其他接口来添加所需的方法、属性和事件处理器，以提供全屏功能。这些接口在以下部分中列出。

实例方法

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

Document 接口的实例方法

Document.exitFullscreen()

请求用户代理从全屏模式切换回窗口模式。返回一个 Promise，其在全屏模式完全关闭后兑现。

Element 接口的实例方法

Element.requestFullscreen()

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

实例属性

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement 属性告诉你当前在 DOM（或影子 DOM）中以全屏模式显示的 Element。如果为 null，则文档（或影子 DOM）没有处于全屏模式。

Document.fullscreenEnabled

fullscreenEnabled 属性告诉你是否可以启用全屏模式。如果由于任何原因（例如 "fullscreen" 特性不被允许，或不支持全屏模式）而无法启用全屏模式，此属性为 false。

过时属性

Document.fullscreen

一个布尔值，如果文档有一个当前正在以全屏模式显示的元素，则为 true；否则返回 false。

备注：请使用 Document 或 ShadowRoot 的 fullscreenElement 属性代替；如果它不为 null，则它是一个当前正在以全屏模式显示的 Element。

事件

fullscreenchange

当元素进入或退出全屏模式时发送给该 Element。

fullscreenerror

如果尝试将元素切换到或退出全屏模式时发生错误，则发送给该 Element。

控制访问

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

使用说明

用户可以选择按 ESC（或 F11）键退出全屏模式，而不是等待站点或应用程序以编程方式退出全屏模式。确保在用户界面中提供适当的用户界面元素，告知用户此选项对他们可用。

示例

简单的全屏用法

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

查看实时示例

监听 Enter 键

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

document.addEventListener(
  "keydown",
  (e) => {
    if (e.key === "Enter") {
      toggleFullScreen();
    }
  },
  false,
);

切换全屏模式

上述事件处理器在用户按下 Enter 键时调用此代码。

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

这首先查询 document 的 fullscreenElement 属性的值。在实际部署中，此时，你需要检查其前缀版本（例如 mozFullScreenElement、msFullscreenElement 或 webkitFullscreenElement）。如果值为 null，文档当前处于窗口模式，因此我们需要切换到全屏模式；否则，它是当前处于全屏模式的元素。切换到全屏模式通过在 <video> 元素上调用 Element.requestFullscreen() 来完成。

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

规范

浏览器兼容性

api.Document.fullscreenElement

api.Document.fullscreenEnabled

api.Document.exitFullscreen

api.Element.requestFullscreen

参见

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