Esc键失效主因是页面拦截事件或全屏状态错乱，需确保requestFullscreen()由用户手势触发、避免preventDefault()、正确监听fullscreenchange并检查document.fullscreenElement。
HTML5全屏退出快捷键（Esc）失效的常见原因
Esc 键失效，往往不是浏览器 bug，而是页面主动调用了 event.preventDefault() 或在 fullscreenchange 之前就阻塞了原生全屏逻辑。比如在 click 或 keydown 中拦截了 Esc，或者用 requestFullscreen() 后没等状态真正切换就执行了其他 DOM 操作，导致浏览器内部状态错乱。
- 监听了
document.addEventListener('keydown', ...)且对event.key === 'Escape'调用了preventDefault() -
requestFullscreen()被包裹在异步回调（如setTimeout、Promise.then）里，破坏了用户手势触发约束 - 全屏目标元素被移除、隐藏或替换过，但未同步调用
document.exitFullscreen() - 多个
requestFullscreen()连续调用，部分失败后浏览器进入不可预测状态
正确监听 fullscreenchange 的时机和写法
这个事件只在全屏状态**真正切换完成**后触发，不是“开始切换”时。它不冒泡，必须绑定在 document 上；且触发时 document.fullscreenElement 才是最新值——不能依赖事件前的判断。
- 始终用
document.addEventListener('fullscreenchange', handler)，别用onfullscreenchange属性 - 在 handler 内立刻读取
document.fullscreenElement，而不是缓存上一次的值 - 如果需要兼容旧版，同时监听
webkitfullscreenchange、mozfullscreenchange、msfullscreenchange，但注意它们触发顺序不一致，优先以标准事件为准 - 避免在 handler 里再调用
requestFullscreen()或exitFullscreen()，可能引发循环或拒绝（DOMException: Document not active）
exitFullscreen() 被拒绝的典型场景与绕过方式
document.exitFullscreen() 会抛出 Promise reject，常见错误信息是 "Document not active" 或 "Invalid state"，本质是浏览器认为当前没有合法的全屏上下文——比如页面已失焦、iframe 被沙箱限制、或全屏是由非用户手势（如定时器）触发的。
- 确保调用
exitFullscreen()前，document.fullscreenElement不为null，否则直接跳过 - 不要在
blur、visibilitychange等非用户交互事件中主动调用exitFullscreen() - 若需从 iframe 退出，父页面需设置
allow="fullscreen"，且子页面调用的是document.exitFullscreen()，不是window.parent.document.exitFullscreen() - 某些安卓 WebView 对
exitFullscreen()支持不稳定，可降级为监听fullscreenchange+ 检查document.fullscreenElement === null来确认是否已退出
调试时容易忽略的细节
很多问题卡在「以为自己在全屏，其实没成功」。Chrome DevTools 的 Application → Rendering 面板里勾选 “Show fullscreen overlay” 可视化当前全屏状态；但更关键的是每次 requestFullscreen() 都要处理 Promise：
立即学习“前端免费学习笔记（深入）”；
elem.requestFullscreen().catch(err => {
console.warn('Fullscreen request failed:', err.name, err.message);
});
-
err.name是判断依据：NotAllowedError表示缺少用户手势，SecurityError表示跨域或沙箱限制，TypeError表示目标元素无效 - 移动端 Safari 不支持
video元素以外的任意元素全屏，强行调用不会报错但静默失败 -
document.fullscreenEnabled为false时，整个 API 不可用（如禁用全屏策略的浏览器配置），此时连事件监听都无意义
全屏逻辑的脆弱性不在代码多难写，而在于它极度依赖浏览器当前焦点、权限状态和调用链路的原子性。任何中间环节的异步拆分、DOM 变更或权限缺失，都会让 Esc 键或 exitFullscreen() 失效——这不是能靠重试解决的问题，得从触发源头开始收束。
