1. 全屏这件事浏览器到底把控制权交给了谁很多人第一次接触全屏是在做视频播放器或者在线演示工具的时候。产品经理跑过来说“点一下按钮让内容铺满整个屏幕”你第一反应可能是去调 CSS把容器宽高设成 100vw 和 100vh再配个position: fixed把 z-index 拉到最高。这么做在普通页面里看着像那么回事但只要用户按一下 F11或者浏览器地址栏、书签栏、系统任务栏还在你就会发现所谓“全屏”其实只是“占满可视区域”离真正的全屏差得远。浏览器提供的 Fullscreen API 解决的正是这个问题。它让页面里的某个元素——注意是任意元素不一定是整个 document——能够请求进入操作系统的全屏状态此时浏览器自身的界面地址栏、标签栏、工具栏会被隐藏元素独占整个屏幕。这个能力在视频播放、在线幻灯片、网页游戏、图片查看器、代码演示等场景里几乎是刚需。关键词里虽然只给了“JS API: Fullscreen 全屏 API”这一条但真正要讲清楚的东西远不止一个requestFullscreen()方法。它涉及一套完整的权限模型、事件体系、样式伪类、跨浏览器前缀历史以及一堆实际开发中会踩的坑。我见过太多项目在这上面翻车有的是 Safari 上死活进不去全屏有的是退出全屏后布局错乱还有的是在 iframe 里调用直接被浏览器拒绝控制台连个像样的报错都不给。这篇文章面向的是已经会写 JavaScript、准备在真实项目里落地全屏功能的开发者。我会从 API 的设计逻辑讲起把每个方法的参数、返回值、触发条件拆开说再补上跨浏览器兼容的实战写法、事件监听的正确姿势、CSS 配合技巧以及我自己在项目里踩过的那些坑。读完你应该能直接把这套代码抄进项目并且知道每一行为什么这么写。先说一个最容易被忽略的前提全屏请求必须由用户手势触发。所谓用户手势指的是 click、touch、keydown 这类由真实用户操作产生的事件。你在setTimeout里调、在 Promise 的 then 里调、在页面 load 时自动调统统会被浏览器拒绝而且不同浏览器的拒绝方式还不一样——有的抛异常有的返回一个 rejected 的 Promise有的干脆静默失败。这一点后面会专门展开。2. requestFullscreen 的调用姿势与参数细节2.1 方法挂在 Element 上不是 document 上这是新手最容易搞混的一点。全屏 API 的入口是Element.requestFullscreen()也就是说你得先拿到一个具体的 DOM 元素再调它的方法。想让整个页面全屏就传document.documentElement想让某个视频容器全屏就传那个容器。// 整个页面全屏 document.documentElement.requestFullscreen(); // 某个具体元素全屏 const player document.querySelector(#video-player); player.requestFullscreen();为什么设计成挂在元素上而不是 document 上因为全屏的本质是“让某个元素独占屏幕”浏览器需要知道你到底想让谁全屏。如果只有一个全局方法浏览器还得猜你的意图。挂在元素上语义就非常清晰了。这里有个细节一旦某个元素进入全屏它以及它的后代元素会组成一个“全屏元素树”fullscreen element tree。在这个树里的元素渲染层级会被提升到最顶层普通元素的 z-index 再高也盖不住它。这也是为什么全屏后你原来的弹窗、下拉菜单可能“消失”了——它们不在全屏元素树里自然被盖在下面。2.2 options 参数navigationUI 到底管什么requestFullscreen()接受一个可选参数对象目前主流浏览器支持的是navigationUI取值有auto、hide、show三种。element.requestFullscreen({ navigationUI: hide });auto默认值由浏览器自己决定是否显示导航界面。hide请求隐藏导航 UI比如某些浏览器全屏时顶部会短暂出现的提示条。show请求显示导航 UI。说实话这个参数的实际效果在不同浏览器、不同平台上差异很大很多情况下浏览器会忽略你的请求因为它要考虑用户如何退出全屏。我的建议是除非你有非常明确的理由否则不要传这个参数用默认行为就好。传了反而可能在某些浏览器上触发意料之外的表现。2.3 返回值是一个 Promise但别高兴太早现代浏览器里requestFullscreen()返回一个 Promise。成功进入全屏时 resolve失败时 reject 并带上一个TypeError。这看起来很美你可以用await或者.catch()来处理错误。async function enterFullscreen(el) { try { await el.requestFullscreen(); console.log(进入全屏成功); } catch (err) { console.error(进入全屏失败:, err.message); } }但这里有个历史遗留问题老版本浏览器尤其是带 webkit 前缀的那些返回的是 undefined不是 Promise。如果你直接await一个 undefined虽然不会报错await undefined 会立即 resolve但你也拿不到任何错误信息。所以如果你的项目还要兼容老浏览器错误处理不能只依赖 Promise 的 catch还得配合fullscreenerror事件。我个人的做法是封装一个统一的函数内部判断返回值是不是 Promise同时监听错误事件兜底。这样无论浏览器新旧行为都一致。2.4 用户手势这道坎绕不过去前面提过全屏请求必须由用户手势触发。但“用户手势”的判定比想象中严格。以下这些情况都可能被拒绝在setTimeout、setInterval回调里调用。在fetch或Promise.then的异步回调里调用即使这个 Promise 是在 click 里发起的。在requestAnimationFrame回调里调用。页面刚加载时自动调用。浏览器这么设计是为了防止恶意网站在用户不知情的情况下强制全屏属于安全策略没有绕过的方法。实际开发中如果你需要在异步操作完成后再进全屏比如先请求接口拿视频地址再全屏播放正确做法是先同步进入全屏再在异步回调里做其他事或者引导用户再点一次。// 错误示范异步回调里请求全屏大概率被拒 button.addEventListener(click, async () { const data await fetchVideoInfo(); await player.requestFullscreen(); // 可能失败 }); // 正确示范先同步全屏再异步加载内容 button.addEventListener(click, () { player.requestFullscreen(); // 同步调用手势有效 loadVideoContent(); // 异步加载内容 });3. 退出全屏与状态查询exitFullscreen 和 fullscreenElement3.1 退出全屏只有一条路退出全屏用的是document.exitFullscreen()注意它挂在 document 上不是元素上。这跟进入全屏不对称很多人第一次写会写成element.exitFullscreen()结果报错。document.exitFullscreen();同样返回 Promise同样在老浏览器上可能是 undefined。退出全屏不需要用户手势你可以在任何地方调用比如按 ESC 键、点关闭按钮、或者视频播放结束时自动退出。3.2 判断当前是否处于全屏查询当前全屏元素用document.fullscreenElement。如果当前没有元素处于全屏它的值是null否则返回那个全屏的元素。if (document.fullscreenElement) { console.log(当前全屏元素:, document.fullscreenElement); } else { console.log(当前没有元素处于全屏); }这个属性非常有用。比如你想做一个“全屏/退出全屏”切换按钮就可以根据它来判断当前状态决定调用哪个方法。function toggleFullscreen(el) { if (document.fullscreenElement) { document.exitFullscreen(); } else { el.requestFullscreen(); } }3.3 全屏元素树与 fullscreenElement 的关系前面提到全屏元素树的概念这里再深入一点。当你让元素 A 全屏后document.fullscreenElement返回的就是 A。如果 A 内部还有元素 BB 也在全屏元素树里但fullscreenElement依然返回 A不会返回 B。只有当你在全屏状态下再让 B 全屏嵌套全屏fullscreenElement才会变成 B。嵌套全屏在实际项目中用得不多但理解它有助于你搞清楚全屏的层级关系。退出时exitFullscreen()会退出当前最内层的全屏回到上一层。如果只有一层就直接退出全屏状态。3.4 一个容易忽略的细节全屏状态是全局的document.fullscreenElement是全局的不是某个元素私有的。这意味着如果你在页面里同时管理多个可能全屏的组件比如两个视频播放器它们共享同一个全屏状态。一个进了全屏另一个查询fullscreenElement也会得到非 null 的结果。所以组件之间要做好协调避免互相干扰。我见过一个项目页面上有两个播放器用户让 A 全屏后B 组件的“全屏”按钮状态没更新显示的还是“进入全屏”点一下反而把 A 的全屏退出了。这就是没有监听全屏变化事件导致的。下一节就讲事件。4. 全屏事件体系change 和 error 的正确监听方式4.1 fullscreenchange状态变化的唯一可靠信号全屏状态发生变化时浏览器会在 document 上触发fullscreenchange事件。注意是 document不是元素。这个事件不携带任何关于“是进入还是退出”的信息你需要自己读document.fullscreenElement来判断。document.addEventListener(fullscreenchange, () { if (document.fullscreenElement) { console.log(已进入全屏); } else { console.log(已退出全屏); } });为什么这个事件这么重要因为用户退出全屏的方式太多了按 ESC、按 F11、点浏览器自带的退出按钮、切换标签页、甚至系统层面的操作。你无法拦截所有这些操作唯一能做的就是监听fullscreenchange在状态变化时同步你的 UI。比如你的全屏按钮需要在进入全屏后变成“退出全屏”图标就必须在这个事件里更新。否则用户按 ESC 退出后按钮还显示“退出全屏”体验就很糟糕。4.2 fullscreenerror失败时的兜底当全屏请求失败时除了 Promise 被 reject浏览器还会在 document 上触发fullscreenerror事件。document.addEventListener(fullscreenerror, (event) { console.error(全屏请求失败); });这个事件在什么时候有用主要是兼容老浏览器以及处理那些 Promise 没有正确 reject 的情况。比如某些浏览器在 iframe 里请求全屏失败时Promise 可能不 reject但fullscreenerror会触发。所以稳妥的做法是两者都监听。4.3 事件监听要绑在 document 上且只绑一次新手常犯的错误是把fullscreenchange绑在具体元素上。虽然某些浏览器可能也支持但标准规定是绑在 document 上。绑在元素上在部分浏览器里收不到事件。另一个问题是重复绑定。如果你在组件挂载时绑一次卸载时没解绑多次挂载后同一个事件会触发多次回调导致逻辑重复执行。在单页应用里这个问题尤其常见。// 组件挂载 function onFullscreenChange() { // 更新 UI } document.addEventListener(fullscreenchange, onFullscreenChange); // 组件卸载 document.removeEventListener(fullscreenchange, onFullscreenChange);4.4 事件触发时机的一个坑fullscreenchange的触发时机是“全屏状态已经改变之后”不是“即将改变”。这意味着在事件回调里document.fullscreenElement已经是新值了。这个设计是合理的但如果你在事件里做动画或者布局计算要注意此时 DOM 已经处于全屏状态尺寸可能已经变了。还有一个细节进入全屏和退出全屏都会触发fullscreenchange而且只触发一次。但如果你在事件回调里又调用了requestFullscreen或exitFullscreen可能引发连锁反应。所以回调里尽量避免直接操作全屏状态除非你很清楚自己在做什么。5. 跨浏览器兼容前缀、差异与统一封装5.1 前缀的历史包袱Fullscreen API 在标准化之前各家浏览器用了不同的前缀标准Chrome/Safari/OperaFirefoxIE/EdgerequestFullscreenwebkitRequestFullscreenmozRequestFullScreenmsRequestFullscreenexitFullscreenwebkitExitFullscreenmozCancelFullScreenmsExitFullscreenfullscreenElementwebkitFullscreenElementmozFullScreenElementmsFullscreenElementfullscreenchangewebkitfullscreenchangemozfullscreenchangeMSFullscreenChangefullscreenerrorwebkitfullscreenerrormozfullscreenerrorMSFullscreenError注意 Firefox 的mozRequestFullScreen里 Screen 的 S 是大写mozCancelFullScreen也是。这个大小写问题坑过不少人写错了方法就不存在。现代浏览器基本都支持无前缀版本了但如果你的项目要兼容较老的浏览器还是得做前缀检测。我的建议是写一个统一的工具函数把这些差异封装起来业务代码只调标准方法。5.2 统一封装实战下面是我在项目里常用的封装思路是优先用标准方法不支持则回退到前缀方法同时统一事件名。const FullscreenHelper { // 获取当前全屏元素 getFullscreenElement() { return document.fullscreenElement || document.webkitFullscreenElement || document.mozFullScreenElement || document.msFullscreenElement || null; }, // 请求全屏 request(element) { const el element || document.documentElement; const fn el.requestFullscreen || el.webkitRequestFullscreen || el.mozRequestFullScreen || el.msRequestFullscreen; if (fn) { return fn.call(el); } return Promise.reject(new Error(当前浏览器不支持全屏 API)); }, // 退出全屏 exit() { const fn document.exitFullscreen || document.webkitExitFullscreen || document.mozCancelFullScreen || document.msExitFullscreen; if (fn) { return fn.call(document); } return Promise.reject(new Error(当前浏览器不支持退出全屏)); }, // 监听全屏变化 onChange(callback) { const events [ fullscreenchange, webkitfullscreenchange, mozfullscreenchange, MSFullscreenChange ]; events.forEach(evt document.addEventListener(evt, callback)); // 返回解绑函数 return () { events.forEach(evt document.removeEventListener(evt, callback)); }; } };这个封装的好处是业务代码完全不用关心前缀调用FullscreenHelper.request(el)就行。onChange返回一个解绑函数方便在组件卸载时清理。5.3 Safari 的特殊脾气Safari 在全屏这件事上有几个特殊行为值得单独说。第一Safari 对用户手势的判定非常严格。在某些版本里如果你在 click 回调里先做了一些同步操作比如修改 DOM再调requestFullscreen可能会被拒绝。稳妥的做法是把requestFullscreen放在 click 回调的最前面。第二Safari 在 iPad 上的全屏行为和桌面版不同。iPad 的 Safari 对全屏的支持一直比较微妙某些版本里requestFullscreen对非视频元素无效。如果你的目标用户包含 iPad建议做降级处理比如用 CSS 模拟全屏效果。第三Safari 退出全屏时fullscreenchange的触发时机可能比其他浏览器晚一点。如果你在事件里做布局计算可能会拿到旧值。这种情况可以用requestAnimationFrame包一层等下一帧再读。5.4 iframe 里的全屏allowfullscreen 不能少如果你的页面嵌在 iframe 里想在 iframe 内部请求全屏必须在 iframe 标签上加上allowfullscreen属性。iframe srcplayer.html allowfullscreen/iframe没有这个属性iframe 内部调requestFullscreen会被拒绝而且错误信息往往很模糊。这是安全策略的一部分防止嵌入的第三方内容强制全屏。另外如果 iframe 有sandbox属性还需要确保没有禁用allow-fullscreen注意 sandbox 里的写法是allow-fullscreen和 iframe 的allowfullscreen属性名不一样。这个细节很容易搞混。6. CSS 配合:fullscreen 伪类与布局调整6.1 :fullscreen 伪类怎么用元素进入全屏后可以用:fullscreen伪类给它加样式。同样有前缀版本:-webkit-full-screen、:-moz-full-screen、:-ms-fullscreen。/* 标准写法 */ .player:fullscreen { width: 100%; height: 100%; background: #000; } /* WebKit 前缀 */ .player:-webkit-full-screen { width: 100%; height: 100%; background: #000; }注意前缀伪类的写法差异很大WebKit 是:-webkit-full-screen有连字符Moz 是:-moz-full-screenMS 是:-ms-fullscreen。写的时候要小心写错了整条规则失效。6.2 全屏后元素尺寸的变化元素进入全屏后它的尺寸会变成屏幕尺寸但它的父元素、兄弟元素的布局不会自动调整。也就是说如果你把一个原本宽 300px 的 div 全屏它会变成全屏大小但它原来的位置会留下空白其他元素不会自动填补。这就是为什么很多项目全屏后布局会乱。解决办法通常是全屏时给 body 加一个类用 CSS 把其他内容隐藏或者调整布局。document.addEventListener(fullscreenchange, () { if (document.fullscreenElement) { document.body.classList.add(is-fullscreen); } else { document.body.classList.remove(is-fullscreen); } });body.is-fullscreen { overflow: hidden; } body.is-fullscreen .other-content { display: none; }6.3 全屏下的滚动与溢出全屏元素默认是可以滚动的如果你不希望它滚动需要显式设置overflow: hidden。但要注意全屏元素本身如果内容超出滚动条会出现在全屏元素内部而不是整个页面。另一个坑是全屏状态下100vh的取值可能和预期不同。某些浏览器在全屏时100vh会包含或者不包含某些系统 UI 的高度导致布局偏差。稳妥的做法是用100%配合全屏元素的尺寸或者用window.innerHeight动态计算。6.4 全屏时的光标与交互全屏播放视频时通常希望鼠标不动几秒后自动隐藏光标。这个用 CSS 的cursor: none配合 JS 定时器就能实现。let cursorTimer; document.addEventListener(fullscreenchange, () { if (document.fullscreenElement) { const hideCursor () { document.body.style.cursor none; }; const showCursor () { document.body.style.cursor default; clearTimeout(cursorTimer); cursorTimer setTimeout(hideCursor, 3000); }; document.addEventListener(mousemove, showCursor); showCursor(); } else { document.body.style.cursor default; clearTimeout(cursorTimer); } });这段代码的逻辑是鼠标移动时显示光标并重置定时器3 秒不动就隐藏。退出全屏时恢复默认光标并清理定时器。注意清理否则退出全屏后光标可能还是隐藏的。7. 实战中那些文档不会告诉你的坑7.1 全屏请求被拒绝时控制台可能什么都不显示这是最让人抓狂的一点。在某些浏览器里全屏请求因为非用户手势被拒绝时Promise 不 rejectfullscreenerror也不触发控制台干干净净你完全不知道发生了什么。唯一的线索是document.fullscreenElement依然是 null。遇到这种情况我的排查思路是先确认调用是否在用户手势的同步执行栈里。如果不是那就是手势问题。如果是再检查元素是否在 DOM 里、是否可见、是否在 iframe 里且缺少 allowfullscreen。这几个是最常见的原因。7.2 全屏后按 ESC 退出你的状态可能没同步前面强调过要监听fullscreenchange但实际项目里还是经常有人忘。表现就是用户按 ESC 退出全屏页面上的按钮还显示“退出全屏”再点一下反而又进了全屏。这种 bug 在测试阶段很容易被忽略因为测试人员通常用页面上的按钮退出不会去按 ESC。我的建议是任何涉及全屏状态的 UI都必须以fullscreenchange事件为准来更新不要自己维护一个布尔变量。自己维护的变量迟早会和真实状态不一致。7.3 移动端的全屏和桌面端不是一回事移动端浏览器的全屏行为差异很大。iOS Safari 对非视频元素的全屏支持有限Android 上各家浏览器也不统一。而且移动端本身屏幕就小全屏的意义和桌面端不同。如果你的项目要覆盖移动端建议做能力检测不支持时降级为 CSS 模拟全屏固定定位 100vw/100vh。虽然体验差一点但至少不会报错。function isFullscreenSupported() { return !!(document.documentElement.requestFullscreen || document.documentElement.webkitRequestFullscreen || document.documentElement.mozRequestFullScreen || document.documentElement.msRequestFullscreen); }7.4 全屏和页面可见性 API 的配合有个场景用户全屏看视频然后切到别的标签页再切回来。这时候全屏状态可能还在但视频暂停了。你需要监听visibilitychange来处理。document.addEventListener(visibilitychange, () { if (document.hidden) { // 页面不可见暂停视频 } else { // 页面可见恢复 } });注意visibilitychange和fullscreenchange是独立的切标签页不一定退出全屏退出全屏也不一定切标签页。两个事件都要处理。7.5 全屏元素的样式继承问题全屏元素会继承它原来在 DOM 树里的样式但它的渲染上下文变了。比如原来依赖父元素的font-size、color等继承属性全屏后如果父元素不在全屏元素树里这些继承可能失效。我遇到过一个案例一个按钮的文字颜色依赖父容器的color全屏后父容器被隐藏按钮文字变成了默认黑色在深色背景上看不清。解决办法是给全屏元素显式设置所有关键样式不要依赖继承。7.6 全屏状态下的键盘事件全屏后键盘事件依然会触发但某些按键会被浏览器拦截。比如 ESC 键浏览器用它来退出全屏你的keydown监听可能收不到或者收到时全屏已经退出了。如果你需要在全屏下用 ESC 做别的事比如关闭弹窗要小心和浏览器默认行为的冲突。通常的做法是不要拦截 ESC让浏览器退出全屏你在fullscreenchange里做后续处理。8. 一个可直接复用的全屏组件实现把前面讲的东西串起来给一个完整的实现。这个组件包含进入/退出全屏、状态同步、错误处理、前缀兼容可以直接抄进项目。class FullscreenController { constructor(element, options {}) { this.element element; this.onChange options.onChange || (() {}); this.onError options.onError || (() {}); this._boundChange this._handleChange.bind(this); this._boundError this._handleError.bind(this); this._init(); } _init() { const events [ fullscreenchange, webkitfullscreenchange, mozfullscreenchange, MSFullscreenChange ]; const errorEvents [ fullscreenerror, webkitfullscreenerror, mozfullscreenerror, MSFullscreenError ]; events.forEach(evt document.addEventListener(evt, this._boundChange)); errorEvents.forEach(evt document.addEventListener(evt, this._boundError)); } _handleChange() { const isFullscreen !!this.getFullscreenElement(); this.onChange(isFullscreen, this.getFullscreenElement()); } _handleError(event) { this.onError(event); } getFullscreenElement() { return document.fullscreenElement || document.webkitFullscreenElement || document.mozFullScreenElement || document.msFullscreenElement || null; } isFullscreen() { return !!this.getFullscreenElement(); } async enter() { const el this.element; const fn el.requestFullscreen || el.webkitRequestFullscreen || el.mozRequestFullScreen || el.msRequestFullscreen; if (!fn) { throw new Error(当前浏览器不支持全屏 API); } try { const result fn.call(el); if (result typeof result.then function) { await result; } } catch (err) { this.onError(err); throw err; } } async exit() { const fn document.exitFullscreen || document.webkitExitFullscreen || document.mozCancelFullScreen || document.msExitFullscreen; if (!fn) { throw new Error(当前浏览器不支持退出全屏); } try { const result fn.call(document); if (result typeof result.then function) { await result; } } catch (err) { this.onError(err); throw err; } } async toggle() { if (this.isFullscreen()) { await this.exit(); } else { await this.enter(); } } destroy() { const events [ fullscreenchange, webkitfullscreenchange, mozfullscreenchange, MSFullscreenChange ]; const errorEvents [ fullscreenerror, webkitfullscreenerror, mozfullscreenerror, MSFullscreenError ]; events.forEach(evt document.removeEventListener(evt, this._boundChange)); errorEvents.forEach(evt document.removeEventListener(evt, this._boundError)); } }用法const player document.querySelector(#player); const fs new FullscreenController(player, { onChange(isFullscreen) { const btn document.querySelector(#fullscreen-btn); btn.textContent isFullscreen ? 退出全屏 : 进入全屏; }, onError(err) { console.error(全屏出错:, err); } }); document.querySelector(#fullscreen-btn).addEventListener(click, () { fs.toggle(); }); // 组件卸载时 // fs.destroy();这个实现里几个关键点enter和exit都做了 Promise 兼容老浏览器返回 undefined 时不会报错onChange回调同时给出布尔状态和全屏元素方便业务判断destroy负责清理事件监听避免内存泄漏。9. 关于全屏 API 的一些个人经验做了几个涉及全屏的项目之后我最大的体会是全屏功能本身不难难的是状态同步和边界处理。API 就那么几个方法但用户的操作路径是发散的——他们可能点按钮、按 ESC、按 F11、切标签页、锁屏、拔电源。你的代码要能应对所有这些情况靠的就是fullscreenchange这个唯一可靠的状态源。另一个经验是不要试图自己维护全屏状态。我早期写过用布尔变量记录是否全屏的代码结果各种不同步。后来改成每次需要判断时直接读document.fullscreenElement问题就少了很多。状态这种东西能读就别存。还有一点是关于降级的。全屏 API 的支持度现在已经很好了但总有一些环境不支持比如某些嵌入式浏览器、某些移动端 WebView。与其让功能直接报错不如检测一下不支持时用 CSS 模拟。用户可能分不清“真全屏”和“假全屏”但一定能分清“能用”和“报错”。最后说一个小的性能注意点fullscreenchange事件在快速切换全屏时可能触发多次如果你的回调里有重计算或者网络请求记得做防抖或者状态判断避免重复执行。我在一个项目里就因为没做这个快速点全屏按钮时发了多次统计请求后来加了个简单的状态判断才解决。
