全屏功能失效主因是权限链断裂，需检查跨域iframe的allow="fullscreen"、父页Permissions-Policy响应头、sandbox属性配置，并确保requestFullscreen()由子页用户手势直接触发，且正确使用postMessage通信。
allowfullscreen写了但全屏按钮灰了，先查这三处
不是属性没加，而是权限链在某个环节断掉了。最常见的是：跨域 iframe 漏了 allow="fullscreen"，父页响应头写了 Permissions-Policy: fullscreen 'none'，或者 iframe 带 sandbox 但没配 allow-scripts。
-
allowfullscreen是布尔属性，写成allowfullscreen="true"没问题，但allowfullscreen="false"或不写就等于禁止 - Chrome 120+、Firefox 100+、Safari 13.1+ 已将权限控制收敛到
allow="fullscreen"，只写allowfullscreen在跨域场景下会被静默忽略 - 用 DevTools 右键点击 iframe → “Inspect iframe” → 切到右侧 “Permissions” 标签页，确认
fullscreen显示为 Allowed；若显示 Denied，说明 HTML 属性被响应头覆盖或 sandbox 阻断
requestFullscreen() 调用后静默失败，检查用户手势上下文
浏览器不报错、Promise 不 resolve、document.fullscreenElement 始终为 null——这是典型的手势上下文丢失。全屏 API 必须由 iframe 内部的用户操作直接触发，不能由父页代理。
- 父页按钮点击后调用
iframe.contentWindow.document.documentElement.requestFullscreen()？必然失败，跨 browsing context 的手势不可传递 - 正确做法：子页内放一个
<button onclick="document.getElementById('player').requestFullscreen()">，且该按钮必须真实渲染、可见、可点击（offsetParent !== null） - 不能在
iframe.onload、setTimeout、fetch().then中调用——这些都不是用户手势，浏览器直接拦截
iframe 全屏后父页状态失联，别依赖 document.fullscreenElement
父页面的 document.fullscreenElement 永远不会指向 iframe 元素，这不是 bug，是规范行为。iframe 全屏属于子文档的独立状态，父页无法直接感知。
- 错误写法：
if (document.fullscreenElement === iframeElm) { /* 退出逻辑 */ }—— 这个判断永远为false - 正确通信方式：子页进入全屏后执行
window.parent.postMessage({ type: 'FULLSCREEN_ENTERED' }, '*')，父页监听window.addEventListener('message', handler) - 移动端（尤其是 iOS Safari）对非
<video>元素全屏支持极弱，即使所有配置都对，<div id="app">在 iOS 上 requestFullscreen() 也大概率静默失败
控制台报 SecurityError: Document not allowed to call requestFullscreen()
这是最明确的信号：权限校验在 JS 执行前就被浏览器拒绝了。它比静默失败更“诚实”，但容易被当成代码错误忽略。
立即学习“前端免费学习笔记（深入）”；
- 出现该错误，99% 是因为 iframe 缺少
allow="fullscreen"，或父页响应头含Permissions-Policy: fullscreen 'none' - 检查 iframe 的
src协议：HTTP 页面嵌 HTTPS iframe 通常可工作，但 HTTPS 页面嵌 HTTP iframe 在现代浏览器中会因混合内容被阻断全屏 - 如果 iframe 是 sandboxed，必须显式加
sandbox="allow-scripts allow-fullscreen"（注意：旧版写法allowfullscreen在 sandbox 中无效）
真正卡住人的从来不是“怎么写”，而是“为什么写了还不行”。权限声明、手势上下文、跨文档状态同步、平台限制——四层叠加，漏掉任意一层都会让全屏功能彻底失效。尤其要注意 iOS 和 sandbox iframe 这两个高频陷阱，它们不会报错，只会安静地拒绝。
