JavaScript全屏API使用与退出方法

JavaScript全屏API看似简单，实则暗藏兼容性陷阱与交互雷区：从必须由用户手势触发的硬性要求，到Chrome/Safari/Firefox各异的前缀降级策略；从仅能通过document.exitFullscreen()全局退出的特殊设计，到fullscreenchange/error事件监听的异步本质；再到iframe需显式声明allow="fullscreen"、iOS Safari长期不支持、移动端video优化等真实开发痛点——本文直击全屏功能落地中的关键细节与避坑指南，帮你避开静默失败、状态失控和体验断层，真正实现稳定、合规、跨浏览器的全屏交互。

JavaScript全屏API的使用需兼顾浏览器兼容性、用户交互合规性及状态管理，核心是统一调用标准方法并正确处理前缀差异与事件响应。

进入全屏：优先使用标准方法，降级支持旧前缀

现代浏览器支持 Element.requestFullscreen()，但部分旧版Chrome/Safari仍需 webkitRequestFullscreen()，Firefox旧版用 mozRequestFullScreen()。不应直接调用 document.documentElement.requestFullscreen()，而应作用于具体容器元素（如一个 div），避免整个页面失控。

• 检查元素是否支持全屏：if (element.requestFullscreen) 再调用
• 触发必须由用户手势（如 click、keydown）发起，否则被浏览器静默拒绝
• 可传入可选配置对象控制方向，例如 element.requestFullscreen({ navigationUI: 'hide' })（仅部分浏览器支持）

退出全屏：统一调用 document.exitFullscreen()

退出操作不绑定在元素上，而是全局调用 document.exitFullscreen()。同样需兼容前缀：document.webkitExitFullscreen()、document.mozCancelFullScreen()。

• 调用前建议判断当前是否处于全屏状态：document.fullscreenElement !== null
• 避免重复调用，可在退出后清空相关 UI 状态（如切换“退出全屏”按钮为“进入全屏”）
• 注意：Safari 在 iOS 上不支持全屏 API，桌面版 Safari 16.4+ 才完整支持

监听全屏状态变化：用 fullscreenchange 和 fullscreenerror

全屏切换是异步行为，必须通过事件监听实际结果。监听对象是 document，而非具体元素。

• document.addEventListener('fullscreenchange', () => { ... })：进入或退出时触发，通过 document.fullscreenElement 判断当前状态
• document.addEventListener('fullscreenerror', () => { ... })：权限被拒、非用户手势触发等失败时触发，应提示用户原因
• 建议在组件卸载或页面离开前移除事件监听，防止内存泄漏

安全与体验要点：不可忽略的细节

全屏模式受浏览器策略严格约束，违反规则会导致静默失败或报错。

• iframe 需添加 allow="fullscreen" 属性才可触发其内部内容全屏
• 移动端（尤其是 Android Chrome）对 video 元素全屏有特殊优化，推荐用 的原生 controls + webkit-playsinline 配合 requestFullscreen
• 全屏期间 document.body 会自动添加 fullscreen 类（部分浏览器），可用于 CSS 样式隔离
• 退出全屏后焦点可能丢失，必要时手动恢复 focus 到关键元素

好了，本文到此结束，带大家了解了《JavaScript全屏API使用与退出方法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！