Fullscreen API 必须由用户手势触发，如 click 或 keydown 事件中调用 requestFullscreen()，否则抛出 NotAllowedError；需捕获错误、监听 fullscreenchange 事件，并为 iframe 显式添加 allowfullscreen 属性。
Fullscreen API 调用必须走用户手势触发
浏览器禁止脚本自动全屏，element.requestFullscreen() 必须在点击、键盘按键等用户交互回调中调用，否则会直接拒绝并抛出 TypeError: Document not allowed to request fullscreen。这不是兼容性问题，而是安全策略强制要求。
常见错误是把全屏逻辑写在页面加载后或定时器里，比如：setTimeout(() => el.requestFullscreen(), 100) —— 这种写法在所有现代浏览器里都会失败。
- 只允许在
click、keydown（且有按键值）、pointerdown等可信事件处理器内调用 - React/Vue 中绑定的
onClick或@click是安全的；但组件mounted钩子或useEffect里直接调用不行 - 若需“一键进入全屏”，按钮本身必须是用户真实点击的目标，不能靠
button.click()模拟
requestFullscreen() 的兼容写法和错误处理
requestFullscreen() 在不同浏览器前缀不同，但现代标准已统一为无前缀版本。不过仍建议加 catch 捕获拒绝原因，因为用户可能手动禁用了全屏权限，或当前元素不支持（如 iframe 缺少 allowfullscreen）。
button.addEventListener('click', () => {
const el = document.documentElement; // 或某个具体容器
el.requestFullscreen()
.catch(err => {
console.error('Fullscreen failed:', err.name); // 常见：NotAllowedError、SecurityError
});
});
-
err.name === 'NotAllowedError'：最常见，说明没在用户手势中调用，或页面被嵌入 iframe 且未声明权限 -
err.name === 'SecurityError'：通常因跨域 iframe 或非 HTTPS 页面尝试全屏 - Chrome/Firefox/Safari 均支持无前缀
requestFullscreen()，无需再写webkitRequestFullscreen等旧方法
退出全屏与监听状态变化
退出全屏不能靠关闭窗口或按 Esc 键来“监听”，而要主动调用 document.exitFullscreen()，并监听 fullscreenchange 事件来响应状态切换（比如更新按钮文案）。
立即学习“前端免费学习笔记（深入）”；
注意：document.fullscreenElement 是判断当前是否全屏的唯一可靠方式，document.webkitIsFullScreen 已废弃。
-
document.exitFullscreen()也受用户手势限制，但实际中只要在fullscreenchange的回调里调用一般没问题 -
fullscreenchange事件在文档上监听，不是在目标元素上：document.addEventListener('fullscreenchange', ...) - 退出时
document.fullscreenElement变为null，可据此切换 UI 状态
iframe 全屏需要显式声明 allowfullscreen
如果想让页面内嵌的 <iframe> 触发全屏（比如播放器），必须给 iframe 加 allowfullscreen 属性，否则调用 requestFullscreen() 会静默失败或抛 SecurityError。
仅加属性还不够：若 iframe 来源是跨域的，还需对方页面自己调用全屏（即控制权在子页面），父页面无法代为触发。
- 正确写法：
<iframe src="player.html" allowfullscreen></iframe> - 若 iframe 内容由你控制，确保其内部也使用标准
requestFullscreen()，而非依赖父页调用 - Safari 对
allowfullscreen要求更严格，缺少该属性时连全屏图标都不会显示
document.fullscreenElement。这些点漏掉任意一个，按钮就只是个摆设。 
