JavaScript全屏API使用教程

JavaScript全屏API是浏览器原生提供的强大功能，能让指定元素（如视频、画布或页面容器）真正进入系统级全屏状态，隐藏浏览器UI、获得沉浸式体验，远超CSS模拟的“伪全屏”；它必须由用户手势（如点击）触发，需兼容处理旧版前缀、妥善监听fullscreenchange事件、安全调用requestFullscreen()和exitFullscreen()，并注意iframe权限、移动端限制及Promise错误捕获等关键细节——掌握这些，你就能稳定、合规地为网页添加专业级全屏交互。

JavaScript 全屏 API 是一套浏览器原生提供的接口，允许网页中的某个元素（比如视频容器、画布或整个页面）临时占据用户整个屏幕，隐藏浏览器 UI（地址栏、工具栏等），常用于视频播放、游戏、数据可视化等场景。它不是 CSS 的 width: 100vw; height: 100vh 模拟，而是真正触发系统级全屏状态。

如何让元素进入全屏模式？

核心是调用目标元素的 requestFullscreen() 方法。该方法返回一个 Promise，在成功进入全屏时 resolve，失败时 reject（比如用户拒绝、不支持、或非用户手势触发）。

• 必须由用户操作（如点击、按键）触发，不能在页面加载或定时器中自动调用，否则会被浏览器静默阻止
• 推荐检查并使用带前缀的旧版方法（如 webkitRequestFullscreen、msRequestFullscreen），但现代浏览器基本都支持标准 requestFullscreen
• 示例代码：

const elem = document.getElementById('my-video');
function launchFullscreen() {
  if (elem.requestFullscreen) {
    elem.requestFullscreen();
  } else if (elem.webkitRequestFullscreen) {
    elem.webkitRequestFullscreen();
  } else if (elem.msRequestFullscreen) {
    elem.msRequestFullscreen();
  }
}

// 绑定到按钮点击
document.getElementById('fs-btn').addEventListener('click', launchFullscreen);

如何退出全屏模式？

调用全局 document.exitFullscreen() 方法即可退出当前全屏状态。同样需注意兼容性写法，并建议加 try-catch 防止报错（例如当前未处于全屏时调用会抛异常）。

• 退出后浏览器会恢复原有 UI，页面布局通常不受影响（除非你用 CSS 做了全屏适配）
• 兼容写法示例：

function exitFullscreen() {
  if (document.exitFullscreen) {
    document.exitFullscreen();
  } else if (document.webkitExitFullscreen) {
    document.webkitExitFullscreen();
  } else if (document.msExitFullscreen) {
    document.msExitFullscreen();
  }
}

如何监听全屏状态变化？

通过监听 fullscreenchange 事件，可实时感知是否进入/退出全屏。注意事件触发在 document 上，且需通过 document.fullscreenElement 判断当前哪个元素处于全屏（为 null 表示未全屏）。

• document.fullscreenElement 返回当前全屏的 DOM 元素，或 null
• 也可用 document.fullscreenEnabled 判断浏览器是否支持全屏 API
• 常用响应逻辑示例：

document.addEventListener('fullscreenchange', () => {
  if (document.fullscreenElement) {
    console.log('已进入全屏：', document.fullscreenElement.id);
  } else {
    console.log('已退出全屏');
  }
});

常见注意事项与限制

全屏 API 受安全策略严格约束，实际使用中容易踩坑：

• iframe 默认无法全屏，需添加 allow="fullscreen" 属性（如 ）
• 移动端（尤其 iOS Safari）支持有限，部分版本仅允许 元素原生全屏，不支持自定义元素
• 调用失败时 Promise 会 reject，建议用 .catch(e => console.warn('全屏失败:', e)) 捕获原因（如 NotAllowedError 表示非用户手势触发）
• 退出全屏后，焦点可能丢失，必要时手动恢复（如 elem.focus()）

基本上就这些。用好全屏 API 关键是尊重用户意图、做好降级处理、及时响应状态变化。不复杂但容易忽略权限和触发时机——只要确保是用户点出来的，基本就能稳稳跑起来。

今天关于《JavaScript全屏API使用教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！