document.exitFullscreen() 调用失败的常见原因：未处理浏览器前缀、未处于全屏状态（document.fullscreenElement为null）、在异步回调（如setTimeout、fetch.then）中调用违反用户手势策略，或页面失焦导致文档非活跃。
document.exitFullscreen() 调用失败的常见原因
直接调用 document.exitFullscreen() 报错 “TypeError: document.exitFullscreen is not a function” 或静默失败，大概率是因为浏览器前缀未处理，或当前根本没处于全屏状态。这个 API 在 Chrome、Firefox、Safari 中都存在兼容性差异，且必须由用户手势（如 click）触发，不能在异步回调（比如 setTimeout、fetch.then）里调用。
- Chrome / Edge 84+ 和 Firefox 69+ 支持标准
document.exitFullscreen() - Safari 15.4+ 才支持无前缀版本；更早版本需用
document.webkitExitFullscreen() - 调用前必须确认
document.fullscreenElement不为null，否则会失败且不抛异常
安全退出全屏的推荐写法
不要裸调 document.exitFullscreen()，应先检测状态、再兜底兼容、最后统一处理 Promise 结果。现代写法应兼顾错误捕获和降级逻辑：
function safeExitFullscreen() {
if (!document.fullscreenElement) return Promise.resolve();
const exit = document.exitFullscreen ||
document.webkitExitFullscreen ||
document.msExitFullscreen;
if (exit) {
return exit.call(document).catch(() => {});
}
return Promise.resolve();
}
// 使用示例（绑定在按钮上）
button.addEventListener('click', () => {
safeExitFullscreen().then(() => {
console.log('已退出全屏');
});
});
为什么不能在 setTimeout 或 fetch 回调里调用？
浏览器强制要求全屏切换（包括退出）必须由“可信的用户激活事件”发起，比如 click、keydown（非自动触发），否则会拒绝执行并抛出 NotAllowedError。这跟 requestFullscreen() 是同一套策略。
-
setTimeout(() => document.exitFullscreen(), 100)→ 必然失败 -
fetch('/api').then(() => document.exitFullscreen())→ 必然失败 - 正确做法：把退出逻辑放在用户点击后立即执行，中间不要穿插异步等待
监听全屏状态变化比手动管理更可靠
靠变量标记“是否全屏”容易不同步，尤其在多标签页、页面卸载、系统级全屏切换（如 macOS 的 Mission Control）时失效。应该监听原生事件：
document.addEventListener('fullscreenchange', () => {
if (!document.fullscreenElement) {
console.log('已退出全屏');
// 这里适合重置 UI、恢复滚动、清理临时样式
}
});
// 注意：该事件在 Safari 中可能触发两次（进入/退出各一次），但 exitFullscreen() 成功后一定会触发一次 fullscreenchange
真正难处理的不是调用本身，而是状态同步——退出动作可能成功，但事件没来；也可能事件来了，但 UI 还没反应过来。建议把关键副作用（比如恢复 body overflow）放在 fullscreenchange 里做，而不是只依赖 exitFullscreen().then()。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
