HTML如何全屏显示_html全屏API fullscreen使用方法【深度解析】

requestFullscreen() 必须在用户手势（如点击）中调用，否则静默失败或抛 NotAllowedError；常见原因包括非手势上下文、元素未挂载DOM、不可见、跨iframe未授权；需按标准→webkit→moz→ms顺序兼容调用；状态判断唯一可靠方式是document.fullscreenElement并监听document的fullscreenchange事件；iOS Safari仅支持video或带allow="fullscreen"的iframe。

requestFullscreen() 不是“调用就全屏”，而是必须在用户点击、按键等手势上下文中执行，否则直接静默失败或抛 NotAllowedError —— 这是绝大多数人卡住的第一关。

为什么 requestFullscreen() 总是报 Failed to execute 'requestFullscreen' on 'Element'

这个错误几乎全是权限/上下文问题，不是语法错：

• 没在用户手势中调用：比如放在 setTimeout、Promise.then、DOMContentLoaded 或 load 事件里，都会断开手势链
• 目标元素还没插入 DOM：例如刚 new Element() 就调用，但还没 appendChild
• 元素不可见：设置了 display: none、visibility: hidden，或父容器 overflow: hidden 裁剪了它
• 跨 iframe 调用且子帧没加 allow="fullscreen" 属性（如 <iframe src="..." allow="fullscreen">）

怎么正确调用 requestFullscreen() 并兼容老浏览器

现代浏览器统一支持 element.requestFullscreen()（返回 Promise），但旧版 Chrome/Safari/Firefox/IE 仍需前缀。别写死一个方法，要按优先级检测：

• 先查 element.requestFullscreen（标准）
• 再查 element.webkitRequestFullscreen（Safari、旧 Chrome）
• 再查 element.mozRequestFullScreen（Firefox）
• 最后查 element.msRequestFullscreen（IE11 / 旧 Edge）

示例片段：

立即学习“前端免费学习笔记（深入）”；

function enterFullscreen(el) {  if (el.requestFullscreen) {    el.requestFullscreen().catch(err => console.error('全屏被拒:', err.message));  } else if (el.webkitRequestFullscreen) {    el.webkitRequestFullscreen();  } else if (el.mozRequestFullScreen) {    el.mozRequestFullScreen();  } else if (el.msRequestFullscreen) {    el.msRequestFullscreen();  }}

注意：document.exitFullscreen() 同样要兼容前缀，且退出也必须由用户手势触发（比如按钮点击），不能靠定时器自动退出。

document.fullscreenElement 和 fullscreenchange 事件怎么用才不翻车

判断是否真进全屏，唯一可靠方式是读 document.fullscreenElement（注意拼写是 fullscreen，不是 fullScreen 或 FullScreen）；监听状态变化必须绑定到 document 上，不是某个元素：

• document.addEventListener('fullscreenchange', () => { ... }) 是唯一有效监听点
• 用户按 Esc 退出时，该事件会触发，但你的 JS 逻辑不会自动执行退出动作 —— UI 状态和实际状态容易脱节
• 务必在事件回调里检查 document.fullscreenElement，而不是靠变量缓存，因为用户可能绕过按钮直接按 Esc

常见坑：把监听绑在按钮上、用 isFullscreen 布尔变量手动维护状态、忘记处理 null 值导致后续逻辑崩溃。

iOS Safari 和移动端的特殊限制

iOS Safari 对全屏极其保守：

• 只允许 <video> 元素或带 allow="fullscreen" 的 <iframe> 进入全屏
• 不接受 div、canvas 或 document.documentElement 的全屏请求
• 对用户手势要求更严：touchend 有时不被认可，优先用 click
• 即使成功进入，全屏后键盘可能无法弹出（尤其表单场景），且 :fullscreen CSS 伪类支持不稳定

这意味着：如果你的目标是视频播放器，video.requestFullscreen() 是可行路径；如果是通用内容容器，在 iOS 上基本无解，得降级为 CSS “伪全屏”（position: fixed + 100vw/vh）并手动管理显隐逻辑。