requestfullscreen() 失败主因是未在用户手势同步上下文中调用，需绑定原生 click/touchend 事件直接调用；目标元素须已挂载且可见；应监听 document 的 fullscreenchange 和 fullscreenerror 事件，并用 try...catch 包裹 document.exitfullscreen()。
requestFullscreen() 调用失败的常见原因
点了按钮没反应，90% 是因为 requestFullscreen() 没在用户手势同步上下文中执行。它不能出现在 setTimeout、Promise.then、DOMContentLoaded 或视频 play() 回调里——浏览器会静默拒绝，控制台可能只报 NotAllowedError，甚至完全无提示。
实操建议：
- 按钮必须绑定原生
click（或touchend）事件，且回调函数内直接调用目标元素的requestFullscreen() - 目标元素需已挂载到 DOM 且可见（
display: none或visibility: hidden都会失败） - 避免对
document.body或document.documentElement直接调用——Safari 会拒绝，应优先选一个语义清晰的容器，如<main id="app"></main> - 调用前可加兼容性判断：
if (container.requestFullscreen)，防止旧 Safari 报错
如何正确监听和响应全屏状态变化
fullscreenchange 事件只在 document 上有效，且不携带目标元素信息。你无法从事件对象里拿到“谁进全屏了”，只能靠 document.fullscreenElement 实时读取。
实操建议：
- 用
document.addEventListener('fullscreenchange', handler)监听，不要绑在按钮或容器上 -
document.fullscreenElement === container才表示该容器处于全屏；退出后值为null（不是undefined） - Safari 触发
fullscreenchange稍滞后，若需立即更新按钮文案，可用Promise.resolve().then(() => {...})延迟读取 - 建议同时监听
fullscreenerror：用户拒权、元素被移出 DOM、跨域 iframe 尝试全屏都会触发，但默认不报错，容易漏处理
安全退出全屏的写法
document.exitFullscreen() 是全局操作，不是某个元素的方法。误写成 container.exitFullscreen() 会报 TypeError，因为该方法根本不存在。
实操建议：
- 退出前先判空：
if (document.fullscreenElement)，再调用document.exitFullscreen() - 必须用
try...catch包裹：旧版 Firefox 在非全屏时调用会抛NotFoundError，不捕获会导致后续 JS 中断 - 不要依赖 ESC 键自动清理逻辑——后台项目常需同步关闭弹窗、暂停定时器、释放 canvas 动画资源，这些都得在
fullscreenchange里手动做 - iOS Safari 对全屏限制极严：仅支持
<video></video>元素，其他元素即使调用成功，也无法真正覆盖系统 UI
移动端与 iframe 的特殊处理
移动端（尤其 iOS）和嵌入式 iframe 是全屏功能最易翻车的场景。它们不是“不支持”，而是有明确白名单和属性要求。
实操建议：
- iOS 15+ 才允许部分元素全屏，且仍不支持
<div> 类容器覆盖状态栏；若必须适配，优先考虑用 <code><video></video>+webkit-playsinline+controls - iframe 默认禁止全屏，必须显式添加
allow="fullscreen"属性，例如：<iframe src="..." allow="fullscreen"></iframe> - 不要在 Vue/React 组件挂载完成（
mounted/useEffect）里自动触发全屏——这违反用户手势原则，必然失败 - 若页面含多个可全屏区域（如图表容器、模态框），每次只允许一个元素全屏；切换前需先退出当前全屏，否则新调用会被忽略 全屏 API 表面简单，实际牵扯状态管理、事件时机、跨端差异和错误兜底。最容易被忽略的是
fullscreenerror 监听和 try...catch 包裹 exitFullscreen() ——它们不报错时一切正常，一出问题就静默失败，排查成本极高。
