JavaScript全屏API怎么用？元素全屏方法详解

JavaScript全屏API让你轻松实现网页元素（如视频、画布或自定义容器）独占屏幕显示，自动隐藏浏览器UI，无需新窗口或插件；它以`requestFullscreen()`为核心，配合`fullscreenElement`、`fullscreenEnabled`状态判断和`fullscreenchange`/`fullscreenerror`事件精准响应，但必须由用户手势触发、注意iframe权限与浏览器兼容性——掌握这些关键点，你就能快速构建稳定、跨浏览器的全屏交互体验。

JavaScript 中的全屏 API（Fullscreen API）是一组用于控制网页中某个元素以浏览器窗口大小独占显示的接口，它不打开新窗口，也不依赖插件，而是让指定元素（如视频、画布或 div）“撑满整个屏幕”，同时隐藏浏览器 UI（地址栏、工具栏等）。

全屏 API 的核心方法和属性

该 API 主要通过 Element 上的 requestFullscreen() 方法触发，配合 document 上的几个关键属性和事件使用：

• element.requestFullscreen()：请求将该元素切换为全屏（需用户手势触发，如 click）
• document.fullscreenElement：返回当前处于全屏状态的元素，为 null 表示未全屏
• document.fullscreenEnabled：布尔值，表示当前文档是否允许进入全屏（例如 iframe 没设 allowfullscreen 就为 false）
• document.onfullscreenchange：全屏状态切换时触发（进入或退出）
• document.onfullscreenerror：请求失败时触发（比如没用鼠标点击触发、被策略阻止）

如何让一个元素进入全屏（兼容写法）

由于历史原因，各浏览器曾使用不同前缀（如 webkitRequestFullscreen、msRequestFullscreen），现在主流浏览器已支持无前缀的 requestFullscreen()，但为兼容旧版，可封装一个安全调用函数：

function launchFullscreen(element) {
  if (element.requestFullscreen) {
    element.requestFullscreen();
  } else if (element.webkitRequestFullscreen) {
    element.webkitRequestFullscreen();
  } else if (element.msRequestFullscreen) {
    element.msRequestFullscreen();
  }
}

// 使用示例：点击按钮让 id="video" 的 video 元素全屏
document.getElementById('fullscreen-btn').addEventListener('click', () => {
  const video = document.getElementById('video');
  launchFullscreen(video);
});

注意事项与常见限制

全屏 API 受严格的安全策略约束，不是随时都能调用成功：

• 必须由用户手势（click、touchend、keydown 等）直接触发，不能在 setTimeout 或异步回调里调用
• iframe 需显式添加 allowfullscreen 属性才允许其内容调用全屏（）
• 某些浏览器（如 Safari）仅允许