怎么用JS监听浏览器全屏状态变化
详细讲解如何使用 JavaScript 监听浏览器全屏状态变化,涵盖 fullscreenchange 标准事件、document.fullscreenElement 状态判断、用户主动退出识别、多浏览器兼容封装及避坑要点。
在前端开发中,监听全屏状态变化的标准做法是向 document 绑定 fullscreenchange 事件,并在事件回调中通过读取 document.fullscreenElement 是否为 null 来判断当前是处于全屏模式还是已退出全屏。
一、全屏事件监听的核心机制
浏览器的 Fullscreen API 将全屏状态抽象为一个全局属性与一组事件。当页面元素进入或脱离全屏时,浏览器会在宿主文档(document)以及触发全屏的具体元素上派发一个名为 fullscreenchange 的事件。
需要注意,fullscreenchange 事件本身在触发时不携带“进入”还是“退出”的布尔值参数。判断当前状态必须通过检查 document.fullscreenElement 属性:
- 全屏状态:
document.fullscreenElement指向当前处于全屏视图的那个 DOM 元素节点(例如某个<video>或<div>容器)。 - 普通状态:当页面没有元素处于全屏展示模式时,
document.fullscreenElement的值为null。
二、标准监听实现与代码步骤
编写监听代码时,通常遵循四个标准步骤:声明回调函数、获取全屏元素状态、更新业务界面、挂载事件监听器。
下面是完整的可运行代码示例。代码包含进入全屏、退出全屏以及状态变化的监听与界面反馈:
// 1. 获取 DOM 元素
const videoBox = document.getElementById('my-video-container');
const toggleBtn = document.getElementById('toggle-fullscreen-btn');
// 2. 状态变化处理函数
function handleFullscreenChange() {
const currentElement = document.fullscreenElement;
if (currentElement) {
// 已经进入全屏状态
console.log('当前已进入全屏,全屏节点为:', currentElement);
toggleBtn.textContent = '退出全屏';
videoBox.classList.add('is-fullscreen');
} else {
// 已经退出全屏状态
console.log('当前已退出全屏');
toggleBtn.textContent = '进入全屏';
videoBox.classList.remove('is-fullscreen');
}
}
// 3. 监听标准全屏变化事件
document.addEventListener('fullscreenchange', handleFullscreenChange);
// 4. 监听可能发生的全屏被拒绝或异常事件
document.addEventListener('fullscreenerror', (event) => {
console.error('全屏模式请求失败或被浏览器拒绝:', event);
});
// 5. 触发按钮逻辑:根据当前状态切换
toggleBtn.addEventListener('click', () => {
if (!document.fullscreenElement) {
// 请求让容器元素进入全屏
videoBox.requestFullscreen().catch((err) => {
console.error(`请求全屏出错: ${err.message}`);
});
} else {
// 退出全屏必须在 document 上调用
document.exitFullscreen().catch((err) => {
console.error(`退出全屏出错: ${err.message}`);
});
}
});
三、容易忽视的机制差异:Fullscreen API 与 窗口全屏 (F11)
许多开发者在测试全屏监听时,会按下键盘上的 F11 键(或在 macOS 上点击窗口绿色的全屏按钮),却发现 fullscreenchange 监听函数完全没有被调用。
这是因为浏览器严格区分了“DOM 元素全屏 (Fullscreen API)”与“浏览器窗口全屏 (Window Fullscreen)”:
- Fullscreen API:由 JavaScript 主动调用某个 DOM 节点的
requestFullscreen()触发。该模式下该 DOM 节点被放置在最顶层渲染图层,覆盖整个操作系统屏幕。这会精准触发fullscreenchange事件。 - F11 窗口全屏:属于浏览器软件外壳自身的视口最大化,没有指定任何具体的网页 DOM 元素作为全屏载体。
document.fullscreenElement仍然为null,因此不会触发fullscreenchange事件。
如果业务场景需要连带感知用户按 F11 导致的窗口变大,可额外监听 window 的 resize 事件,并对比 window.innerHeight === screen.height,或者通过 CSS 媒体查询 window.matchMedia('(display-mode: fullscreen)') 进行辅助捕获。
四、历史浏览器前缀与兼容封装
现代主流浏览器(Chrome 71+、Edge 79+、Firefox 64+、Safari 16.4+)均已完全支持标准无前缀的 API。但若需兼容较旧的 Safari(WebKit 内核)、早期 Firefox 或嵌入式 WebView 环境,需要对带有厂商前缀的属性与事件名称进行简单适配。
主要前缀对照关系如下:
- 标准规范:事件为
fullscreenchange,属性为document.fullscreenElement。 - WebKit 前缀(旧版 Safari / 微信内旧内核):事件为
webkitfullscreenchange,属性为document.webkitFullscreenElement。 - Firefox 早期前缀:事件为
mozfullscreenchange,属性为document.mozFullScreenElement。 - IE / 早期 Edge 前缀:事件为
MSFullscreenChange,属性为document.msFullscreenElement。
生产环境中可编写一个统一的兼容包装工具:
/**
* 跨浏览器安全获取当前处于全屏的元素
* @returns {Element|null}
*/
function getFullscreenElement() {
return (
document.fullscreenElement ||
document.webkitFullscreenElement ||
document.mozFullScreenElement ||
document.msFullscreenElement ||
null
);
}
/**
* 跨浏览器绑定全屏状态变化监听
* @param {Function} callback 状态变更后的回调,入参为 (isFullscreen, currentElement)
* @returns {Function} 用于销毁监听的清理函数
*/
function listenFullscreenChange(callback) {
const eventNames = [
'fullscreenchange',
'webkitfullscreenchange',
'mozfullscreenchange',
'MSFullscreenChange'
];
const handler = () => {
const currentElem = getFullscreenElement();
const isFullscreen = currentElem !== null;
callback(isFullscreen, currentElem);
};
// 批量注册所有可能的前缀事件
eventNames.forEach((name) => {
document.addEventListener(name, handler);
});
// 返回卸载函数,便于在 React / Vue 组件卸载时调用
return function unbind() {
eventNames.forEach((name) => {
document.removeEventListener(name, handler);
});
};
}
五、开发中的关键注意事项
1. 为什么不能在“全屏按钮”的点击事件中同步 UI?
很多新手喜欢在点击“进入全屏”按钮后立即将按钮文本改为“退出全屏”。这种写法存在严重漏洞:用户在全屏下按下键盘上的 ESC 键退出全屏时,并不会点击你的自定义按钮。此时,页面按钮仍旧停留在“退出全屏”,UI 与实际状态产生脱节。
因此,所有与全屏相关的 UI 渲染、图标翻转、样式切换,必须统一放在 fullscreenchange 的监听回调中处理。
2. 用户手势限制(User Gesture Requirement)
浏览器对全屏有严格的安全限制。不能在页面刚加载(DOMContentLoaded 或 window.onload)或异步定时器中无条件调用 requestFullscreen()。全屏请求必须由用户的主动点击、轻触或按键事件直接触发,否则控制台会报错并触发 fullscreenerror 事件。
3. iframe 内嵌页面的全屏权限
如果页面运行在 <iframe> 内,必须在父页面的 iframe 标签上显式声明 allow="fullscreen"(或历史属性 allowfullscreen)。若缺失该属性,内嵌页的 requestFullscreen() 会直接失败,不会进入全屏。
六、总结
监听浏览器全屏状态变化的核心逻辑可归结为三句话:
- 使用
document.addEventListener('fullscreenchange', callback)捕获进入与退出的状态变动。 - 在回调中通过
document.fullscreenElement是否为null(或判定是否为预期元素)来确认当前全屏状态。 - 所有控制界面的切换逻辑(如按钮文字、图表重绘、浮窗显示)都集中在事件回调中处理,以此天然兼顾用户按
ESC键退出的场景。
Swiper.js配置指南:实现移动端触摸翻页效果
2026-11-18 14:52:42
JavaScript获取input值后怎么去除首尾空格
2026-11-18 11:42:04
HTML行内事件属性中JavaScript的this指向规则
2026-11-18 08:00:40
现代JS开发中替代alert弹出提示框的最佳实践
2026-11-17 19:11:31
JS怎么使用createElement和appendChild动态添加HTML标签
2026-11-17 18:33:06








