掌握 requestFullscreen：网页全屏功能的实用指南与技巧

想让网页上的图片、视频或者整个界面铺满用户屏幕？浏览器的 requestFullscreen api 是开发者实现这个功能的关键。它比你想象的要强大，但也藏着一些需要注意的细节。本文将详细介绍如何正确使用它，并分享一些提升用户体验的实用技巧。

一、开始使用 requestFullscreen：基础与常见问题

直接调用 element.requestFullscreen() 是最简单的方法，但有几个关键点容易出错：

并非所有元素都能直接全屏：

<div>、<section> 等普通容器元素需要提前设置好尺寸（比如 width: 100%; height: 100%; 或者具体的像素值）。否则全屏可能无效或显示异常。

<video>、<canvas> 等媒体元素通常可以直接全屏。

浏览器兼容性问题：

老版本浏览器（特别是 Safari）需要使用带前缀的方法 webkitRequestFullscreen。安全起见，最好检测并调用正确的方法。

必须在用户操作中触发：

浏览器出于安全考虑，要求全屏请求必须在用户点击、触摸等交互事件（如 click、touchstart）的处理函数里直接调用。不能放在 setTimeout 或者异步回调里直接调用，否则会被浏览器阻止。

二、控制全屏时的样式

全屏状态下，你可以使用特殊的 css 选择器为全屏元素或其内部的元素定制样式：

/* 为处于全屏状态的 <video> 元素设置黑色背景 */
video:fullscreen {
  background-color: #000;
}

/* 当某个具有 id="controls" 的元素在全屏模式下时，默认半透明，鼠标移上去变清晰 */
#controls:fullscreen {
  opacity: 0.3;
  transition: opacity 0.3s ease;
}
#controls:fullscreen:hover {
  opacity: 1;
}

:-webkit-full-screen (WebKit 前缀): 针对老版本 WebKit 内核浏览器（如旧 Safari）。

:fullscreen (标准): 现代浏览器支持的标准写法。优先使用这个。

三、实用的进阶技巧

在多个元素间切换全屏：
创建一个管理器能方便地在不同元素（如图库中的图片）之间切换全屏状态，并记住当前全屏的是哪个元素。

const fullscreenManager = {
  currentElement: null, // 记录当前全屏的元素

  async toggle(element) {
    // 如果点击的元素已经是全屏元素，则退出全屏
    if (document.fullscreenElement && this.currentElement === element) {
      try {
        await document.exitFullscreen();
        this.currentElement = null;
      } catch (error) {
        console.error('退出全屏失败:', error);
      }
    } else {
      // 否则，尝试让新元素进入全屏
      try {
        await element.requestFullscreen();
        this.currentElement = element; // 更新当前元素
      } catch (error) {
        console.error('进入全屏失败:', error);
        // 可以在这里提供一个后备方案，比如模拟全屏的CSS类
        element.classList.add('simulated-fullscreen');
      }
    }
  }
};

// 给图库中所有图片绑定点击事件
document.querySelectorAll('.gallery-img').forEach(img => {
  img.addEventListener('click', () => fullscreenManager.toggle(img));
});

在全屏模式下处理键盘事件：
全屏时，你可能想添加自定义快捷键（如切换滤镜、截图）。

function handleFullscreenHotkeys(event) {
  // 保留 Escape 键退出全屏的功能
  if (event.key === 'Escape') return;

  // 自定义快捷键
  if (event.key === 'f') toggleFilter(); // 按 F 切换滤镜
  if (event.ctrlKey && event.key === 'p') enterPictureInPicture(); // Ctrl+P 画中画
  if (event.shiftKey && event.key === 's') captureScreenshot(); // Shift+S 截图

  // 阻止这些键的默认行为（比如防止F键触发浏览器查找）
  event.preventDefault();
}

// 监听全屏状态变化
document.addEventListener('fullscreenchange', () => {
  if (document.fullscreenElement) {
    // 进入全屏，添加自定义键盘监听
    document.addEventListener('keydown', handleFullscreenHotkeys);
  } else {
    // 退出全屏，移除自定义键盘监听
    document.removeEventListener('keydown', handleFullscreenHotkeys);
  }
});

记住用户的全屏状态：
如果用户刷新页面，可以尝试自动恢复他们之前全屏查看的元素。

// 页面加载完成后检查是否需要恢复全屏
window.addEventListener('domContentLoaded', () => {
  const elementId = localStorage.getItem('fullscreenElementId');
  if (elementId) {
    const element = document.getElementById(elementId);
    if (element) {
      setTimeout(() => element.requestFullscreen().catch(console.error), 100); // 稍延迟确保元素就绪
    }
  }
});

// 监听全屏变化，保存当前全屏元素的ID
document.addEventListener('fullscreenchange', () => {
  if (document.fullscreenElement) {
    localStorage.setItem('fullscreenElementId', document.fullscreenElement.id);
  } else {
    localStorage.removeItem('fullscreenElementId');
  }
});

处理嵌套全屏（沙盒内全屏）：
在已经全屏的容器内的 <iframe> 中再次触发全屏是可能的（需要 allow="fullscreen" 属性）。

<div id="main-container">
  <iframe id="nested-content" src="inner.html" allow="fullscreen"></iframe>
</div>
<script>
  const mainContainer = document.getElementById('main-container');
  const iframe = document.getElementById('nested-content');

  // 主容器全屏后，可以尝试触发iframe内部元素的全屏（需内部配合）
  mainContainer.addEventListener('fullscreenchange', () => {
    if (document.fullscreenElement === mainContainer) {
      // 假设iframe内部有一个id为'innerVideo'的视频元素
      // 注意：这需要在iframe加载完成后，且iframe内容同源或允许跨域操作
      const innerDoc = iframe.contentDocument || iframe.contentWindow.document;
      const innerVideo = innerDoc.getElementById('innerVideo');
      if (innerVideo) {
        setTimeout(() => innerVideo.requestFullscreen().catch(console.error), 500);
      }
    }
  });
