企业官网建设流程全解析

1. 全屏 API 到底解决了什么问题

第一次接触全屏功能，很多人以为就是让页面“变大”。实际做过项目的人都知道，浏览器地址栏、标签页、系统任务栏这些东西占掉的垂直空间，在展示类场景里是致命的。一个在线设计工具，用户想沉浸式拖拽画布；一个视频播放页，用户想关掉所有干扰只看画面；一个数据大屏，需要把整个屏幕交给图表。这些需求背后都是同一个诉求：让某个元素独占显示区域，把浏览器和系统的界面元素暂时隐藏掉。

Fullscreen API 就是干这个的。它允许你用 JavaScript 把任意 DOM 元素（不只是 video，也不只是整个页面）切换到全屏状态，同时提供进入、退出、状态变化、错误处理这一整套事件机制。和早年那种按 F11 让整个浏览器全屏的方式不同，Fullscreen API 是元素级的——你可以只让一个 div 全屏，页面其他部分照常存在，只是被盖住了。

这个能力适合谁？前端开发者在做播放器、在线编辑器、演示工具、数据可视化大屏、游戏页面时都会用到。哪怕你只是做一个产品图册，想让用户点开大图后满屏查看，Fullscreen API 也是标准方案。它的兼容性在今天已经相当好，主流桌面浏览器和移动端浏览器基本都支持，只是各家前缀和细节行为有差异，这也是实际开发中最容易踩坑的地方。

我见过不少项目用 CSS 的position: fixed加z-index来“模拟全屏”，结果在移动端被地址栏和手势操作搞得一团糟。真正的 Fullscreen API 能拿到系统级的全屏状态，键盘的 Esc 键、移动端的手势返回都能被正确响应，这是模拟方案做不到的。所以只要场景对沉浸感有要求，优先考虑原生 API，别自己造轮子。

2. 核心概念与浏览器兼容现状

2.1 标准 API 与历史前缀

Fullscreen API 的标准化过程比较曲折，导致现在代码里经常要写一堆兼容分支。核心方法就两个：element.requestFullscreen()进入全屏，document.exitFullscreen()退出全屏。属性方面，document.fullscreenElement返回当前处于全屏的元素，document.fullscreenEnabled表示当前环境是否允许全屏。

历史前缀是绕不开的坎。早期 Chrome 用webkitRequestFullscreen，Firefox 用mozRequestFullScreen（注意 S 大写），IE 和旧 Edge 用msRequestFullscreen。虽然现在新版本基本都支持无前缀版本，但如果你的项目要兼容几年前的老设备，或者某些定制内核的浏览器，前缀分支还是得留着。我的做法是写一个统一的工具函数，把这些差异封装起来，业务代码只调用自己的方法。

function getFullscreenApi() { const doc = document; const el = doc.documentElement; return { request: el.requestFullscreen || el.webkitRequestFullscreen || el.mozRequestFullScreen || el.msRequestFullscreen, exit: doc.exitFullscreen || doc.webkitExitFullscreen || doc.mozCancelFullScreen || doc.msExitFullscreen, element: () => doc.fullscreenElement || doc.webkitFullscreenElement || doc.mozFullScreenElement || doc.msFullscreenElement, enabled: doc.fullscreenEnabled || doc.webkitFullscreenEnabled || doc.mozFullScreenEnabled || doc.msFullscreenEnabled }; }

这段代码看着啰嗦，但它是很多播放器库内部真实存在的逻辑。封装好之后，业务层就不用关心前缀了。

2.2 各浏览器行为差异对照

光有前缀还不够，不同浏览器在细节行为上也有区别，这些差异直接影响到用户体验。我整理了一张实际项目中遇到的对照表：

这张表里最需要记住的一条是：全屏必须由用户手势触发。所谓用户手势，指的是 click、touch、keydown 这类真实交互事件。你在setTimeout里调requestFullscreen，或者在页面加载时自动调用，浏览器会直接拒绝并抛出错误。这是为了防止恶意网站劫持用户屏幕，属于硬性安全策略，没有绕过的方法。

