监听用户退出全屏需绑定 document 的 fullscreenchange 事件,通过 document.fullscreenElement 是否为 null 判断;iOS Safari 需加 setTimeout 或 Promise.then 延迟读取,并兼容监听 webkitfullscreenchange。

监听用户退出全屏动作,核心是捕获 document 上的 fullscreenchange 事件,并通过 document.fullscreenElement 的值变化来判断是否已退出。
必须监听 document,不是 video 或 window
很多人误以为给 <video> 元素绑定 fullscreenchange 就能监听退出,但该事件只在 document 上触发,且不冒泡。绑定到元素或 window 都无效。
- ✅ 正确写法:
document.addEventListener('fullscreenchange', handler) - ❌ 错误写法:
videoEl.addEventListener('fullscreenchange', ...)或window.addEventListener('fullscreenchange', ...) - 注意拼写:是
fullscreenchange(全小写),不是fullScreenChange或fullscreenchanged
用 fullscreenElement 判断是否真正退出
事件本身不带“进入”或“退出”标识,只能靠读取状态属性:
- 若
document.fullscreenElement === null→ 已退出全屏(无论因 ESC、点击退出按钮,还是 F11 关闭 API 全屏) - 若
document.fullscreenElement是某个 DOM 元素(如你的video)→ 当前处于全屏中 - 如需确认退出的是你的视频,可加判断:
document.fullscreenElement !== videoEl
iOS Safari 特别注意:异步延迟读取
部分 iOS Safari 版本中,fullscreenchange 回调刚执行时,document.fullscreenElement 可能还没更新为 null,导致误判。
立即学习“前端免费学习笔记(深入)”;
- 稳妥做法:在事件回调里用
setTimeout(() => { /* 读取 fullscreenElement */ }, 0) - 或者用
Promise.resolve().then(() => { ... })确保读取时机 - 避免在回调中立即调用
exitFullscreen()或再次requestFullscreen(),易报错或循环
补充兼容旧版 Safari(iOS 15.4 及更早)
虽然现代标准是监听 fullscreenchange,但为覆盖旧版 iOS Safari,建议同时监听 webkitfullscreenchange:
document.addEventListener('webkitfullscreenchange', handler)- 两个事件回调逻辑一致:都检查
document.fullscreenElement(或降级用document.webkitFullscreenElement) - 不需要单独处理
webkitExitFullscreen,退出动作仍由浏览器统一管控



















