如何使用Fullscreen API在HTML中全屏显示元素

全屏必须由用户手势触发，调用 requestFullscreen() 前需绑定 click 等事件；检测用 document.fullscreenElement，退出用 document.exitFullscreen()，样式适配用 :fullscreen 伪类。

如何调用 requestFullscreen() 进入全屏

元素全屏必须由用户手势（如 click、keydown）触发，直接在脚本中调用会失败并抛出 TypeError: Document not active 或静默拒绝。现代浏览器要求全屏请求必须是“用户发起的”。

正确做法是绑定点击事件，在回调中调用目标元素的 requestFullscreen() 方法：

document.getElementById('myVideo').addEventListener('click', () => {  document.getElementById('myVideo').requestFullscreen();});

• 只支持 HTMLElement 实例，document 或 document.body 也能调用，但效果等价于让整个页面全屏
• 部分旧版浏览器需加前缀：webkitRequestFullscreen、mozRequestFullScreen、msRequestFullscreen
• 调用后若成功，会触发 fullscreenchange 事件；失败则触发 fullscreenerror

如何检测当前是否处于全屏状态

不能靠变量手动维护状态，应以 document.fullscreenElement 为准——它返回当前全屏的元素（null 表示未全屏）。

注意拼写：Chrome/Firefox 是 fullscreenElement，旧版 Safari 是 webkitFullscreenElement，IE 是 msFullscreenElement。

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

• document.fullscreenElement === myDiv 表示 myDiv 正在全屏
• document.fullscreenElement === null 表示无元素全屏（包括刚退出或从未进入）
• 不要用 document.isFullscreen —— 该属性不存在，是常见误查

如何退出全屏及监听状态变化

退出全屏统一调用 document.exitFullscreen()，而非元素上的方法。它返回 Promise，可链式处理失败情况：

document.exitFullscreen().catch(e => {  console.warn('退出全屏失败:', e.name); // e.name 可能是 'NotAllowedError' 或 'NotFoundError'});

• 退出失败常见原因是：没有全屏元素（document.fullscreenElement 为 null），或被其他异步逻辑中断
• 全局监听状态变化用 document.addEventListener('fullscreenchange', handler)，不是 onfullscreenchange 属性
• 注意：该事件在进入和退出时都触发，需在 handler 中检查 document.fullscreenElement 判断方向

CSS 中如何适配全屏样式

全屏状态下，浏览器会自动给全屏元素及其祖先添加伪类 :fullscreen（标准）或带前缀的 ::-webkit-full-screen 等。这是唯一可靠的样式钩子。

不要试图用 JavaScript 动态加 class 模拟全屏样式，因为全屏切换可能发生在 JS 之外（如用户按 F11）。

• 推荐写法：div:fullscreen { width: 100vw; height: 100vh; }
• :fullscreen 的权重高于普通 class，但低于内联 style；如有冲突，优先用 !important 显式覆盖
• 注意：:fullscreen 匹配的是当前 document.fullscreenElement，不是它的子元素

全屏 API 行为高度依赖用户交互上下文和浏览器策略，最易忽略的是：即使代码逻辑完全正确，如果调用不在用户手势回调内、或目标元素不可见/被 display: none、或包含 iframe 且未设 allow="fullscreen"，都会静默失败。调试时务必检查控制台错误，并始终用 document.fullscreenElement 做最终判断。