JS调用Document.exitFullscreen()退出全屏的标准写法

作者:流萤

时间:2026-11-22

浏览:537

全面解析JavaScript中调用Document.exitFullscreen()退出全屏的标准写法、核心机制、异步Promise处理、状态防护及常见误区。

文章目录

在 JavaScript 全屏 API(Fullscreen API)中,退出全屏的标准方法是 document.exitFullscreen()。该方法是异步执行的,返回一个 Promise 对象。在实际业务开发中,开发者最容易踩入两类陷阱:一是错误地在具体的 DOM 元素上调用该方法,二是未检查当前页面是否正处于全屏状态便直接调用,进而导致浏览器抛出 TypeError 异常。本文将系统讲解 Document.exitFullscreen() 的标准写法、调用守卫、异步捕获、事件协同以及历史浏览器兼容降级策略。

一、核心认知:为什么是 Document 而不是 Element

在全屏 API 的规范设计中,进入全屏与退出全屏的承载对象具有明显的不对称性:

  • 进入全屏:调用的是具体 DOM 元素的方法,例如 videoElement.requestFullscreen() 或 document.documentElement.requestFullscreen(),其意图是让该指定元素脱离常规文档流,覆盖整个屏幕视图。
  • 退出全屏:调用的是顶级文档对象的方法,即 document.exitFullscreen()。因为无论先前是哪个具体元素进入了全屏,全屏模式本身都属于当前浏览上下文(Document Context)的全局呈现状态,由文档顶层统一撤销并恢复常规渲染。
JS调用Document.exitFullscreen()退出全屏的标准写法
图 1:进入全屏与退出全屏的 API 调用对象及语义差异
高频错误提示: 千万不要尝试书写 element.exitFullscreen()。在常规 DOM 元素的原型链上并没有该方法,这样调用会直接抛出 Uncaught TypeError: element.exitFullscreen is not a function。

二、标准调用写法与状态守卫

按照 W3C 规范,如果当前文档并没有任何元素处于全屏状态(即 document.fullscreenElement === null),此时强制调用 document.exitFullscreen(),返回的 Promise 将会被 reject,并在控制台中产生未捕获的 TypeError。

因此,工业级的前端实现必须在调用前加入状态守卫(Guard Check),先验证当前是否存在全屏元素,然后再执行退出并妥善处理 Promise:

1. 基于 async/await 的标准写法(推荐)

/**
 * 安全退出全屏模式的标准函数
 * @returns {Promise<void>}
 */
async function exitFullscreenSafely() {
  // 1. 状态守卫:检查当前文档是否处于全屏状态
  if (!document.fullscreenElement) {
    // 当前并未处于全屏状态,安全跳过退出操作
    return;
  }

  try {
    // 2. 调用标准方法并等待异步 Promise 完成
    await document.exitFullscreen();
  } catch (error) {
    // 3. 捕获权限受阻或上下文失效等意外异常
    console.error('退出全屏失败:', error);
  }
}

2. 基于 Promise 链式调用的标准写法

function exitFullscreenPromise() {
  if (!document.fullscreenElement) {
    return Promise.resolve();
  }

  return document.exitFullscreen().catch((error) => {
    console.warn('退出全屏操作未能成功执行:', error);
  });
}
JS调用Document.exitFullscreen()退出全屏的标准写法
图 2:安全调用 Document.exitFullscreen() 的完整执行流程与分支处理

三、全屏状态联动:不要只在退出按钮中修改 UI

在实际网页中,全屏的退出并不完全依赖网页里的“退出全屏”按钮。用户随时可以按下键盘上的 Esc 键,或者通过操作系统的全屏控制栏主动退出全屏。

如果你仅仅在按钮点击事件触发 document.exitFullscreen() 的回调里更新按钮图标或文字状态,一旦用户通过 Esc 退出,页面上的按钮状态就会与实际显示状态完全脱节。

最佳实践: 将 UI 状态更新与 fullscreenchange 事件绑定,让视图完全由全屏状态的变更事件驱动,实现真正的单向状态流与解耦。

