iframe无法全屏90%因权限声明错误:必须双写allowfullscreen和allow="fullscreen",后者值须为精确字符串"fullscreen";跨域时父页permissions-policy响应头会覆盖html属性;全屏须由iframe内用户手势触发,且目标为子页真实dom元素。

iframe 无法全屏,90% 是因为权限没声明对,不是 JS 写错了,而是浏览器压根不给执行机会。
allowfullscreen 和 allow="fullscreen" 必须双写
现代浏览器(Chrome 120+、Firefox 100+)已将权限控制收敛到 allow="fullscreen",allowfullscreen 只是兼容补丁,不能替代它。
-
allowfullscreen是布尔属性,不带值;写成allowfullscreen="true"或allowfullscreen="allowfullscreen"都无效 -
allow="fullscreen"的值必须是字符串"fullscreen",拼错成"full-screen"、"allow-fullscreen"或大小写错误(如"Fullscreen")都会失效 - 跨域 iframe 必须双写:
<iframe src="https://thirdparty.com/app.html" allowfullscreen allow="fullscreen"></iframe> - 同源 iframe 可只写
allowfullscreen,但建议统一双写,避免测试环境和生产环境行为不一致
requestFullscreen() 在 iframe 内静默失败的三大硬性条件
不是报错,是根本没触发——控制台安静、Promise 不 resolve、也不 reject。常见现象就是点按钮毫无反应。
- 用户手势必须发生在 iframe 内部:父页按钮点击后,不能直接调用
iframe.contentDocument.getElementById('player').requestFullscreen();必须用postMessage让子页自己调用 - iframe 必须已加载完成且 JS 可执行:若带
sandbox属性,需显式加allow-scripts,否则子页 JS 根本不运行 - 目标元素必须是子页内真实挂载的 DOM 节点,且不能是
<iframe></iframe>自身——iframeElm.requestFullscreen()永远无效
父页的 Permissions-Policy 响应头会直接覆盖 HTML 属性
如果父页面 HTTP 响应头包含 Permissions-Policy: fullscreen 'none',那么无论你怎么写 allowfullscreen 或 allow="fullscreen",浏览器都会无视。
- 这种响应头常见于 CMS、SaaS 平台或企业内网网关,开发者往往无权修改
- 此时删掉响应头比改 HTML 更有效;若不可行,只能联系平台方开放策略
- 可通过浏览器 DevTools 的 Network → Response Headers 面板确认是否被拦截
document.fullscreenElement 在父页永远是 null
这不是 bug,是规范行为。iframe 全屏后,全屏状态属于子文档(iframe.contentDocument),父文档的 document.fullscreenElement 始终为 null,哪怕整个视口都被占满了。
- 别写
parent.document.fullscreenElement === iframeElm来判断——这永远不成立 - 正确做法是子页进入全屏后主动通知:
window.parent.postMessage({ type: 'FULLSCREEN_ENTERED' }, '*') - 父页监听
window.addEventListener('message', ...),再做 UI 同步(比如隐藏 body 滚动条)
最容易被忽略的是:iOS Safari 对非 <video></video> 元素的全屏限制极严,连 <canvas></canvas> 都不支持原生全屏,此时必须退守 CSS “伪全屏”方案,而不是反复调试 API 调用时机。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