</script>

四、实际应用场景

媒体展示： 图片画廊、视频播放器（隐藏浏览器UI获得更好沉浸感 { navigationUI: 'hide' }）。

数据密集型应用： 全屏表格、图表或数据看板，提供更大的工作空间。

游戏与交互： WebGL 游戏、交互式动画、全景图查看器（结合陀螺仪 API），全屏能提升性能和体验。

演示模式： 在线文档、幻灯片展示。

专注模式： 写作工具、代码编辑器。

安全措施： 在全屏内容上添加低透明度水印（使用 ::before / ::after 伪元素），增加录屏难度。

五、开发者需要注意的问题与解决建议

问题描述	解决方案
iOS Safari 全屏视频行为	为 <video> 添加 playsinline 属性防止自动横屏。提供手动旋转按钮。
全屏导致滚动位置丢失	进入全屏前记录 scrollTop，退出后恢复。或使用 scroll-snap 等布局技术。
全屏触发页面重排/抖动	提前给目标元素设置 width: 100%; height: 100%; 或固定尺寸。
全屏时难以打开开发者工具	在开发环境，避免拦截 F12 或右键菜单快捷键。使用 console 调试。
全屏元素内 iframe 权限	为 <iframe> 添加 allow="fullscreen" 属性。
检测用户手动全屏 (F11)	比较 window.outerHeight 和 screen.height 有一定参考价值，但非绝对可靠。通常建议引导用户使用应用内的全屏按钮。

六、兼容性处理封装（推荐使用）

下面是一个更健壮的工具函数，处理了不同浏览器的前缀问题：

/**
 * 全屏工具类 (简化版，展示核心功能)
 */
const FullscreenHelper = {
  /**
   * 请求元素进入全屏模式
   * @param {HTMLElement} [element=document.documentElement] 要全屏的元素，默认是整个页面
   * @returns {Promise<boolean>} 是否成功进入全屏
   */
  async enter(element = document.documentElement) {
    const reqMethods = [
      'requestFullscreen',       // 标准
      'webkitRequestFullscreen', // Safari, Old Chrome/Edge
      'mozRequestFullScreen',    // Firefox
      'msRequestFullscreen'      // Old IE/Edge
    ];

    for (const method of reqMethods) {
      if (element[method]) {
        try {
          // 可以传递选项，例如隐藏导航UI: { navigationUI: 'hide' }
          await element[method]({ navigationUI: 'hide' });
          return true; // 成功进入全屏
        } catch (error) {
          console.warn(`${method} 失败:`, error);
          // 继续尝试下一个方法
        }
      }
    }
    return false; // 所有方法都失败
  },

  /**
   * 退出全屏模式
   * @returns {Promise<boolean>} 是否成功退出全屏
   */
  async exit() {
    const exitMethods = [
      'exitFullscreen',          // 标准
      'webkitExitFullscreen',     // Safari, Old Chrome/Edge
      'mozCancelFullScreen',      // Firefox
      'msExitFullscreen'          // Old IE/Edge
    ];

    for (const method of exitMethods) {
      if (document[method]) {
        try {
          await document[method]();
          return true; // 成功退出全屏
        } catch (error) {
          console.warn(`${method} 失败:`, error);
        }
      }
    }
    return false; // 所有方法都失败或不在全屏状态
  },

  /**
   * 检查当前是否有元素处于全屏状态
   * @returns {boolean} 是否在全屏状态
   */
  isFullscreen() {
    return !!(
      document.fullscreenElement ||    // 标准
      document.webkitFullscreenElement || // Safari, Old Chrome/Edge
      document.mozFullScreenElement || // Firefox
      document.msFullscreenElement     // Old IE/Edge
    );
  },

  /**
   * 添加全屏状态变化监听器
   * @param {Function} callback 状态变化时触发的回调函数
   */
  onChange(callback) {
    const events = [
      'fullscreenchange',       // 标准
      'webkitfullscreenchange', // Safari, Old Chrome/Edge
      'mozfullscreenchange',    // Firefox
      'MSFullscreenChange'      // Old IE/Edge
    ];
    // 为每种可能的事件添加监听，确保兼容性
    events.forEach(eventName => {
      document.addEventListener(eventName, callback);
    });
  }
};

// 使用示例
const myButton = document.getElementById('fullscreen-btn');
const myVideo = document.getElementById('my-video');

myButton.addEventListener('click', async () => {
  if (FullscreenHelper.isFullscreen()) {
    await FullscreenHelper.exit();
  } else {
    await FullscreenHelper.enter(myVideo); // 让视频全屏
  }
});

// 监听全屏变化
FullscreenHelper.onChange(() => {
  console.log('全屏状态变了:', FullscreenHelper.isFullscreen() ? '进入全屏' : '退出全屏');
});

总结

requestFullscreen API 是实现网页元素全屏展示的核心工具。理解其基础用法、兼容性处理、样式控制和状态管理是第一步。通过掌握切换控制、键盘事件处理、状态持久化和嵌套全屏等进阶技巧，以及规避常见的陷阱，你可以为用户创建更流畅、功能更丰富的全屏体验。上面的 FullscreenHelper 工具类封装了兼容性细节，推荐在实际项目中使用。现在就去尝试在你的网页中应用这些技巧吧！

链接: https://fly63.com/article/detial/12861