// 统一监听文档的全屏变化事件
document.addEventListener('fullscreenchange', () => {
  const isCurrentlyFullscreen = Boolean(document.fullscreenElement);
  
  // 根据全屏状态统一切换按钮文字或样式
  const toggleBtn = document.getElementById('fullscreenToggleBtn');
  if (toggleBtn) {
    toggleBtn.textContent = isCurrentlyFullscreen ? '退出全屏' : '进入全屏';
    toggleBtn.setAttribute('aria-pressed', String(isCurrentlyFullscreen));
  }
});

// 监听可能发生的全屏错误
document.addEventListener('fullscreenerror', (event) => {
  console.error('全屏模式切换发生错误:', event);
});

四、历史浏览器与内核前缀兼容方案

现代主流浏览器(包括 Chrome 71+、Firefox 64+、Edge 79+、Safari 16.4+)均已全面支持标准未加前缀的 document.exitFullscreen()。但在涉及特定内嵌 WebView、定制工控屏浏览器或维护较旧的企业级项目时,仍需考虑厂商前缀的降级适配。

规范阶段 全屏检测属性 退出全屏方法 典型适用环境
W3C 标准规范 document.fullscreenElement document.exitFullscreen() 所有现代主流桌面与移动浏览器
WebKit 前缀 document.webkitFullscreenElement document.webkitExitFullscreen() 旧版 Safari、旧版 Android WebView
Gecko (火狐) 前缀 document.mozFullScreenElement document.mozCancelFullScreen() 旧版 Firefox(注意方法名为 Cancel)
Trident / IE11 document.msFullscreenElement document.msExitFullscreen() IE 11 及早期的 EdgeHTML
JS调用Document.exitFullscreen()退出全屏的标准写法
图 3:现代标准与跨内核前缀的降级适配调用架构

工业级跨浏览器退出全屏封装实现

/**
 * 跨浏览器兼容的退出全屏通用封装
 * @returns {Promise<void>}
 */
function exitFullscreenUniversal() {
  // 1. 获取当前处于全屏的元素(带前缀兼容)
  const fullscreenElement =
    document.fullscreenElement ||
    document.webkitFullscreenElement ||
    document.mozFullScreenElement ||
    document.msFullscreenElement;

  if (!fullscreenElement) {
    return Promise.resolve();
  }

  // 2. 依次匹配标准方法与各内核前缀方法
  if (document.exitFullscreen) {
    return document.exitFullscreen();
  } else if (document.webkitExitFullscreen) {
    return Promise.resolve(document.webkitExitFullscreen());
  } else if (document.mozCancelFullScreen) {
    return Promise.resolve(document.mozCancelFullScreen());
  } else if (document.msExitFullscreen) {
    return Promise.resolve(document.msExitFullscreen());
  }

  return Promise.reject(new Error('当前运行环境不支持 Fullscreen API'));
}

五、常见问题排查与注意事项

  • 问题 1:调用时报错 TypeError: Document not active 或全屏未开启
    原因: 在未全屏或者非当前激活标签页中调用了 exitFullscreen()。排查方案是确保在调用前检查 document.fullscreenElement 是否有效。
  • 问题 2:在 iframe 中调用退出全屏无效或报错
    原因: 如果页面嵌入在 <iframe> 中,iframe 必须声明 allow="fullscreen"(或在旧版中包含 allowfullscreen 属性),否则浏览器的权限策略(Permissions Policy)会阻止全屏状态变更。
  • 问题 3:误在全屏元素的销毁阶段同步调用
    原因: 如果在组件卸载(如 React 的 componentWillUnmount 或 Vue 的 unmounted)时需要退出全屏,必须先确认该组件或其子元素是否即为 document.fullscreenElement,避免引发冗余调用或竞争条件。
JS调用Document.exitFullscreen()退出全屏的标准写法
图 4:Document.exitFullscreen() 标准工程落地四大核心要则总结

六、总结

调用 Document.exitFullscreen() 退出全屏时,核心要把握三条关键准则:第一,明确调用主体是 document 而非任意 DOM 节点;第二,前置检查 document.fullscreenElement,避免在未全屏时盲目调用而抛出未捕获异常;第三,视图状态应统一监听 fullscreenchange 事件,以兼容用户键盘按键等系统级退出行为。

实用工具推荐

电子包浆

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

使用 ›
图片压缩

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

使用 ›
相关文章