HTML Fullscreen API：元素全屏显示方法

在前端开发中，实现全屏功能看似简单，但实际操作时却容易遇到各种问题。许多开发者都遇到过这样的困惑：代码逻辑明明正确，为什么全屏就是无法触发？或者样式突然混乱？本文将详细梳理 Fullscreen API 中容易被忽略的关键细节，帮助开发者一次性理清所有要点。

调用 requestFullscreen() 进入全屏的正确方式

第一条也是最关键的规则：全屏请求必须由用户主动触发。浏览器出于安全考虑，禁止脚本暗中将页面切换为全屏。如果在页面加载或异步函数中直接调用，通常会出现 TypeError: Document not active 错误，或者浏览器静默拒绝请求。

因此，正确的做法始终是绑定用户事件，例如点击：

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

此外，还需注意以下几点：

• 该方法调用在 HTMLElement 实例上。也可以对 document 或 document.body 调用，使整个页面进入全屏。
• 处理浏览器兼容性时，需添加前缀：webkitRequestFullscreen（Chrome、Safari）、mozRequestFullScreen（Firefox）、msRequestFullscreen（旧版 IE/Edge）。
• 调用成功后触发 fullscreenchange 事件，失败时触发 fullscreenerror 事件，这是调试的重要依据。

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

不要自行维护 isFullscreen 类变量，这种方式容易导致状态不同步。浏览器提供了官方属性 document.fullscreenElement 来查询状态。

该属性非常直观：若存在全屏元素，则返回该元素；若为 null，则表示没有元素处于全屏状态（可能是退出后或从未进入）。

不同浏览器的属性名略有差异：标准写法为 fullscreenElement，旧版 Safari 使用 webkitFullscreenElement，IE 使用 msFullscreenElement。需要特别注意：不存在 document.isFullscreen 属性，直接使用该属性会始终返回 undefined。

• document.fullscreenElement === myDiv：用于精确判断特定元素是否在全屏。
• document.fullscreenElement === null：这是判断“是否已退出全屏”的可靠依据。

退出全屏及监听状态变化的方法

退出全屏的操作应在 document 对象上调用 exitFullscreen()，而非之前全屏的元素。该方法返回 Promise，便于处理异常情况。

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

退出失败通常有两种原因：当前没有元素在全屏（document.fullscreenElement 已为 null），或受到浏览器的其他策略（如同步逻辑冲突）中断。

要监听全屏状态变化，需为 document 添加 fullscreenchange 事件监听器。需要注意：进入和退出全屏都触发该事件。在事件处理函数中，必须检查 document.fullscreenElement 才能确定当前是进入（属性有值）还是退出（属性为 null）。

CSS 中如何适配全屏样式

元素进入全屏后，浏览器会自动为其及其祖先元素应用伪类 :fullscreen。这是定制全屏样式的唯一可靠入口。

不要尝试通过 JavaScript 动态添加或移除 CSS 类来模拟该效果，因为用户可能通过按 F11 等键触发全屏，这完全绕过了 JavaScript 逻辑。

• 标准写法：div:fullscreen { width: 100vw; height: 100vh; }
• 兼容性前缀：WebKit 内核浏览器（如 Safari）需使用 ::-webkit-full-screen。
• :fullscreen 伪类权重高于普通类选择器，但低于内联样式。出现冲突时可使用 !important 确保覆盖。
• 该伪类只匹配当前全屏元素本身，不匹配其子元素。

最后，汇总几个最容易被忽略的陷阱：

全屏 API 的行为高度依赖用户交互上下文与浏览器的安全策略。即使代码语法完全正确，若调用时机不在有效的用户手势回调函数内、目标元素处于不可见状态（如 display: none）、或元素内部包含 iframe 但未设置 allow="fullscreen" 属性，全屏请求都会静默失败。

调试时务必打开浏览器控制台查看错误信息，并始终以 document.fullscreenElement 的返回值作为最终状态判断依据。处理好这些细节，全屏功能才能真正稳定可靠。