JS调用exitFullscreen退出全屏的正确方法

作者:竹影

时间:2026-11-22

浏览:593

深入详解JavaScript中调用exitFullscreen退出全屏的正确方法与运行机制。解析调用主体归属、状态检测、Promise异常拦截、跨浏览器兼容封装以及全屏事件监听等核心实践。

文章目录
Web API · 前端交互开发指南
在 JavaScript 中,退出全屏模式的正确方法是执行 document.exitFullscreen()。初学者常犯的两个典型错误是在具体的 DOM 元素节点上调用退出方法,或者在当前页面尚未处于全屏状态时强行调用,这会导致控制台抛出 TypeError 或 DOMException 异常。本文将从 API 的设计机制出发,提供包含状态前置检测、Promise 异常处理、跨浏览器兼容封装以及 fullscreenchange 状态协同在内的完整规范方案。
JS调用exitFullscreen退出全屏的正确方法
缩略图概览:JavaScript Fullscreen API 的职责分工——元素发起全屏,根文档终结全屏

一、核心原则:为什么退出全屏必须在 document 上调用?

Fullscreen API 的设计体现了严密的 DOM 层次隔离思想。当我们希望某个特定元素(如 <video> 视频播放器或 <div class="dashboard"> 仪表盘)全屏显示时,调用的是该元素自身的实例方法:

// 进入全屏:调用在具体的 DOM 元素上
const playerElement = document.getElementById('player');
playerElement.requestFullscreen();

这一步的操作逻辑是:“请求将这个具体的 DOM 节点放大并铺满当前屏幕”。

但当退出全屏时,浏览器的底层机制完全不同。无论是网页内的哪个子元素处于全屏状态,整个浏览器视口在同一时刻只允许维护一个顶级全屏图层。控制页面是否回归到正常的窗口布局模式,属于页面视口管理权的收回。因此,W3C 标准将 exitFullscreen() 方法挂载在全局的 Document 对象上,而不是 Element 上。

高频报错剖析: 如果你编写了 playerElement.exitFullscreen(),浏览器会直接报错:
Uncaught TypeError: playerElement.exitFullscreen is not a function。
因为 Element.prototype 上根本不存在 exitFullscreen 属性。记住口诀:“元素负责申请进入,文档负责全局退出”。
JS调用exitFullscreen退出全屏的正确方法
图 1:浏览器全屏 API 的主体归属与 DOM 层级拓扑图

二、标准调用规范:安全退出全屏的四个步骤

虽然直接执行 document.exitFullscreen() 能够完成退出操作,但在生产环境中直接裸调仍会引发隐患。现代浏览器对于全屏操作要求返回 Promise 对象,并在文档未处于活跃状态或未全屏时抛出异常。

要写出鲁棒性高的代码,必须严格执行以下四个步骤:

步骤 1:判断当前是否处于全屏状态

调用退出方法之前,必须先读取 document.fullscreenElement 属性。该属性会返回当前处于全屏模式的元素;如果页面当前处于常规视口状态,则该属性严格返回 null。

if (document.fullscreenElement) {
  // 当前确实有元素处于全屏状态,允许执行退出
} else {
  // 未全屏,切勿调用 exitFullscreen,否则会抛出 DOMException
  return;
}

步骤 2:在 document 上派发 exitFullscreen

确认全屏状态存在后,向根文档对象派发 document.exitFullscreen()。

步骤 3:捕获返回的 Promise 异常

exitFullscreen() 是一个异步方法,返回一个 Promise<void>。如果在调用瞬间页面发生路由跳转、iframe 失去焦点或受浏览器安全策略阻断,该 Promise 会被 reject。如果不添加捕获逻辑,控制台会出现 Uncaught (in promise) 错误提示。

document.exitFullscreen()
  .catch(err => {
    console.error('退出全屏失败:', err);
  });

步骤 4:解耦界面更新,依托 fullscreenchange 事件

许多开发者习惯在点击“退出全屏”按钮的 click 事件回调中直接修改按钮图标或文案。这是常见的逻辑缺陷——用户完全可以通过敲击键盘的 ESC 键退出全屏。如果把 UI 更新逻辑与点击事件绑定,当用户按 ESC 退出时,界面的全屏状态就会发生脱节。

JS调用exitFullscreen退出全屏的正确方法
图 2:安全调用 exitFullscreen 的四步标准化流程图

三、跨浏览器兼容性封装(支持 WebKit / Gecko / Trident)

目前各大现代主流浏览器(Chrome 71+、Firefox 64+、Edge 79+ 以及 macOS Safari 16.4+)均已全面支持标准未带前缀的 API。然而在部分国内主流双核浏览器的低版本内核、历史版本 Safari 或政企维护的遗留系统环境中,仍存在带有各厂商前缀的实现:

规范 / 内核分支 退出全屏方法 全屏激活元素属性 适用典型浏览器
W3C 现代标准 document.exitFullscreen() document.fullscreenElement Chrome, Edge, Firefox, 新版 Safari
WebKit 前缀 document.webkitExitFullscreen() document.webkitFullscreenElement 旧版 Safari, iPadOS WebKit
Gecko 前缀 document.mozCancelFullScreen() document.mozFullScreenElement Firefox 64 之前版本
Trident 前缀 document.msExitFullscreen() document.msFullscreenElement IE 11 及早期 Edge
JS调用exitFullscreen退出全屏的正确方法
图 3:跨浏览器 Fullscreen API 兼容映射与降级链

为了在工程项目中实现无缝降级,我们可以将检测和退出逻辑封装为通用的安全工具函数:

/**
 * 获取当前处于全屏的元素(兼容各大厂商前缀)
 * @returns {Element|null}
 */
