ruanyf/jstutorial 项目解析：深入理解 Fullscreen API 全屏操作-优快云博客

ruanyf/jstutorial 项目解析：深入理解 Fullscreen API 全屏操作

jstutorial Javascript tutorial book 项目地址: https://gitcode.com/gh_mirrors/js/jstutorial

前言

在现代 Web 开发中，全屏体验已经成为提升用户沉浸感的重要手段。Fullscreen API 为开发者提供了以编程方式控制浏览器全屏显示的能力。本文将全面解析这一 API 的使用方法、兼容性处理以及实际应用中的注意事项。

基本概念

Fullscreen API 允许网页中的特定元素（及其子元素）占据整个屏幕空间，隐藏浏览器界面和其他应用程序。这种技术广泛应用于视频播放、游戏、演示文稿等需要专注浏览的场景。

核心方法

进入全屏模式

requestFullscreen() 是触发全屏的核心方法，但需要注意浏览器前缀问题：

function launchFullscreen(element) {
  if(element.requestFullscreen) {
    element.requestFullscreen();
  } else if(element.mozRequestFullScreen) {  // Firefox
    element.mozRequestFullScreen();
  } else if(element.msRequestFullscreen) {   // IE
    element.msRequestFullscreen();
  } else if(element.webkitRequestFullscreen) { // Chrome/Safari
    element.webkitRequestFullScreen();
  }
}

// 使用示例
launchFullscreen(document.getElementById("myVideo"));

浏览器行为差异：

Firefox：自动拉伸元素至全屏尺寸
Chrome：保持元素原始尺寸，居中显示
Safari：类似 Chrome 的行为

为确保一致性，建议添加 CSS 规则：

:-webkit-full-screen #myElement {
  width: 100%;
  height: 100%;
}

退出全屏模式

exitFullscreen() 方法用于退出全屏状态：

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

注意：退出全屏的操作必须通过 document 对象调用，而非元素对象。

状态检测与属性

检测全屏元素

document.fullscreenElement 返回当前全屏的元素：

var currentFullscreenElement = 
  document.fullscreenElement ||
  document.mozFullScreenElement ||
  document.webkitFullscreenElement ||
  document.msFullscreenElement;

检测全屏支持

document.fullscreenEnabled 检测浏览器是否支持全屏：

var isFullscreenSupported = 
  document.fullscreenEnabled ||
  document.mozFullScreenEnabled ||
  document.webkitFullscreenEnabled ||
  document.msFullscreenEnabled;

事件处理

Fullscreen API 提供了两个重要事件：

fullscreenchange - 全屏状态变化时触发
fullscreenerror - 全屏操作失败时触发

document.addEventListener("fullscreenchange", function(event) {
  if (document.fullscreenElement) {
    console.log('进入全屏状态');
    // 可以在这里添加全屏时的特殊逻辑
  } else {
    console.log('退出全屏状态');
    // 恢复页面正常状态
  }
});

document.addEventListener("fullscreenerror", function(event) {
  console.error('全屏操作失败:', event);
  // 可以提供用户友好的错误提示
});

CSS 全屏样式

针对不同浏览器，可以使用伪类为全屏状态设置特殊样式：

/* 标准语法 */
:fullscreen {
  background: black;
}

/* 带前缀的变体 */
:-webkit-full-screen {
  background: black;
}

:-moz-full-screen {
  background: black;
}

:-ms-fullscreen {
  background: black;
}

/* 全屏子元素样式 */
:-webkit-full-screen video {
  width: 100%;
  height: 100%;
  object-fit: contain;
}

重要提示：全屏状态下的元素默认会保持原有尺寸和位置。为确保最佳体验，建议：

为全屏元素设置合适的背景色
对媒体元素使用 object-fit 属性控制显示方式
考虑隐藏不必要的界面元素

实际应用建议

用户触发原则：全屏操作必须由用户手势（如点击）直接触发，否则会被浏览器阻止

兼容性处理：

// 封装更健壮的全屏切换函数
function toggleFullscreen(element) {
  if (!document.fullscreenElement) {
    launchFullscreen(element);
  } else {
    exitFullscreen();
  }
}