怎么用JS监听浏览器全屏状态变化

作者:像素漫游

时间:2026-11-18

浏览:479

详细讲解如何使用 JavaScript 监听浏览器全屏状态变化,涵盖 fullscreenchange 标准事件、document.fullscreenElement 状态判断、用户主动退出识别、多浏览器兼容封装及避坑要点。

文章目录

在前端开发中,监听全屏状态变化的标准做法是向 document 绑定 fullscreenchange 事件,并在事件回调中通过读取 document.fullscreenElement 是否为 null 来判断当前是处于全屏模式还是已退出全屏。

怎么用JS监听浏览器全屏状态变化
图 1:JavaScript 全屏事件监听机制概览

一、全屏事件监听的核心机制

浏览器的 Fullscreen API 将全屏状态抽象为一个全局属性与一组事件。当页面元素进入或脱离全屏时,浏览器会在宿主文档(document)以及触发全屏的具体元素上派发一个名为 fullscreenchange 的事件。

需要注意,fullscreenchange 事件本身在触发时不携带“进入”还是“退出”的布尔值参数。判断当前状态必须通过检查 document.fullscreenElement 属性:

  • 全屏状态:document.fullscreenElement 指向当前处于全屏视图的那个 DOM 元素节点(例如某个 <video> 或 <div> 容器)。
  • 普通状态:当页面没有元素处于全屏展示模式时,document.fullscreenElement 的值为 null。
怎么用JS监听浏览器全屏状态变化
图 2:全屏状态流转与事件派发链路

二、标准监听实现与代码步骤

编写监听代码时,通常遵循四个标准步骤:声明回调函数、获取全屏元素状态、更新业务界面、挂载事件监听器。

怎么用JS监听浏览器全屏状态变化
图 3:编写全屏状态监听与响应的四个关键步骤

下面是完整的可运行代码示例。代码包含进入全屏、退出全屏以及状态变化的监听与界面反馈:

// 1. 获取 DOM 元素
const videoBox = document.getElementById('my-video-container');
const toggleBtn = document.getElementById('toggle-fullscreen-btn');

// 2. 状态变化处理函数
function handleFullscreenChange() {
  const currentElement = document.fullscreenElement;

  if (currentElement) {
    // 已经进入全屏状态
    console.log('当前已进入全屏,全屏节点为:', currentElement);
    toggleBtn.textContent = '退出全屏';
    videoBox.classList.add('is-fullscreen');
  } else {
    // 已经退出全屏状态
    console.log('当前已退出全屏');
    toggleBtn.textContent = '进入全屏';
    videoBox.classList.remove('is-fullscreen');
  }
}

// 3. 监听标准全屏变化事件
document.addEventListener('fullscreenchange', handleFullscreenChange);

// 4. 监听可能发生的全屏被拒绝或异常事件
document.addEventListener('fullscreenerror', (event) => {
  console.error('全屏模式请求失败或被浏览器拒绝:', event);
});

// 5. 触发按钮逻辑:根据当前状态切换
toggleBtn.addEventListener('click', () => {
  if (!document.fullscreenElement) {
    // 请求让容器元素进入全屏
    videoBox.requestFullscreen().catch((err) => {
      console.error(`请求全屏出错: ${err.message}`);
    });
  } else {
    // 退出全屏必须在 document 上调用
    document.exitFullscreen().catch((err) => {
      console.error(`退出全屏出错: ${err.message}`);
    });
  }
});

三、容易忽视的机制差异:Fullscreen API 与 窗口全屏 (F11)

许多开发者在测试全屏监听时,会按下键盘上的 F11 键(或在 macOS 上点击窗口绿色的全屏按钮),却发现 fullscreenchange 监听函数完全没有被调用。

这是因为浏览器严格区分了“DOM 元素全屏 (Fullscreen API)”与“浏览器窗口全屏 (Window Fullscreen)”:

  • Fullscreen API:由 JavaScript 主动调用某个 DOM 节点的 requestFullscreen() 触发。该模式下该 DOM 节点被放置在最顶层渲染图层,覆盖整个操作系统屏幕。这会精准触发 fullscreenchange 事件。
  • F11 窗口全屏:属于浏览器软件外壳自身的视口最大化,没有指定任何具体的网页 DOM 元素作为全屏载体。document.fullscreenElement 仍然为 null,因此不会触发 fullscreenchange 事件。