另一个容易忽略的点是：全屏状态下如果弹出alert、confirm或者打开新的浏览器对话框，全屏会自动退出。所以做全屏播放器时，别在全屏逻辑里混入原生弹窗，要用自定义的浮层组件。

3. 从零实现一个可复用的全屏控制器

3.1 基础进入与退出逻辑

先写最核心的进入和退出。这里的关键是返回值是 Promise，现代浏览器里requestFullscreen()返回一个 Promise，成功进入后 resolve，被拒绝则 reject。很多人不处理这个 Promise，结果用户点了按钮没反应，控制台一堆未捕获的错误，排查半天。

async function enterFullscreen(element) { const api = getFullscreenApi(); if (!api.enabled) { console.warn('当前环境不支持全屏'); return false; } try { await api.request.call(element); return true; } catch (err) { console.error('进入全屏失败:', err.message); return false; } } async function exitFullscreen() { const api = getFullscreenApi(); if (!api.element()) return true; try { await api.exit.call(document); return true; } catch (err) { console.error('退出全屏失败:', err.message); return false; } }

注意api.request.call(element)这里的this绑定。如果你把方法取出来单独调用，比如const fn = element.requestFullscreen; fn();，this就丢了，会报错。所以要么直接element.requestFullscreen()，要么用call显式绑定。这个坑我在早期项目里踩过，当时封装得太“优雅”，反而把上下文弄丢了。

3.2 状态监听与事件绑定

全屏状态可能被用户用 Esc 键、系统手势、或者浏览器自身行为改变，所以你不能只依赖自己代码里的进入退出，必须监听状态变化事件。标准事件是fullscreenchange，前缀版本对应webkitfullscreenchange、mozfullscreenchange、MSFullscreenChange。

function bindFullscreenChange(callback) { const events = [ 'fullscreenchange', 'webkitfullscreenchange', 'mozfullscreenchange', 'MSFullscreenChange' ]; const handler = () => { const api = getFullscreenApi(); const el = api.element(); callback({ isFullscreen: !!el, element: el }); }; events.forEach(evt => document.addEventListener(evt, handler)); return () => { events.forEach(evt => document.removeEventListener(evt, handler)); }; }

这个回调里拿到isFullscreen和当前全屏元素，你就可以同步更新按钮图标、切换样式、暂停或恢复某些动画。实际项目里我建议把全屏状态存到一个统一的状态管理里，而不是散落在各个组件内部，否则多个组件同时监听容易状态不一致。

还有一个fullscreenerror事件，进入全屏失败时触发。虽然 Promise 的 catch 也能捕获，但事件监听能覆盖到一些异步场景，两个都加上更稳妥。

3.3 封装成即插即用的类

把上面的逻辑整合成一个类，业务代码用起来就清爽了。这个类的设计思路是：传入目标元素和可选的按钮元素，自动处理点击、状态同步、事件清理。

class FullscreenController { constructor(target, options = {}) { this.target = typeof target === 'string' ? document.querySelector(target) : target; this.onChange = options.onChange || (() => {}); this.unbind = null; this._init(); } _init() { this.unbind = bindFullscreenChange(this.onChange); } async toggle() { const api = getFullscreenApi(); if (api.element()) { return exitFullscreen(); } return enterFullscreen(this.target); } isFullscreen() { return !!getFullscreenApi().element(); } destroy() { if (this.unbind) this.unbind(); } }

用的时候：

const controller = new FullscreenController('#player', { onChange: ({ isFullscreen }) => { document.querySelector('#btn').textContent = isFullscreen ? '退出全屏' : '进入全屏'; } }); document.querySelector('#btn').addEventListener('click', () => { controller.toggle(); });