function getFullscreenElement() {
  return document.fullscreenElement ||
         document.webkitFullscreenElement ||
         document.mozFullScreenElement ||
         document.msFullscreenElement ||
         null;
}

/**
 * 安全退出全屏的跨浏览器兼容实现
 * @returns {Promise<void>}
 */
async function exitFullScreenSafely() {
  // 1. 状态判断:非全屏状态下直接返回,杜绝不必要的调用
  if (!getFullscreenElement()) {
    return;
  }

  // 2. 按标准与各内核优先级尝试执行退出
  try {
    if (document.exitFullscreen) {
      await document.exitFullscreen();
    } else if (document.webkitExitFullscreen) {
      await document.webkitExitFullscreen();
    } else if (document.mozCancelFullScreen) {
      await document.mozCancelFullScreen();
    } else if (document.msExitFullscreen) {
      await document.msExitFullscreen();
    } else {
      console.warn('当前运行环境不支持全屏控制 API');
    }
  } catch (error) {
    console.error('退出全屏过程中捕获异常:', error);
  }
}

四、关键细节与边界踩坑排查

在实际项目落地中,除了 API 的调用对象和语法,以下三个边界场景也是全屏退出逻辑中最容易滋生 Bug 的环节:

1. 全屏切换切换按钮(Toggle)的正确写法

很多业务场景下,“全屏”与“退出全屏”复用同一个操作按钮。实现 Toggle 逻辑时,应该以 getFullscreenElement() 作为唯一分流条件:

async function toggleFullscreen(targetElement) {
  if (getFullscreenElement()) {
    // 正在全屏,执行退出
    await exitFullScreenSafely();
  } else {
    // 未全屏,让指定目标元素进入全屏
    if (targetElement.requestFullscreen) {
      await targetElement.requestFullscreen();
    } else if (targetElement.webkitRequestFullscreen) {
      await targetElement.webkitRequestFullscreen();
    }
  }
}

2. iframe 嵌套权限问题

如果你的网页被嵌入在 <iframe> 容器内运行,子页面默认是没有权限调用 Fullscreen API 的。如果父容器没有显式声明权限,在子页面内调用全屏或退出全屏会直接被浏览器策略拒绝。

解决方案: 确保父页面的 iframe 标签添加了标准的 allow="fullscreen" 特性(或旧版 allowfullscreen 属性):
<iframe src="subpage.html" allow="fullscreen"></iframe>

3. iPhone 上 Safari 的环境限制

在 iOS 系统的 iPhone 设备上,苹果出于系统交互设计规范,不支持对普通 DOM 节点(如 div)调用 requestFullscreen;仅对原生的 <video> 标签支持专有的 videoElement.webkitEnterFullscreen() 和 videoElement.webkitExitFullscreen()。如果在 iPhone 上尝试对 div 进行全屏或退出操作,应提前做好降级或提示处理。

JS调用exitFullscreen退出全屏的正确方法
图 4:全屏退出生命周期与常见异常排查决策树

五、全屏状态驱动 UI 的完整生产范例

下面提供一段符合现代前端工程规范的完整交互代码。该示例将状态检测、退出操作与全局事件监听完全解耦,确保无论用户是通过页面按钮点击还是按下物理 ESC 键退出全屏,按钮文案和界面交互都能绝对同步:

// HTML 结构:
// <div id="container" class="preview-box">
//   <button id="fsBtn">切换全屏</button>
// </div>

const fsButton = document.getElementById('fsBtn');
const container = document.getElementById('container');

// 1. 统一的 UI 状态同步函数
function updateFullscreenUI() {
  const activeEl = document.fullscreenElement || document.webkitFullscreenElement;
  if (activeEl) {
    fsButton.textContent = '退出全屏';
    container.classList.add('is-fullscreen');
  } else {
    fsButton.textContent = '进入全屏';
    container.classList.remove('is-fullscreen');
  }
}

// 2. 按钮点击事件处理
fsButton.addEventListener('click', async () => {
  const isFullscreen = Boolean(document.fullscreenElement || document.webkitFullscreenElement);
  
  if (isFullscreen) {
    // 执行退出:必须在 document 上调用
    if (document.exitFullscreen) {
      await document.exitFullscreen().catch(err => console.error(err));
    } else if (document.webkitExitFullscreen) {
      document.webkitExitFullscreen();
    }
  } else {
    // 执行进入:在目标元素 container 上调用
    if (container.requestFullscreen) {
      await container.requestFullscreen().catch(err => console.error(err));
    } else if (container.webkitRequestFullscreen) {
      container.webkitRequestFullscreen();
    }
  }
});

// 3. 监听全局全屏变更事件(关键点:同时监听标准与 webkit 事件)
document.addEventListener('fullscreenchange', updateFullscreenUI);
document.addEventListener('webkitfullscreenchange', updateFullscreenUI);

// 初始化 UI 表现
updateFullscreenUI();

六、自查决策清单

在提交你的全屏控制模块代码前,建议通过以下清单逐项自检:

  • 调用对象验证: 退出全屏的方法是 document.exitFullscreen,绝无 element.exitFullscreen。
  • 状态前置检查: 是否在执行退出前判定了 document.fullscreenElement 是否非空,杜绝无意义的报错。
  • Promise 异常保护: 是否对 exitFullscreen() 返回的 Promise 添加了 .catch() 或包裹在 try...catch 中。
  • Esc 键行为对齐: 页面按钮文案、图标显隐是否挂载在 fullscreenchange 全局事件中统一分发,而不是直接写在按钮点击回调里。
  • 嵌入环境许可: 如运行于微前端或内嵌页面,确认宿主 <iframe> 具备 allow="fullscreen" 特性。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章