1. 项目概述一个横屏游戏开发者的“心头刺”如果你用 Cocos Creator 开发过 H5 游戏并且目标平台包含 iOS 的 Safari 浏览器那你一定对下面这个场景不陌生你精心设计的横屏游戏在用户将手机旋转到横屏模式后屏幕顶部那个该死的 Safari 地址栏以及底部的工具栏就像一块顽固的膏药死死地贴在画面上方生生吃掉了一部分宝贵的游戏可视区域。更让人恼火的是它时而出现时而隐藏行为飘忽不定直接破坏了游戏的沉浸感。这个问题几乎成了每一个面向移动端浏览器的 H5 游戏开发者必踩的“大坑”。我最初遇到这个问题时也以为只是个简单的“全屏”API调用。但实际深入后才发现这背后是 iOS Safari 为了平衡用户体验和安全而设计的一套复杂逻辑远不是一句requestFullscreen就能解决的。特别是对于像 Cocos Creator 这样以 Canvas 作为主要渲染载体、且通常设置为固定尺寸如 1920x1080的横屏游戏我们面对的是一个“静态”画布与一个“动态”的浏览器视口之间的博弈。简单来说iOS Safari 自动隐藏地址栏即进入“全屏”模式的核心触发机制是“页面滚动”。如果页面内容的高度超过了视口viewport的高度用户一个轻微的上滑动作就能让地址栏优雅地滑走。但我们的横屏游戏呢为了适配各种屏幕我们往往将 Canvas 的尺寸通过 CSS 设置为100%宽高或者通过缩放来填满屏幕。在横屏状态下游戏画布的高度通常就等于视口的高度没有“溢出”没有滚动条。Safari 一看“哟这页面高度正好嘛用户没地方滚那地址栏我就留着吧。”于是问题就产生了。所以这个“避坑指南”要解决的远不止一个技术点。它是一场针对特定浏览器行为的前端“外科手术”涉及对viewportmeta 标签的精准控制、对 CSS 样式的巧妙运用、对 JavaScript 事件如旋转、触摸的捕获与响应以及对 Cocos Creator 引擎本身打包配置的深度调整。目标只有一个在 iOS Safari 横屏状态下稳定、可靠地隐藏地址栏和底部工具栏为玩家提供一个纯净、全屏的游戏画面同时确保游戏本身的渲染与交互不受任何影响。2. 核心问题与Safari行为逻辑深度解析要解决问题必须先透彻理解“敌人”的行为模式。我们不能与浏览器的设计哲学硬碰硬而是要巧妙地引导它让它按照我们期望的方式工作。2.1 Safari 地址栏的“自动隐藏”与“手动全屏”首先必须分清两个概念它们常常被混淆自动隐藏Automatic Hiding这是 Safari 在移动端的默认体验。当页面可滚动时用户向下滑动页面地址栏会向上收起向上滑动到顶部地址栏又会出现。这个行为是浏览器内置的目的是在提供页面信息地址和最大化内容区域之间取得平衡。我们的核心目标就是要在横屏下稳定触发这种“自动隐藏”并使其保持隐藏状态。手动全屏 APIFullscreen API即通过 JavaScript 调用document.documentElement.requestFullscreen()。这个 API 在桌面端浏览器上可以隐藏所有浏览器UI但在 iOS Safari 上受到严格限制。对于普通的网页内容Safari 根本不支持此 API。它只对特定的视频元素或某些特殊的 Web App 模式如“添加到主屏幕”后以全屏模式打开提供有限的全屏支持。所以想用标准 Fullscreen API 来解决我们的问题此路不通。2.2 横屏下地址栏不隐藏的根本原因关键在于“可滚动区域”scrollable area。Safari 判断是否隐藏地址栏的简化逻辑如下条件页面内容高度 视口高度即存在垂直滚动可能性。触发用户发起一个垂直方向的触摸滑动即使滑动距离很小。结果地址栏隐藏。对于竖屏页面这很容易满足。但对于一个设计为横屏例如 16:9的游戏我们通常设置meta nameviewport contentwidthdevice-width, initial-scale1.0。竖屏时device-width是屏幕的短边如 390px视口较窄页面内容高度容易超出。当用户旋转到横屏时device-width变成了屏幕的长边如 844px。如果我们游戏的画布是 1920x1080经过缩放适配后其渲染高度很可能恰好等于横屏视口的高度因为我们要铺满屏幕。此时页面内容高度 视口高度垂直滚动量为0。Safari 检测不到可滚动区域因此认为“无需隐藏地址栏”。即使用户尝试滑动因为没有滚动发生地址栏也纹丝不动。2.3 另一种“坑”动态旋转时的布局抖动即使你通过一些方法让地址栏在横屏初始状态就隐藏了另一个棘手问题会出现当用户从竖屏旋转到横屏时Safari 的视口尺寸计算会发生突变。地址栏的隐藏/显示会引起可用窗口高度window.innerHeight的变化。如果 Cocos Creator 的 Canvas 缩放是依赖window.innerHeight或window.outerHeight计算的那么旋转过程中画布可能会经历“缩放 - 突然变化 - 再缩放”的过程导致游戏画面短暂抖动或缩放比例错误体验极差。因此一个完整的解决方案必须同时处理初始化隐藏确保页面在横屏加载时地址栏就是隐藏的。旋转稳定性在设备方向变化时保持布局稳定避免抖动。交互保持在地址栏隐藏后确保用户的触摸事件能正确传递给游戏不会误触发浏览器的下拉刷新等原生行为。3. 解决方案一Meta Viewport 与 CSS 的魔法这是最基础、也是最重要的一步。我们需要通过 HTML 的 meta 标签和 CSS 来“欺骗” Safari让它认为我们的页面有足够的可滚动空间。3.1 关键 Meta Viewport 配置不要使用 Cocos Creator 构建后默认生成的简单 viewport。我们需要一个更强大的配置。在index.html的head部分使用如下配置meta nameviewport contentwidthdevice-width, initial-scale1.0, maximum-scale1.0, minimum-scale1.0, user-scalableno, viewport-fitcover让我们拆解每个参数的作用widthdevice-width标准设置让视口宽度等于设备宽度。initial-scale1.0, maximum-scale1.0, minimum-scale1.0这是关键将缩放比例锁定为1.0并且禁止用户手动缩放。这能有效防止在旋转或滑动时Safari 自动调整缩放比例从而引发不可预料的布局计算和地址栏行为。user-scalableno进一步禁用用户缩放与上面的缩放锁定配合。viewport-fitcover至关重要这个属性告诉浏览器让视口覆盖整个屏幕区域包括刘海屏、圆角等“安全区域”之外的部分。它为后续使用 CSSenv(safe-area-inset-*)处理异形屏奠定了基础同时也更符合全屏游戏的诉求。注意在 iOS 15 及之后的版本中单纯使用user-scalableno可能被 Safari 忽略以保障可访问性。但结合maximum-scale1.0, minimum-scale1.0双重锁定在实践中最有效。3.2 创建“可滚动”的 CSS 结构既然 Safari 需要可滚动区域我们就给它一个。但我们要确保这个滚动不会影响游戏主画布的视觉表现。思路将整个页面 body 设置为一个可滚动的、高度略大于 100% 的容器而将游戏 Canvas 绝对定位并固定在顶部。这样Safari 能检测到滚动但用户看到的始终是固定的全屏画布。具体 CSS 方案html, body { margin: 0; padding: 0; /* 关键让 html 和 body 撑满并允许滚动 */ width: 100%; height: 100%; overflow: hidden; /* 先隐藏我们用内部容器制造滚动 */ position: relative; background-color: #000; /* 设置游戏背景色避免滚动时露白 */ } /* 创建一个用于“欺骗”滚动的包装器 */ #scroll-wrapper { position: absolute; top: 0; left: 0; width: 100%; /* 高度设为 101% 或更多确保产生垂直滚动空间 */ height: calc(100% 1px); overflow-y: scroll; /* 启用垂直滚动 */ -webkit-overflow-scrolling: touch; /* 启用 iOS 弹性滚动体验更佳 */ /* 隐藏滚动条 */ scrollbar-width: none; /* Firefox */ -ms-overflow-style: none; /* IE and Edge */ } #scroll-wrapper::-webkit-scrollbar { display: none; /* Chrome, Safari, Opera*/ } /* Cocos Creator 的 Canvas 容器 */ #GameDiv { /* Canvas 容器固定定位永远覆盖视口 */ position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; /* 处理刘海屏确保内容在安全区域内 */ padding-top: env(safe-area-inset-top); padding-left: env(safe-area-inset-left); padding-right: env(safe-area-inset-right); padding-bottom: env(safe-area-inset-bottom); box-sizing: border-box; /* 禁止任何可能干扰游戏的事件 */ touch-action: none; pointer-events: auto; } /* Canvas 元素本身 */ #gameCanvas { display: block; width: 100%; height: 100%; }对应的 HTML 结构需要调整body div idscroll-wrapper/div !-- 这个 div 是空的仅用于滚动 -- div idGameDiv canvas idgameCanvas/canvas /div script srcmain.js/script /body原理#scroll-wrapper的高度是100% 1px它相对于body产生了 1 像素的溢出滚动。Safari 检测到了这个可滚动容器。当页面加载或旋转时我们可以用极少的 JavaScript 代码让这个包装器向下滚动 1 个像素scroll-wrapper.scrollTop 1。这个微小的滚动动作就足以触发 Safari 的“用户进行了滚动”的判断从而自动隐藏地址栏。而#GameDiv是fixed定位的完全不受这个滚动影响玩家看到的始终是完美的全屏游戏画面。实操心得这个1px的滚动量是经验值。有时可能需要稍微大一点比如10px以确保在所有机型上都能可靠触发。但切忌滚动太多否则在竖屏模式下可能会看到明显的背景闪动。4. 解决方案二JavaScript 的事件驱动与控制CSS 布局创造了条件JavaScript 则负责在正确的时机执行触发动作并处理设备旋转等动态事件。4.1 页面加载与初始隐藏我们需要在页面加载后立即触发一次“滚动”来隐藏地址栏。但要注意执行时机。(function() { // 等待页面基本元素加载完毕 document.addEventListener(DOMContentLoaded, function() { var scrollWrapper document.getElementById(scroll-wrapper); if (scrollWrapper) { // 使用 setTimeout 确保布局已稳定 setTimeout(function() { // 关键滚动1像素以触发地址栏隐藏 scrollWrapper.scrollTop 1; // 立即将滚动位置重置回顶部确保视觉上无偏移 // 注意有的方案建议不重置让那1px一直滚着。但重置可以避免极少数情况下的副作用。 // 可以尝试两种方式选择更稳定的一种。 // scrollWrapper.scrollTop 0; // 可选 // 强制触发一次重排确保 Safari “注意到”滚动 void scrollWrapper.offsetHeight; }, 100); // 100ms 延迟是一个比较安全的经验值 } }); })();4.2 处理设备旋转Orientation Change设备旋转是地址栏问题复现的高发区。我们必须监听这个事件并在旋转完成后重新触发隐藏逻辑。// 定义一个处理全屏的函数 function ensureFullscreen() { var scrollWrapper document.getElementById(scroll-wrapper); if (!scrollWrapper) return; // 在旋转后Safari 可能有一个短暂的布局计算期 // 太早执行可能无效需要稍作延迟 setTimeout(function() { // 再次滚动触发隐藏 scrollWrapper.scrollTop 1; // 可选重置 scrollTop 0; void scrollWrapper.offsetHeight; // **重要修复旋转抖动** // 旋转后window.innerHeight 会变化。如果Cocos引擎据此调整Canvas会导致画面缩放。 // 我们需要在旋转完成后获取稳定的窗口尺寸并通知Cocos引擎。 if (window.cc window.cc.view) { // 假设Cocos Creator的适配策略是基于设计分辨率和屏幕宽高比 // 这里需要根据你项目具体的适配方案来调整 // 例如强制重置引擎的视图尺寸 setTimeout(function() { cc.view.setCanvasSize(window.innerWidth, window.innerHeight); // 或者调用你的游戏分辨率适配函数 // adjustCanvasSize(); }, 200); // 比触发滚动的延迟更长确保布局完全稳定 } }, 300); // 旋转后300ms执行这是一个经过大量测试的相对可靠值 } // 监听旋转事件 var orientationChangeTimeout; window.addEventListener(orientationchange, function() { // 清除可能的旧定时器 clearTimeout(orientationChangeTimeout); // 设置一个新的定时器在旋转事件结束后执行 orientationChangeTimeout setTimeout(ensureFullscreen, 500); }); // 同时监听 resize 事件作为备用某些安卓机或特殊情况下 window.addEventListener(resize, function() { clearTimeout(orientationChangeTimeout); orientationChangeTimeout setTimeout(ensureFullscreen, 500); });4.3 处理触摸事件与防止下拉刷新在隐藏地址栏后页面顶部区域对应原地址栏位置的触摸事件需要妥善处理防止触发 Safari 的下拉刷新在 iOS 13 的某些模式下会出现。// 在 GameDiv 上禁止默认的触摸行为 document.getElementById(GameDiv).addEventListener(touchmove, function(e) { // 如果游戏需要全局捕获触摸事件可以在这里阻止默认行为 // 但这可能会影响游戏内部的滚动组件需要谨慎 // e.preventDefault(); }, { passive: false }); // 必须设置 passive: false 才能 preventDefault // 更精准的做法只在页面顶部边缘下拉时阻止防止刷新 var startY 0; document.getElementById(GameDiv).addEventListener(touchstart, function(e) { startY e.touches[0].pageY; }, { passive: true }); document.getElementById(GameDiv).addEventListener(touchmove, function(e) { var currentY e.touches[0].pageY; // 如果当前滚动位置在顶部且是向下拉 if (window.pageYOffset 0 currentY startY) { // 轻微下拉就阻止防止触发刷新 if (currentY - startY 10) { e.preventDefault(); } } // 如果游戏有自己的垂直拖动逻辑这里的判断需要更复杂 }, { passive: false });5. Cocos Creator 引擎侧的适配与配置前端的布局和 JS 脚本是“外功”Cocos Creator 项目本身的配置则是“内功”必须内外兼修。5.1 构建发布设置设计分辨率在项目设置 - 项目数据中设置一个横屏的设计分辨率例如1920 x 1080。这是你游戏世界的逻辑尺寸。适配策略Fit Height / Fit Width这是关键中的关键。在Canvas组件的适配模式中选择FIXED_HEIGHT固定高度通常是对横屏游戏最友好的。原理FIXED_HEIGHT会保证游戏画面的高度始终等于设计分辨率的高度1080px宽度则按屏幕比例缩放。这样无论在什么屏幕比例下游戏垂直方向的内容都是完整的水平方向可能裁剪或留黑边。更重要的是它保证了游戏渲染内容的高度是固定的逻辑值不会因为window.innerHeight的瞬时变化地址栏隐藏导致的而产生剧烈缩放从而有效减少旋转抖动。对比SHOW_ALL会保证内容全部显示但可能留黑边FIXED_WIDTH则可能导致在很高或很矮的屏幕上垂直方向被过度裁剪。FIXED_HEIGHT在稳定性和一致性上通常最优。构建模板构建 Web Mobile 时可以自定义index.html模板。将我们前面提到的viewportmeta 标签和 CSS 结构直接写入模板中这样就不需要每次构建后手动修改index.html了。模板文件位于 Cocos Creator 安装目录的resources/templates/web-mobile下可以复制出来修改后在构建面板的“自定义构建模板”中指定。5.2 游戏启动脚本中的增强处理在 Cocos Creator 的游戏启动脚本通常是main.js或application.js中我们需要将前面提到的 JavaScript 控制逻辑集成进去。确保在引擎初始化cc.game.run之前或之后执行我们的ensureFullscreen函数。一个常见的做法是修改 Cocos Creator 生成的main.js在window.boot函数内部cc.game.run之前添加我们的初始化代码window.boot function () { // 1. 我们的全屏初始化代码 function initFullscreenWorkaround() { // ... 此处包含前面章节的 ensureFullscreen 函数、事件监听等所有JS代码 ... // 在DOMContentLoaded或适当时机调用 ensureFullscreen if (document.readyState complete) { ensureFullscreen(); } else { window.addEventListener(load, ensureFullscreen); } } initFullscreenWorkaround(); // 2. 原有的Cocos配置 var settings window._CCSettings; // ... 其他原有代码 ... // 3. 启动引擎 onStart function () { cc.loader.downloader._subpackages settings.subpackages; cc.game.run(settings, onStart); }; // ... 后续代码 ... };5.3 处理安全区域Safe Area对于 iPhone X 及以后的刘海屏、药丸屏设备在强制全屏后需要确保游戏的重要 UI 元素如按钮、血量条不被刘海或圆角遮挡。这需要用到 CSS 的env(safe-area-inset-*)变量。我们在前面的 CSS 中已经为#GameDiv添加了padding。但 Cocos Creator 渲染的 Canvas 本身可能不知道这些 padding。我们需要将安全区域信息传递给游戏逻辑。方法在 JavaScript 中获取安全区域插入值并将其作为参数传递给 Cocos 引擎或者在游戏内设置一个“安全区”节点。// 在 initFullscreenWorkaround 函数中 function updateSafeArea() { const div document.getElementById(GameDiv); // 获取计算后的安全区域值 const style window.getComputedStyle(div); const top parseInt(style.paddingTop) || 0; const bottom parseInt(style.paddingBottom) || 0; const left parseInt(style.paddingLeft) || 0; const right parseInt(style.paddingRight) || 0; // 将这些值传递给 Cocos 游戏世界 if (window.cc window.cc.sys) { // 可以存放到一个全局对象中 window._safeAreaInsets { top, bottom, left, right }; // 或者通过发射事件通知游戏场景 if (cc.director cc.director.getScene()) { cc.systemEvent.emit(safe-area-changed, window._safeAreaInsets); } } } // 在 ensureFullscreen 函数中调用 updateSafeArea // 同时在 orientationchange 事件后也需要调用在游戏场景中监听这个事件然后调整你的 UI 根节点的位置或边距确保所有关键 UI 元素都位于top到bottomleft到right的安全区域内。6. 进阶技巧、测试与疑难排查即使实现了上述所有步骤在不同机型、不同 iOS 版本上仍然可能遇到一些边界情况。这里分享一些进阶技巧和排查方法。6.1 针对 iOS 15 的特殊处理从 iOS 15 开始Safari 的地址栏 UI 和行为有了一些变化。有时地址栏会以更紧凑的形式出现隐藏逻辑也更“固执”。除了之前提到的强力 viewport 设置还可以尝试在scroll-wrapper的滚动事件中持续干预document.getElementById(scroll-wrapper).addEventListener(scroll, function(e) { // 如果地址栏又出现了表现为 scrollTop 被重置为0就再次把它滚下去 if (this.scrollTop 0) { this.scrollTop 1; } });使用scrollTo代替直接赋值scrollTop有些开发者反馈element.scrollTo(0, 1)比element.scrollTop 1更可靠。6.2 真机调试与问题排查清单在电脑模拟器上很难完全复现 Safari 的行为真机调试是必须的。如何调试将构建后的游戏部署到一台 HTTPS 服务器上iOS Safari 对许多 API 要求 HTTPS。在 iPhone 的 Safari 中打开游戏页面。用 USB 连接 iPhone 到 Mac。在 Mac 的 Safari 浏览器中打开“开发”菜单选择你的 iPhone 设备然后选择正在运行的网页。即可打开 Safari 开发者工具进行断点、查看元素、日志输出等操作。排查清单地址栏完全不隐藏检查viewportmeta 标签是否正确设置特别是缩放是否被锁定。检查#scroll-wrapper的高度是否确实大于其父容器并且overflow-y是scroll或auto。检查 JavaScript 中的scrollTop赋值是否成功执行在控制台输出scrollWrapper.scrollTop查看。旋转时画面剧烈抖动/闪烁这通常是 Cocos Canvas 在旋转过程中被多次重设尺寸导致的。确保你的orientationchange处理函数中有足够的延迟300ms并且只调用一次引擎的尺寸调整函数。使用FIXED_HEIGHT适配策略能极大缓解此问题。游戏触摸事件失灵检查是否为#GameDiv或#gameCanvas添加了touch-action: none或pointer-events: none等样式或者是否在touchmove事件中错误地调用了e.preventDefault()阻止了事件冒泡。确保游戏需要的触摸事件能正常传递到 Cocos 的输入系统。底部工具栏导航栏不隐藏底部工具栏的隐藏逻辑与地址栏类似但有时更顽固。确保你的页面内容在垂直方向上有足够的“可滚动”空间。有时需要将#scroll-wrapper的高度设得更大如height: calc(100% 100px)并初始滚动相应的像素scrollTop 60。6.3 备选方案Web App 全屏模式添加到主屏幕如果上述所有 Hack 方法在你目标用户的 iOS 版本上仍然不稳定还有一个“终极”方案引导用户将你的游戏**“添加到主屏幕”**。当用户通过主屏幕图标启动网页时Safari 会以一种特殊的“无浏览器UI”模式Standalone Mode运行。在这个模式下地址栏和底部工具栏默认就是隐藏的体验接近原生 App。实现方法在index.html的head中添加 Web App Capable 的 meta 标签meta nameapple-mobile-web-app-capable contentyes meta nameapple-mobile-web-app-status-bar-style contentblack-translucent !-- 或 black --提供合适的图标apple-touch-icon。在游戏内通过 UI 文字或弹窗友好地提示用户“为获得最佳体验请点击分享按钮选择‘添加到主屏幕’”。这个方案的缺点是依赖用户操作无法在普通浏览器访问时自动生效。但对于追求极致体验的核心用户是一个非常好的补充方案。7. 完整代码整合与最佳实践建议将上述所有碎片整合成一个可用的方案需要一定的工程化思维。以下是一个简化的整合思路和最佳实践建议。项目结构建议自定义构建模板修改 Cocos Creator 的 Web Mobile 构建模板将优化后的index.html包含 viewport 和基础 CSS 结构固定下来。独立的全屏工具脚本创建一个单独的 JavaScript 文件例如fullscreen-helper.js包含所有的事件监听、滚动控制、安全区计算逻辑。这个脚本应该尽量轻量与游戏业务逻辑解耦。在 main.js 中引入在 Cocos Creator 的启动入口main.js中最早可能的地方引入并执行fullscreen-helper.js的初始化函数。游戏内的安全区适配在游戏启动场景中监听安全区域变化事件并调整 UI 布局。可以将安全区信息保存到全局管理器供所有 UI 模块查询。最佳实践总结优先使用 CSS 微小滚动 Hack这是目前兼容性最广、相对最稳定的方案。锁定 Viewport 缩放maximum-scale1.0, minimum-scale1.0是稳定性的基石。采用 FIXED_HEIGHT 适配在 Cocos Creator 中这能最大程度减少旋转抖动。延迟执行是关键在load、orientationchange事件后使用setTimeout给予浏览器足够的布局计算时间再执行滚动触发。真机、真机、真机重要的事情说三遍必须在不同型号的 iOS 设备上进行测试。提供降级体验如果你的游戏 UI 在地址栏显示时会被遮挡考虑设计一个动态的 UI 布局当检测到地址栏未隐藏时自动将关键 UI 元素下移虽然不完美但比被挡住要好。可以通过定期检查window.innerHeight与window.outerHeight或screen.height的差值来推测地址栏是否可见。解决 iOS Safari 横屏全屏问题没有一劳永逸的银弹它更像是一场与特定浏览器行为的持续“磨合”。上面提供的方案融合了社区众多开发者的智慧在大多数情况下能取得很好的效果。但技术总是在变化iOS 和 Safari 也在不断更新。最根本的是理解其底层逻辑——利用可滚动区域触发原生隐藏行为。只要抓住这个核心无论浏览器如何变化你都能找到相应的应对策略。在实际项目中我通常会准备一个“全屏兼容性测试页”快速验证新想法在不同设备上的效果这比在完整游戏项目中调试要高效得多。希望这份详细的指南能帮你彻底填上这个“坑”让玩家的第一眼体验再无瑕疵。