这个封装的好处是把兼容性、事件绑定、状态查询都收在一处，业务层只关心“切换”这一个动作。组件卸载时记得调destroy()，否则事件监听会泄漏，在单页应用里反复进出页面会积累一堆无效监听。

4. 实战场景中的细节处理与避坑

4.1 移动端的特殊表现

移动端是全屏 API 最容易出问题的地方。首先是 iOS Safari，它对元素级全屏的支持一直比较保守，早期只允许 video 元素全屏，普通 div 调用requestFullscreen可能无效。较新版本有所改善，但如果你要兼容老设备，得准备降级方案——比如用 CSS 把元素撑满视口，配合position: fixed和overflow: hidden来模拟。

其次是软键盘。全屏状态下如果元素里有输入框，用户点击后软键盘弹出，视口高度会变化，全屏布局可能被挤压变形。我的处理办法是在全屏容器里用flex布局，把可滚动区域单独抽出来，键盘弹出时只影响滚动区，不影响整体结构。另外监听resize事件做适配，别用固定的像素高度。

还有一个细节：移动端进入全屏后，系统的手势返回（比如从边缘滑动）可能会直接退出全屏甚至退出页面。这个行为无法完全拦截，但你可以通过history.pushState在进入全屏时压入一条历史记录，用户手势返回时先触发popstate，你在回调里决定是退出全屏还是放行。这个技巧在需要“返回键先退全屏”的场景里很有用。

4.2 全屏与页面滚动的冲突

进入全屏后，如果全屏元素本身不是body或根元素，页面其他部分虽然被盖住，但滚动条可能还在，用户滚动滚轮时底层页面会动，体验很怪。解决办法是在进入全屏时给body加一个类，设置overflow: hidden，退出时移除。

body.is-fullscreen-active { overflow: hidden; }

但要注意，如果全屏元素内部需要滚动，这个overflow: hidden不能加在全屏元素自身上，否则内部内容也滚不动了。正确的做法是加在body或全屏元素的父级上，全屏元素内部单独设置overflow: auto。

另一个坑是滚动位置丢失。有些浏览器在进入全屏时会重置滚动位置，退出后页面跳回顶部。我一般的处理是在进入全屏前记录scrollTop，退出后恢复。虽然多几行代码，但能避免用户“我明明看到一半，怎么退出来就回到顶部了”的困惑。

4.3 全屏状态下的样式适配

全屏后元素的尺寸变了，原本基于视口单位的样式可能需要调整。比如你用100vh做高度，全屏后vh的基准变了，布局可能错位。更稳妥的是在全屏元素上用width: 100%; height: 100%，让它跟随父级，而不是依赖视口单位。

还有一点：全屏时浏览器默认会给元素加一个黑色背景。如果你希望全屏区域是白色或其他颜色，需要显式设置background。这个默认样式在不同浏览器里表现不完全一致，显式声明能保证一致性。

