JS调用Document.exitFullscreen()退出全屏的标准写法
全面解析JavaScript中调用Document.exitFullscreen()退出全屏的标准写法、核心机制、异步Promise处理、状态防护及常见误区。
在 JavaScript 全屏 API(Fullscreen API)中,退出全屏的标准方法是 document.exitFullscreen()。该方法是异步执行的,返回一个 Promise 对象。在实际业务开发中,开发者最容易踩入两类陷阱:一是错误地在具体的 DOM 元素上调用该方法,二是未检查当前页面是否正处于全屏状态便直接调用,进而导致浏览器抛出 TypeError 异常。本文将系统讲解 Document.exitFullscreen() 的标准写法、调用守卫、异步捕获、事件协同以及历史浏览器兼容降级策略。
一、核心认知:为什么是 Document 而不是 Element
在全屏 API 的规范设计中,进入全屏与退出全屏的承载对象具有明显的不对称性:
- 进入全屏:调用的是具体 DOM 元素的方法,例如
videoElement.requestFullscreen()或document.documentElement.requestFullscreen(),其意图是让该指定元素脱离常规文档流,覆盖整个屏幕视图。 - 退出全屏:调用的是顶级文档对象的方法,即
document.exitFullscreen()。因为无论先前是哪个具体元素进入了全屏,全屏模式本身都属于当前浏览上下文(Document Context)的全局呈现状态,由文档顶层统一撤销并恢复常规渲染。
element.exitFullscreen()。在常规 DOM 元素的原型链上并没有该方法,这样调用会直接抛出 Uncaught TypeError: element.exitFullscreen is not a function。
二、标准调用写法与状态守卫
按照 W3C 规范,如果当前文档并没有任何元素处于全屏状态(即 document.fullscreenElement === null),此时强制调用 document.exitFullscreen(),返回的 Promise 将会被 reject,并在控制台中产生未捕获的 TypeError。
因此,工业级的前端实现必须在调用前加入状态守卫(Guard Check),先验证当前是否存在全屏元素,然后再执行退出并妥善处理 Promise:
1. 基于 async/await 的标准写法(推荐)
/**
* 安全退出全屏模式的标准函数
* @returns {Promise<void>}
*/
async function exitFullscreenSafely() {
// 1. 状态守卫:检查当前文档是否处于全屏状态
if (!document.fullscreenElement) {
// 当前并未处于全屏状态,安全跳过退出操作
return;
}
try {
// 2. 调用标准方法并等待异步 Promise 完成
await document.exitFullscreen();
} catch (error) {
// 3. 捕获权限受阻或上下文失效等意外异常
console.error('退出全屏失败:', error);
}
}
2. 基于 Promise 链式调用的标准写法
function exitFullscreenPromise() {
if (!document.fullscreenElement) {
return Promise.resolve();
}
return document.exitFullscreen().catch((error) => {
console.warn('退出全屏操作未能成功执行:', error);
});
}
三、全屏状态联动:不要只在退出按钮中修改 UI
在实际网页中,全屏的退出并不完全依赖网页里的“退出全屏”按钮。用户随时可以按下键盘上的 Esc 键,或者通过操作系统的全屏控制栏主动退出全屏。
如果你仅仅在按钮点击事件触发 document.exitFullscreen() 的回调里更新按钮图标或文字状态,一旦用户通过 Esc 退出,页面上的按钮状态就会与实际显示状态完全脱节。
最佳实践: 将 UI 状态更新与 fullscreenchange 事件绑定,让视图完全由全屏状态的变更事件驱动,实现真正的单向状态流与解耦。
// 统一监听文档的全屏变化事件
document.addEventListener('fullscreenchange', () => {
const isCurrentlyFullscreen = Boolean(document.fullscreenElement);
// 根据全屏状态统一切换按钮文字或样式
const toggleBtn = document.getElementById('fullscreenToggleBtn');
if (toggleBtn) {
toggleBtn.textContent = isCurrentlyFullscreen ? '退出全屏' : '进入全屏';
toggleBtn.setAttribute('aria-pressed', String(isCurrentlyFullscreen));
}
});
// 监听可能发生的全屏错误
document.addEventListener('fullscreenerror', (event) => {
console.error('全屏模式切换发生错误:', event);
});
四、历史浏览器与内核前缀兼容方案
现代主流浏览器(包括 Chrome 71+、Firefox 64+、Edge 79+、Safari 16.4+)均已全面支持标准未加前缀的 document.exitFullscreen()。但在涉及特定内嵌 WebView、定制工控屏浏览器或维护较旧的企业级项目时,仍需考虑厂商前缀的降级适配。
| 规范阶段 | 全屏检测属性 | 退出全屏方法 | 典型适用环境 |
|---|---|---|---|
| W3C 标准规范 | document.fullscreenElement |
document.exitFullscreen() |
所有现代主流桌面与移动浏览器 |
| WebKit 前缀 | document.webkitFullscreenElement |
document.webkitExitFullscreen() |
旧版 Safari、旧版 Android WebView |
| Gecko (火狐) 前缀 | document.mozFullScreenElement |
document.mozCancelFullScreen() |
旧版 Firefox(注意方法名为 Cancel) |
| Trident / IE11 | document.msFullscreenElement |
document.msExitFullscreen() |
IE 11 及早期的 EdgeHTML |
工业级跨浏览器退出全屏封装实现
/**
* 跨浏览器兼容的退出全屏通用封装
* @returns {Promise<void>}
*/
function exitFullscreenUniversal() {
// 1. 获取当前处于全屏的元素(带前缀兼容)
const fullscreenElement =
document.fullscreenElement ||
document.webkitFullscreenElement ||
document.mozFullScreenElement ||
document.msFullscreenElement;
if (!fullscreenElement) {
return Promise.resolve();
}
// 2. 依次匹配标准方法与各内核前缀方法
if (document.exitFullscreen) {
return document.exitFullscreen();
} else if (document.webkitExitFullscreen) {
return Promise.resolve(document.webkitExitFullscreen());
} else if (document.mozCancelFullScreen) {
return Promise.resolve(document.mozCancelFullScreen());
} else if (document.msExitFullscreen) {
return Promise.resolve(document.msExitFullscreen());
}
return Promise.reject(new Error('当前运行环境不支持 Fullscreen API'));
}
五、常见问题排查与注意事项
-
问题 1:调用时报错
TypeError: Document not active或全屏未开启
原因: 在未全屏或者非当前激活标签页中调用了exitFullscreen()。排查方案是确保在调用前检查document.fullscreenElement是否有效。 -
问题 2:在 iframe 中调用退出全屏无效或报错
原因: 如果页面嵌入在<iframe>中,iframe 必须声明allow="fullscreen"(或在旧版中包含allowfullscreen属性),否则浏览器的权限策略(Permissions Policy)会阻止全屏状态变更。 -
问题 3:误在全屏元素的销毁阶段同步调用
原因: 如果在组件卸载(如 React 的componentWillUnmount或 Vue 的unmounted)时需要退出全屏,必须先确认该组件或其子元素是否即为document.fullscreenElement,避免引发冗余调用或竞争条件。
六、总结
调用 Document.exitFullscreen() 退出全屏时,核心要把握三条关键准则:第一,明确调用主体是 document 而非任意 DOM 节点;第二,前置检查 document.fullscreenElement,避免在未全屏时盲目调用而抛出未捕获异常;第三,视图状态应统一监听 fullscreenchange 事件,以兼容用户键盘按键等系统级退出行为。
html5-qrcode库集成教程:JS实现H5页面扫码功能
2026-11-22 20:05:19
HTML按钮点击调用JS函数的三种常用方法
2026-11-22 19:28:03
JS使用navigator.clipboard.writeText复制文字到剪贴板
2026-11-22 18:23:22
调试JS兼容性问题:怎么在Chrome中模拟旧版本浏览器环境
2026-11-22 15:56:53
JS点击按钮切换页面背景颜色的代码实现
2026-11-22 15:07:04








