详细介绍如何使用JavaScript封装一套兼容主流浏览器及旧版内核的退出全屏通用函数,涵盖标准W3C与WebKit、Gecko、Trident厂商前缀处理、Promise与上下文绑定机制、全屏状态检测与常见异常规避。
JS封装跨浏览器退出全屏的通用函数示例
时间:2026-11-22
浏览:549
文章目录
图 0:跨浏览器全屏退出交互与通用封装设计概念
在开发大屏数据可视化、视频播放器或富交互Web应用时,退出全屏与进入全屏同样重要。现代浏览器普遍遵循W3C Fullscreen API规范,但在存量设备、特定内核(如老版本WebKit、Firefox历史版本、IE 11等)中,API命名、前缀以及返回值差异极大;若在未全屏状态下直接调用原生退出方法,标准浏览器甚至会抛出异常中断主逻辑。本文将直接提供一个经过边界校验与上下文绑定的跨浏览器退出全屏通用函数,并拆解其设计原理与实战注意事项。
一、退出全屏 API 的核心机制与内核差异
理解退出全屏封装的第一步,是明确全屏进入与退出的挂载对象差异:请求进入全屏时调用的是具体元素节点的 element.requestFullscreen(),但退出全屏时操作的则是全局上下文 document.exitFullscreen()。这意味着退出指令永远作用于整个文档层次,而不是特定的某个DOM容器。
由于全屏API经历过漫长的演进过程,各大浏览器内核留下了不同历史前缀。在编写兼容逻辑时,需要系统梳理各内核的方法名称、属性命名及大小写区别:
| 规范 / 浏览器环境 | 退出全屏方法 | 当前全屏元素属性 | 状态变更监听事件 | 执行与返回特性 |
|---|---|---|---|---|
| W3C 现行标准 (Chrome 71+, Edge, Firefox 64+) | document.exitFullscreen() |
document.fullscreenElement |
fullscreenchange |
返回原生 Promise,支持链式异步调用 |
| WebKit 内核 (Safari, 旧版 Chrome) | webkitExitFullscreen() / webkitCancelFullScreen() |
webkitFullscreenElement |
webkitfullscreenchange |
部分早期版本存在大小写变体 |
| Gecko 内核 (Firefox 早期版本) | mozCancelFullScreen() |
mozFullScreenElement |
mozfullscreenchange |
注意方法为 Cancel 且 Screen 首字母大写 |
| Trident / EdgeHTML (IE 11, 旧版 Edge) | msExitFullscreen() |
msFullscreenElement |
MSFullscreenChange |
同步执行无返回值,事件名区分大小写 |
除了方法名前缀不同,另一个关键差异在于返回值:标准API返回一个 Promise 对象,如果当前文档处于全屏状态,Promise 会被成功解决(resolved);如果文档本身没有处于全屏状态,直接调用原生 document.exitFullscreen() 会导致 Promise 被拒绝(rejected),若未做捕获便会在控制台产生 Uncaught (in promise) TypeError 报错。因此,健壮的封装必须包含前置状态检测。
图 1:浏览器全屏 API 标准方法与私有前缀映射矩阵
二、跨浏览器退出全屏的核心通用函数封装
基于上述差异,通用的封装方案需要完成三项关键任务:首先检测当前是否真处于全屏状态,避免误调用报错;其次按优先级探测宿主环境支持的具体退出方法,并使用 .call(doc) 锁定 document 上下文;最后通过 Promise.resolve() 抹平现代 Promise 与旧版同步无返回值的差异,向调用方提供一致的异步接口。
1. 辅助函数:跨浏览器获取当前全屏元素
为了判断当前是否有元素全屏,先封装一个安全获取当前全屏元素的函数:
/**
* 获取当前文档中处于全屏状态的元素
* @param {Document} doc 目标文档对象,默认为当前全局 document
* @returns {Element|null} 当前全屏元素或 null
*/
function getFullscreenElement(doc = document) {
if (!doc) return null;
return (
doc.fullscreenElement ||
doc.webkitFullscreenElement ||
doc.mozFullScreenElement ||
doc.msFullscreenElement ||
null
);
}
2. 核心函数:跨浏览器通用退出全屏函数
接下来是核心函数 exitFullscreen() 的完整实现:
/**
* 跨浏览器退出全屏通用函数
* @param {Document} doc 目标文档对象(默认为当前 document,支持传入 iframe.contentDocument)
* @returns {Promise<boolean>} 退出结果:true 表示成功执行退出;false 表示当前非全屏或不支持
*/
function exitFullscreen(doc = document) {
return new Promise((resolve, reject) => {
// 1. 前置条件判断:目标文档有效性
if (!doc) {
resolve(false);
return;
}
// 2. 前置状态检测:如果当前没有元素处于全屏状态,直接安全返回 false
const activeElement = getFullscreenElement(doc);
if (!activeElement) {
resolve(false);
return;
}
// 3. 候选退出全屏方法探测(兼顾标准与 WebKit、Gecko、Trident 前缀)
const exitMethod =
doc.exitFullscreen ||
doc.webkitExitFullscreen ||
doc.webkitCancelFullScreen ||
doc.mozCancelFullScreen ||
doc.msExitFullscreen;
// 4. 如果宿主环境完全不支持全屏 API
if (!exitMethod) {
resolve(false);
return;
}
// 5. 执行退出全屏:必须通过 .call(doc) 绑定上下文,防止 Illegal invocation 报错
try {
const result = exitMethod.call(doc);
// 6. 统一返回值:标准实现返回 Promise,旧内核返回 undefined
if (result && typeof result.then === 'function') {
result
.then(() => resolve(true))
.catch((error) => reject(error));
} else {
resolve(true);
}
} catch (err) {
reject(err);
}
});
}
当通过属性访问提取 doc.exitFullscreen 并保存到局部变量 exitMethod 时,该函数脱离了原有的宿主对象引用。如果在调用时直接写 exitMethod(),在大多数浏览器内部引擎中会导致 this 指针指向全局或为 undefined,从而直接抛出 TypeError: Illegal invocation。使用 .call(doc) 能够确保函数始终在正确的 document 上下文中执行。
图 2:退出全屏通用函数执行决策与降级处理流程
三、配合状态检测与事件监听的完整调用示例
在实际业务中,用户退出全屏往往有两种途径:一种是通过页面上的“退出全屏”按钮调用封装函数;另一种是按下键盘上的物理 Esc 键退出。因为物理按键退出不会触发页面按钮的 click 事件,所以绝对不能仅在按钮点击回调里切换UI状态,而应当统一监听全屏变更事件。
1. 跨浏览器全屏切换与事件绑定示例
下面是一个包含进入/退出双向切换以及全屏事件监听的完整应用示例:
// 1. 跨浏览器全屏切换函数
async function toggleFullscreen(element = document.documentElement) {
const isFullscreen = !!getFullscreenElement();
if (isFullscreen) {
// 当前处于全屏,调用封装的退出函数
await exitFullscreen();
} else {
// 当前未全屏,按前缀请求进入全屏
const requestMethod =
element.requestFullscreen ||
element.webkitRequestFullscreen ||
element.mozRequestFullScreen ||
element.msRequestFullscreen;
if (requestMethod) {
await requestMethod.call(element);
}
}
}
// 2. 统一监听全屏变更事件(同步更新页面图标与文案)
function bindFullscreenChange(callback) {
const eventList = [
'fullscreenchange',
'webkitfullscreenchange',
'mozfullscreenchange',
'MSFullscreenChange'
];
const handler = () => {
const currentEl = getFullscreenElement();
callback(!!currentEl, currentEl);
};
eventList.forEach((eventName) => {
document.addEventListener(eventName, handler);
});
// 返回解绑函数,便于组件销毁时清理
return () => {
eventList.forEach((eventName) => {
document.removeEventListener(eventName, handler);
});
};
}
// 3. 业务挂载演示
const btn = document.getElementById('fullscreen-toggle-btn');
if (btn) {
btn.addEventListener('click', () => {
toggleFullscreen().catch((err) => {
console.warn('全屏切换操作失败:', err);
});
});
}
// 监听状态变化,无论代码退出还是用户按 Esc 退出均可精准响应
bindFullscreenChange((isFullscreen) => {
if (btn) {
btn.textContent = isFullscreen ? '退出全屏' : '进入全屏';
btn.setAttribute('aria-label', isFullscreen ? '退出全屏' : '进入全屏');
}
});
图 3:Web 全屏生命周期与双通道退出时序关系架构图
四、关键注意事项与边界排查
在跨端运行与复杂宿主环境下,退出全屏还涉及若干特殊限制,需要提前规避:
-
iframe 嵌套权限限制:如果页面被嵌入在
<iframe>中,子页面要能够调用全屏相关 API,父级必须在 iframe 元素上显式声明allow="fullscreen"(历史版本使用allowfullscreen="true")。否则,无论是进入还是退出全屏都会被浏览器的权限策略(Permissions Policy)直接拦截。 -
移动端 iOS Safari 的特殊差异:iPhone 上的 Safari 不支持给普通的
div容器开启 DOM 全屏(其document.fullscreenEnabled为false),仅有<video>元素支持原生播放全屏(通过video.webkitEnterFullscreen()与video.webkitExitFullscreen())。在 iPadOS 上则具备与桌面端一致的标准全屏能力。面向移动端小屏设备,通用方案通常应降级为通过 CSSposition: fixed; inset: 0; z-index: 9999;实现伪全屏,并在伪全屏按钮点击时仅操作类名而非调用全屏API。 -
用户手势约束的非对称性:进入全屏必须在直接的用户交互手势(如
click或touchend)上下文内部触发,否则浏览器会拒绝全屏请求;而退出全屏则不强制依赖即时手势。例如在视频播放完毕的ended事件回调中,或者定时器超时逻辑中,均可直接通过脚本调用exitFullscreen(),浏览器会予以执行。 -
iframe 内部向父级传递退出指令:当跨域 iframe 获得全屏授权并全屏后,其
getFullscreenElement()存在于子文档或父文档中。在复杂的多层微前端架构中,建议通过window.parent.postMessage()告知顶层宿主执行退出动作,保证各层级窗口视图同步复位。
图 4:退出全屏常见开发陷阱与健壮防御策略
五、总结
跨浏览器封装退出全屏函数的实质,是对历史前缀链与执行上下文的规范化收敛。在实际封装中,牢记以下三个核心准则:
- 必须绑定宿主执行:退出方法归属于
document,使用method.call(doc)确保this正确绑定; - 前置状态防御:调用前检测
getFullscreenElement(),非全屏状态下静默拦截,杜绝 Rejected Promise; - UI 状态只依赖事件监听:将界面按钮与样式的更新逻辑完全挂载在
fullscreenchange及其兼容事件上,从而自然覆盖代码调用与物理Esc键两种退出通道。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。