深入详解JavaScript中调用exitFullscreen退出全屏的正确方法与运行机制。解析调用主体归属、状态检测、Promise异常拦截、跨浏览器兼容封装以及全屏事件监听等核心实践。
JS调用exitFullscreen退出全屏的正确方法
时间:2026-11-22
浏览:593
文章目录
document.exitFullscreen()。初学者常犯的两个典型错误是在具体的 DOM 元素节点上调用退出方法,或者在当前页面尚未处于全屏状态时强行调用,这会导致控制台抛出 TypeError 或 DOMException 异常。本文将从 API 的设计机制出发,提供包含状态前置检测、Promise 异常处理、跨浏览器兼容封装以及 fullscreenchange 状态协同在内的完整规范方案。
一、核心原则:为什么退出全屏必须在 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 属性。记住口诀:“元素负责申请进入,文档负责全局退出”。
二、标准调用规范:安全退出全屏的四个步骤
虽然直接执行 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 退出时,界面的全屏状态就会发生脱节。
三、跨浏览器兼容性封装(支持 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 |
为了在工程项目中实现无缝降级,我们可以将检测和退出逻辑封装为通用的安全工具函数:
/**
* 获取当前处于全屏的元素(兼容各大厂商前缀)
* @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 的。如果父容器没有显式声明权限,在子页面内调用全屏或退出全屏会直接被浏览器策略拒绝。
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 进行全屏或退出操作,应提前做好降级或提示处理。
五、全屏状态驱动 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"特性。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。