:fullscreen { background: #000; } :-webkit-full-screen { background: #000; } :-moz-full-screen { background: #000; }

伪类也要写前缀版本，否则样式不生效。这是很多人调半天调不出来的原因——逻辑没问题，就是样式没匹配上。

4.4 常见问题速查表

实际开发中遇到的问题五花八门，我把高频的整理成一张表，方便对照排查：

这张表里的每一条我都在项目里真实遇到过。尤其是 iframe 那条，如果你的页面嵌在 iframe 里，父级 iframe 必须设置allow="fullscreen"，否则子页面调用全屏会被拒绝。这个属性很容易漏，排查时又不容易想到，因为控制台报错信息往往很模糊。

5. 进阶用法与性能考量

5.1 在 iframe 中正确启用全屏

iframe 场景在后台管理系统里很常见，比如主框架嵌了一个子应用，子应用里要做全屏预览。这时候光在子应用里写代码不够，父级 iframe 标签必须显式授权：

<iframe src="child.html" allow="fullscreen" allowfullscreen> </iframe>

allow="fullscreen"是较新的权限策略写法，allowfullscreen是旧版属性，两个都写上兼容性最好。如果父级没授权，子应用调用requestFullscreen会直接 reject，错误信息可能是 “Disallowed by permissions policy”，看到这个就知道是 iframe 权限问题。

另外，跨域 iframe 里全屏的元素，父页面无法直接访问，但fullscreenchange事件在各自文档内还是能监听的。所以子应用自己管理自己的全屏状态即可，父页面不需要干预。

5.2 全屏与画中画、媒体播放的配合

做视频播放器时，全屏和画中画（Picture-in-Picture）是两个相关但独立的能力。用户可能先全屏看，然后切到画中画，这时候全屏状态会自动退出。你需要监听画中画的进入退出事件，同步更新 UI 状态，避免按钮显示错乱。

还有一个细节：视频元素全屏时，浏览器可能会接管控制条。如果你用的是自定义控制条，全屏后要确保控制条仍然可见且可操作。有些浏览器在全屏时会隐藏自定义控件，需要设置controlsList或者用::-webkit-media-controls相关伪元素调整。这块各浏览器差异较大，建议全屏后实测一遍。

5.3 性能与内存注意事项

全屏本身对性能影响不大，但全屏往往伴随着渲染压力增加——因为可视区域变大了，原本被裁剪掉的部分现在要渲染。如果你的全屏元素里有大量 DOM 或复杂动画，进入全屏瞬间可能卡顿。我的做法是在进入全屏前先做一次布局优化，比如把不可见区域用content-visibility: auto标记，让浏览器跳过渲染。

事件监听方面，前面提到的bindFullscreenChange会绑定多个事件名，记得在组件销毁时全部解绑。单页应用里如果反复创建销毁全屏控制器而不清理，监听器会越积越多，最终导致状态回调被触发多次，出现“点一次按钮切换了两次”的诡异现象。这个 bug 我排查过一回，最后发现就是监听器没清理干净。

6. 我踩过的坑与实操心得

说几个文档里不会写、但实际开发中一定会遇到的点。

第一个是全屏按钮的图标切换时机。不要在自己调用requestFullscreen成功后立刻切换图标，因为用户可能用 Esc 退出，这时候你的代码没感知。正确做法是只在fullscreenchange回调里更新 UI，把“调用”和“状态同步”彻底分开。这样无论用户怎么进出全屏，UI 永远和真实状态一致。

第二个是全屏元素的层级问题。如果全屏元素内部有position: fixed的子元素，全屏后这些子元素的定位基准会变成全屏元素，而不是视口。这可能导致原本固定在右下角的按钮跑到奇怪的位置。解决办法是把这些固定定位的子元素移到全屏元素外面，或者在全屏时改用absolute定位。

第三个是测试环境的选择。全屏行为在浏览器开发者工具的移动模拟模式下和真机差异很大，尤其是 iOS。我建议全屏相关的功能一定要在真机上测，模拟器只能验证逻辑，验证不了手势和键盘行为。

第四个是降级方案要提前想好。虽然现在支持度不错，但总有一些环境（比如某些嵌入式浏览器、旧版系统）不支持。我的做法是检测fullscreenEnabled，不支持时把全屏按钮隐藏或者替换成“放大查看”的浮层方案，而不是让用户点了没反应。

最后分享一个实用技巧：如果你想让全屏切换有过渡动画，别直接对全屏元素做transition，因为全屏切换是浏览器层面的操作，元素尺寸变化是瞬时的。想要动画效果，可以在进入全屏前先做一个放大的视觉过渡，进入后再移除，用视觉上的连贯感掩盖技术上的突变。这个思路在多个项目里帮我做出了比较顺滑的体验。

全屏 API 本身不复杂，难的是把兼容性、状态同步、移动端适配、iframe 权限这些边角都处理干净。把上面这套控制器封装好，后续项目直接复用，能省下大量调试时间。