怎么用JS监听浏览器全屏状态变化
图 4:Fullscreen API 元素全屏与 F11 窗口全屏机制对照
如果要兼顾监听 F11 窗口全屏怎么办?

如果业务场景需要连带感知用户按 F11 导致的窗口变大,可额外监听 window 的 resize 事件,并对比 window.innerHeight === screen.height,或者通过 CSS 媒体查询 window.matchMedia('(display-mode: fullscreen)') 进行辅助捕获。

四、历史浏览器前缀与兼容封装

现代主流浏览器(Chrome 71+、Edge 79+、Firefox 64+、Safari 16.4+)均已完全支持标准无前缀的 API。但若需兼容较旧的 Safari(WebKit 内核)、早期 Firefox 或嵌入式 WebView 环境,需要对带有厂商前缀的属性与事件名称进行简单适配。

主要前缀对照关系如下:

  • 标准规范:事件为 fullscreenchange,属性为 document.fullscreenElement。
  • WebKit 前缀(旧版 Safari / 微信内旧内核):事件为 webkitfullscreenchange,属性为 document.webkitFullscreenElement。
  • Firefox 早期前缀:事件为 mozfullscreenchange,属性为 document.mozFullScreenElement。
  • IE / 早期 Edge 前缀:事件为 MSFullscreenChange,属性为 document.msFullscreenElement。

生产环境中可编写一个统一的兼容包装工具:

/**
 * 跨浏览器安全获取当前处于全屏的元素
 * @returns {Element|null}
 */
function getFullscreenElement() {
  return (
    document.fullscreenElement ||
    document.webkitFullscreenElement ||
    document.mozFullScreenElement ||
    document.msFullscreenElement ||
    null
  );
}

/**
 * 跨浏览器绑定全屏状态变化监听
 * @param {Function} callback 状态变更后的回调,入参为 (isFullscreen, currentElement)
 * @returns {Function} 用于销毁监听的清理函数
 */
function listenFullscreenChange(callback) {
  const eventNames = [
    'fullscreenchange',
    'webkitfullscreenchange',
    'mozfullscreenchange',
    'MSFullscreenChange'
  ];

  const handler = () => {
    const currentElem = getFullscreenElement();
    const isFullscreen = currentElem !== null;
    callback(isFullscreen, currentElem);
  };

  // 批量注册所有可能的前缀事件
  eventNames.forEach((name) => {
    document.addEventListener(name, handler);
  });

  // 返回卸载函数,便于在 React / Vue 组件卸载时调用
  return function unbind() {
    eventNames.forEach((name) => {
      document.removeEventListener(name, handler);
    });
  };
}

五、开发中的关键注意事项

1. 为什么不能在“全屏按钮”的点击事件中同步 UI?

很多新手喜欢在点击“进入全屏”按钮后立即将按钮文本改为“退出全屏”。这种写法存在严重漏洞:用户在全屏下按下键盘上的 ESC 键退出全屏时,并不会点击你的自定义按钮。此时,页面按钮仍旧停留在“退出全屏”,UI 与实际状态产生脱节。

因此,所有与全屏相关的 UI 渲染、图标翻转、样式切换,必须统一放在 fullscreenchange 的监听回调中处理。

2. 用户手势限制(User Gesture Requirement)

浏览器对全屏有严格的安全限制。不能在页面刚加载(DOMContentLoaded 或 window.onload)或异步定时器中无条件调用 requestFullscreen()。全屏请求必须由用户的主动点击、轻触或按键事件直接触发,否则控制台会报错并触发 fullscreenerror 事件。

3. iframe 内嵌页面的全屏权限

如果页面运行在 <iframe> 内,必须在父页面的 iframe 标签上显式声明 allow="fullscreen"(或历史属性 allowfullscreen)。若缺失该属性,内嵌页的 requestFullscreen() 会直接失败,不会进入全屏。

怎么用JS监听浏览器全屏状态变化
图 5:全屏状态监听与工程化实现全景总结

六、总结

监听浏览器全屏状态变化的核心逻辑可归结为三句话:

  1. 使用 document.addEventListener('fullscreenchange', callback) 捕获进入与退出的状态变动。
  2. 在回调中通过 document.fullscreenElement 是否为 null(或判定是否为预期元素)来确认当前全屏状态。
  3. 所有控制界面的切换逻辑(如按钮文字、图表重绘、浮窗显示)都集中在事件回调中处理,以此天然兼顾用户按 ESC 键退出的场景。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章