现代标准全屏方法是requestfullscreen()，需用户手势触发且元素已挂载dom；旧版浏览器需兼容webkit/moz/ms前缀；退出时应检查fullscreenelement并捕获异常。
全屏 API 已弃用 _REQUESTFULLSCREEN，正确方法是用 requestFullscreen()
根本不存在标准的 _REQUESTFULLSCREEN 接口——这是早期浏览器私有前缀（如 webkitRequestFullScreen、mozRequestFullScreen）被误传或混淆后的写法。现代标准只认 requestFullscreen()，且必须由用户手势（如 click）触发，否则直接静默失败。
常见错误现象：TypeError: element.requestFullscreen is not a function（未加前缀且目标元素不支持）、或调用无反应（缺少用户手势上下文、元素未挂载到 DOM、或被 iframe sandbox 阻止）。
- 只对嵌入文档中的元素调用，不能对
document以外的任意对象调用 - 必须确保元素已插入 DOM，例如在
mounted（Vue）或useEffect（React）中绑定事件，而非组件定义时 - iframe 需显式声明
allow="fullscreen"属性，否则调用直接被忽略
如何兼容老版本 Chrome/Firefox/Edge 的私有前缀
虽然现代浏览器已统一支持 requestFullscreen()，但若需支持 Chrome ≤59、Firefox ≤63、旧 Edge，需按顺序检测并调用对应方法。注意：不是“同时调用”，而是“找一个能用的就执行”。
实操建议：封装一个安全调用函数，避免重复判断：
function enterFullscreen(el) {
if (!el) return;
const fn = el.requestFullscreen ||
el.webkitRequestFullscreen ||
el.mozRequestFullScreen ||
el.msRequestFullscreen;
if (fn) fn.call(el);
}
- 不要用
if (el.webkitRequestFullscreen)单独判断后调用，因为部分旧版 Safari 返回undefined但实际可用，应优先用逻辑或链式取值 -
msRequestFullscreen在 IE11 中存在，但仅支持document对象，不支持任意元素（IE 全屏只能全窗口） - 调用后可监听
fullscreenchange事件做状态同步，而非依赖返回值（该方法始终返回Promise<void></void>或undefined）
点击按钮触发全屏时，为什么经常报错 “Document not active” 或静默失败
核心原因只有两个：元素不在活动文档中，或调用不在用户手势响应周期内。后者最常见——比如把 requestFullscreen() 包在 setTimeout、Promise.then 或异步接口回调里，哪怕延迟 0ms，也会丢失手势上下文。
- React 中避免：在
onClick回调里直接调用，不要解构为另一个函数再setTimeout调用 - Vue 中避免：用
@click="enterFullscreen($refs.target)"，而不是@click="() => setTimeout(() => enterFullscreen(...), 0)" - 如果必须异步（如加载资源后再全屏），需先在点击时保存元素引用，并用
document.addEventListener('click', ...)等待下一次用户交互，再触发全屏（不推荐，体验差） - 检查元素是否被
display: none或visibility: hidden，这些状态下调用会失败
退出全屏和监听状态变化的可靠写法
退出全屏不能只靠 document.exitFullscreen()，因为该方法在非全屏状态下调用会抛错；监听也别只绑 fullscreenchange，还要处理 fullscreenerror——比如用户按 Esc 后状态已变，但 JS 还没收到事件。
// 安全退出
if (document.fullscreenElement) {
document.exitFullscreen().catch(e => console.warn('Exit failed:', e));
}
// 监听（推荐在 document 上绑定，而非具体元素）
document.addEventListener('fullscreenchange', () => {
const isFull = !!document.fullscreenElement;
// 更新 UI 状态等
});
document.addEventListener('fullscreenerror', (e) => {
console.error('Fullscreen error on', e.target);
});
-
document.fullscreenElement是唯一可靠的当前全屏元素判断依据，document.isFullScreen已废弃且从未被 Chrome 支持 - 移动端 Safari 对全屏支持极弱（iOS 17 仍不支持
requestFullscreen()除<video></video>外的元素），这点容易被忽略 - 调用
exitFullscreen()后，fullscreenElement会立刻变为null，但动画过渡可能还在进行，状态更新应以事件为准
