去年接了個(gè)把 Unity 項(xiàng)目搬進(jìn)瀏覽器的活美術(shù)和策劃直接在網(wǎng)頁(yè)上驗(yàn)收第一句話就是怎么點(diǎn)了全屏沒(méi)反應(yīng)。當(dāng)時(shí)我以為加個(gè)按鈕調(diào)一下瀏覽器的全屏接口就完事結(jié)果一頭撞進(jìn)坑里按鈕點(diǎn)了沒(méi)反應(yīng)、全屏之后畫面糊成一片、按 Esc 退出來(lái) UI 還掛著全屏中的狀態(tài)、嵌在 iframe 里干脆整套接口都摸不到。前前后后折騰了兩三天才把 UnityWebGl 網(wǎng)頁(yè)全屏顯示這件事從能點(diǎn)做到能用再到敢交付。這篇東西就是把那幾天的過(guò)程攤開(kāi)講。全屏在 Unity WebGL 里從來(lái)不是調(diào)一個(gè) API的問(wèn)題它橫跨三層瀏覽器的視口控制、canvas 的繪制緩沖區(qū)、Unity 內(nèi)部的相機(jī)與 UI 適配。任何一層沒(méi)對(duì)齊表現(xiàn)出來(lái)都是全屏壞了但壞的地方完全不一樣。下面這套內(nèi)容適合三類人看剛把項(xiàng)目導(dǎo)出成 WebGL、被全屏按鈕折磨過(guò)的開(kāi)發(fā)者要交付給第三方嵌入、被 iframe 卡住的同學(xué)以及畫面全屏后糊掉、變形、鼠標(biāo)點(diǎn)不準(zhǔn)找不到原因的人。代碼可以直接抄思路可以直接套。1. 先把全屏拆成三層不然后面全是返工1.1 瀏覽器視口層全屏接口到底給了你什么瀏覽器提供的全屏能力本質(zhì)上是讓某一個(gè) DOM 元素脫離頁(yè)面布局獨(dú)占整個(gè)屏幕。它的調(diào)用入口是元素上的requestFullscreen()退出入口在document上叫exitFullscreen()。這兩個(gè)動(dòng)作都有一個(gè)硬前提必須由用戶的真實(shí)交互觸發(fā)。你在定時(shí)器里調(diào)、在數(shù)據(jù)加載完成后的回調(diào)里調(diào)瀏覽器一律拒絕而且拒絕方式很安靜多數(shù)情況下只在控制臺(tái)留一條警告。判斷當(dāng)前是否處于全屏不看按鈕狀態(tài)看document.fullscreenElement——它有值就說(shuō)明有元素正在獨(dú)占屏幕值是null就說(shuō)明沒(méi)有。這個(gè)判斷比維護(hù)一個(gè)布爾變量可靠得多因?yàn)橛脩綦S時(shí)可以按 Esc 或用系統(tǒng)手勢(shì)退出你的變量根本收不到通知。狀態(tài)變化靠事件監(jiān)聽(tīng)fullscreenchange在進(jìn)入和退出時(shí)都會(huì)觸發(fā)fullscreenerror只在失敗時(shí)觸發(fā)。這兩個(gè)事件是你做 UI 同步的唯一正確入口后面第 4 節(jié)會(huì)重點(diǎn)講。還有一個(gè)容易忽略的開(kāi)關(guān)document.fullscreenEnabled。它是false的時(shí)候說(shuō)明當(dāng)前環(huán)境從策略層面就不允許全屏典型場(chǎng)景就是被嵌在一個(gè)沒(méi)有授予全屏權(quán)限的 iframe 里。先查這個(gè)值能省掉一半的排查時(shí)間。注意老版本 WebKit 內(nèi)核用的是帶前綴的寫法webkitRequestFullscreen/webkitfullscreenElement移動(dòng)端部分瀏覽器至今仍然只認(rèn)帶前綴的版本。穩(wěn)妥的封裝里要把這兩套都寫上而不是只調(diào)標(biāo)準(zhǔn)接口。1.2 畫布層canvas 的顯示尺寸和繪制尺寸是兩回事這一層是絕大多數(shù)全屏后畫面糊的根源我見(jiàn)過(guò)太多人卡在這。canvas 有兩個(gè)尺寸概念。一個(gè)是 CSS 尺寸也就是它在頁(yè)面上占多大地方由width/height樣式或者父容器決定另一個(gè)是繪制緩沖區(qū)尺寸也就是canvas.width/canvas.height這兩個(gè)屬性它決定了實(shí)際有多少像素參與渲染。兩者不一致的時(shí)候?yàn)g覽器會(huì)把緩沖區(qū)拉伸到 CSS 尺寸上顯示于是要么糊要么鋸齒。Unity 的 WebGL 框架在啟動(dòng)時(shí)會(huì)根據(jù)發(fā)布配置給 canvas 設(shè)一個(gè)初始緩沖區(qū)尺寸之后窗口尺寸變化時(shí)它會(huì)自己重算。但這個(gè)重算依賴一個(gè)條件它讀到的 canvas 的 CSS 尺寸必須是真實(shí)鋪滿容器的。如果你的容器用了transform: scale()、或者給 canvas 加了padding、或者父級(jí)有奇怪的定位方式框架讀到的clientWidth就不是你以為的那個(gè)值重算出來(lái)的緩沖區(qū)尺寸自然也是錯(cuò)的。所以我在模板里的做法永遠(yuǎn)是讓 canvas 老老實(shí)實(shí)width: 100%; height: 100%; display: block;父容器負(fù)責(zé)布局canvas 只負(fù)責(zé)填滿中間不加任何花活。1.3 游戲內(nèi)部層別指望Screen.fullScreen在 WebGL 上生效Unity 的Screen.fullScreen和Screen.SetResolution這套東西在 WebGL 平臺(tái)上是失效的。原因很直白瀏覽器沙箱里的分辨率由 canvas 緩沖區(qū)決定Unity 運(yùn)行時(shí)無(wú)權(quán)直接改操作系統(tǒng)層面的窗口尺寸它能做的只是改自己那塊畫布的像素?cái)?shù)。這意味著你寫在桌面端跑得好好的全屏邏輯搬到 WebGL 上會(huì)變成什么都不發(fā)生而且不報(bào)錯(cuò)。我第一版就是這么翻車的——C# 里判斷了一下平臺(tái)以為是編輯器模擬的問(wèn)題導(dǎo)出來(lái)才發(fā)現(xiàn)是真不生效。正確的分工是全屏的進(jìn)入和退出交給瀏覽器接口畫面的清晰度和比例交給 canvas 尺寸與 Unity 相機(jī)適配。Unity 側(cè)只負(fù)責(zé)發(fā)指令和收狀態(tài)不負(fù)責(zé)真正的全屏動(dòng)作。2. 方案選型真全屏、偽全屏還是兩個(gè)都要2.1 三種常見(jiàn)落地方式的橫向?qū)Ρ仍趧?dòng)手之前先把可選路徑擺清楚。我實(shí)測(cè)過(guò)的三種方式如下方式實(shí)現(xiàn)手段覆蓋范圍主要短板適用場(chǎng)景真全屏元素調(diào)用requestFullscreen()桌面端瀏覽器覆蓋率很高安卓主流瀏覽器可用iOS 上的瀏覽器對(duì)任意元素支持極差必須用戶手勢(shì)觸發(fā)桌面端為主的運(yùn)營(yíng)后臺(tái)、展示型項(xiàng)目偽全屏CSS 把容器鋪滿視口position: fixedinset: 0 高層級(jí)全平臺(tái)無(wú)差別可用瀏覽器地址欄、標(biāo)簽欄依然存在按 Esc 退不出移動(dòng)端為主的 H5 小游戲、必須兼容 iOS 的項(xiàng)目混合方案優(yōu)先真全屏失敗或環(huán)境不支持時(shí)自動(dòng)降級(jí)到偽全屏全平臺(tái)代碼量翻倍兩套狀態(tài)的同步要寫清楚我實(shí)際交付的項(xiàng)目基本都用這個(gè)偽全屏的核心就三行 CSS容器固定定位、四邊貼零、層級(jí)拉到足夠高同時(shí)把body的滾動(dòng)關(guān)掉。它看上去沒(méi)有真正全屏但在移動(dòng)端瀏覽器里用戶感知上的差別遠(yuǎn)小于你的預(yù)期——尤其是當(dāng)頁(yè)面本身就沒(méi)有其他內(nèi)容的時(shí)候。真全屏和偽全屏最大的行為差異在于退出的方式真全屏下用戶按 Esc 或系統(tǒng)返回手勢(shì)會(huì)退出這個(gè)動(dòng)作你攔不住只能監(jiān)聽(tīng)偽全屏下退出只能靠你自己的按鈕所以反而狀態(tài)更可控。這個(gè)差異直接影響第 4 節(jié)的狀態(tài)同步邏輯。2.2 我的選型結(jié)論默認(rèn)走混合判斷條件寫死我現(xiàn)在的固定做法是先判斷環(huán)境能力再?zèng)Q定走哪條路判斷邏輯在下發(fā)指令那一刻執(zhí)行而不是在頁(yè)面加載時(shí)緩存。判斷條件按順序來(lái)document.fullscreenEnabled為true且當(dāng)前元素上存在requestFullscreen方法走真全屏否則直接走偽全屏。iOS 上的瀏覽器基本都會(huì)落到第二條分支上這不是缺陷是現(xiàn)狀提前接受它比事后打補(bǔ)丁省事得多。還有一層要考慮如果項(xiàng)目是嵌在 iframe 里交給第三方用的真全屏這條路還得額外滿足兩個(gè)條件——iframe 標(biāo)簽上要有allowfullscreen屬性同時(shí)allow屬性里要顯式寫明全屏權(quán)限。少任何一個(gè)document.fullscreenEnabled直接是false你連嘗試的機(jī)會(huì)都沒(méi)有。提示混合方案里最容易出問(wèn)題的是降級(jí)后狀態(tài)沒(méi)對(duì)齊。比如真全屏失敗了代碼走了偽全屏分支但 Unity 側(cè)收到的信號(hào)是進(jìn)入成功UI 顯示成退出全屏按鈕用戶點(diǎn)了才發(fā)現(xiàn)根本沒(méi)全屏。所以指令的下發(fā)結(jié)果必須回傳不能只發(fā)不收。3. 改造發(fā)布模板把控制權(quán)從 Unity 手里拿回來(lái)3.1 自定義模板目錄怎么建名字和路徑都是硬要求Unity 的 WebGL 發(fā)布模板放在工程目錄下的Assets/WebGLTemplates/里。這個(gè)路徑的名字、大小寫、層級(jí)都不能錯(cuò)錯(cuò)一個(gè)字母在發(fā)布面板里就看不到你的模板。建目錄的步驟很死板但每次新建工程我都得提醒自己一遍在Assets下建WebGLTemplates文件夾注意首字母大寫、其余小寫、中間不能有空格和下劃線然后在這個(gè)文件夾里建你的模板文件夾比如叫FullscreenTpl把默認(rèn)模板里的index.html復(fù)制進(jìn)去再檢查一下模板文件夾里有沒(méi)有thumbnail.png——沒(méi)有的話發(fā)布面板里那塊預(yù)覽圖是空白的不影響功能但影響心情。發(fā)布的時(shí)候在 Player Settings 的 Resolution and Presentation 里把 WebGL Template 選成你的模板名。選完之后建議清一次瀏覽器緩存在本地跑一遍因?yàn)槲矣龅竭^(guò)發(fā)布配置改了但瀏覽器拿著舊 index.html 的情況排查半天以為是代碼問(wèn)題。模板里的占位符在不同 Unity 版本寫法有差異。老版本用的是%UNITY_WIDTH%、%UNITY_HEIGHT%、%UNITY_WEBGL_LOADER_URL%、%UNITY_WEBGL_DATA_URL%這種百分號(hào)包裹的形式2020 之后的版本改成了{(lán){{ UNITY_WIDTH }}}這種大括號(hào)形式。改模板之前先打開(kāi)原始文件看一眼用的是哪套別照著一個(gè)四年前的教程硬改改完占位符沒(méi)被替換頁(yè)面白屏。3.2 index.html 的骨架改造容器、canvas、覆蓋層三層結(jié)構(gòu)原始模板的結(jié)構(gòu)一般是一個(gè)外層容器包著 canvas 和加載條。我要改的是把容器角色拆清楚外層負(fù)責(zé)鋪滿視口中間層負(fù)責(zé)承載 canvas最上面放我自己的一層 UI 覆蓋元素。結(jié)構(gòu)大致長(zhǎng)這樣div idunity-viewport div idunity-container canvas idunity-canvas tabindex-1/canvas /div div idfs-ui button idfs-btn typebutton全屏/button /div /div幾個(gè)細(xì)節(jié)值得說(shuō)。canvas上的tabindex-1是為了讓它能被腳本聚焦——退出全屏后如果不把焦點(diǎn)還給 canvas鍵盤輸入會(huì)丟玩家按 WASD 沒(méi)反應(yīng)這是我在一個(gè)項(xiàng)目里被反饋了三次的 bug。#fs-ui這層要有pointer-events: none只給按鈕開(kāi)pointer-events: auto否則它會(huì)擋住 canvas 的鼠標(biāo)事件全屏進(jìn)去之后點(diǎn)哪兒都沒(méi)反應(yīng)。加載條的改動(dòng)要謹(jǐn)慎。Unity 的加載進(jìn)度是掛在原始結(jié)構(gòu)上的直接刪掉#unity-loading-bar相關(guān)內(nèi)容會(huì)讓createUnityInstance的進(jìn)度回調(diào)無(wú)處可寫。我的做法是保留結(jié)構(gòu)只調(diào)整樣式把加載條改成覆蓋在 canvas 上方居中的形式加載完成后由框架自己隱藏。3.3 樣式層撐滿、去滾動(dòng)條、處理移動(dòng)端視口高度樣式這塊有三類坑我按順序?qū)?。第一類是滾動(dòng)條。html, body上要同時(shí)設(shè)margin: 0; padding: 0; overflow: hidden;。只設(shè)overflow: hidden而不清margin頁(yè)面頂上會(huì)留 8 像素的白邊全屏之后白邊跟著進(jìn)去看起來(lái)像畫面沒(méi)鋪滿。#unity-viewport上設(shè)position: fixed; inset: 0;比width: 100%; height: 100%更省心因?yàn)樗皇芨讣?jí)定位影響。第二類是高度單位。移動(dòng)端瀏覽器用100vh會(huì)有經(jīng)典的地址欄問(wèn)題——地址欄收起時(shí)100vh比可視區(qū)小地址欄展開(kāi)時(shí)又比可視區(qū)大表現(xiàn)為畫面下方被切掉一條或者出現(xiàn)一條空白。新一點(diǎn)的寫法是用100dvh動(dòng)態(tài)視口高度能跟著地址欄變化。但dvh在部分老設(shè)備上不認(rèn)識(shí)所以要寫成兜底疊加的形式#unity-viewport { position: fixed; inset: 0; height: 100vh; height: 100dvh; overflow: hidden; background: #1a1a1a; }后一行覆蓋前一行認(rèn)識(shí)的用dvh不認(rèn)識(shí)的自動(dòng)退回vh。這是我用了兩年最穩(wěn)的寫法。第三類是 canvas 的顯示尺寸#unity-container { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; } #unity-canvas { display: block; width: 100%; height: 100%; outline: none; background: #000; }display: block是為了干掉行內(nèi)元素基線帶來(lái)的底部空隙outline: none是為了去掉聚焦時(shí)的虛線框——那個(gè)框在游戲里特別扎眼。容器用 flex 居中是為了后面做等比留黑邊的時(shí)候讓 canvas 縮小后仍然居中不用手算偏移。4. 實(shí)操一套可復(fù)用的全屏控制代碼4.1 JS 側(cè)封裝能力探測(cè)、進(jìn)入、退出、狀態(tài)回調(diào)先給一個(gè)能直接用的封裝。幾個(gè)設(shè)計(jì)取舍我在注釋里寫了理由。(function () { const el document.getElementById(unity-viewport); const btn document.getElementById(fs-btn); function canNative() { return !!(document.fullscreenEnabled (el.requestFullscreen || el.webkitRequestFullscreen)); } function isNative() { return !!(document.fullscreenElement || document.webkitFullscreenElement); } function applyPseudo(on) { if (on) { el.classList.add(pseudo-fs); document.body.style.overflow hidden; } else { el.classList.remove(pseudo-fs); document.body.style.overflow ; } notify(on ? enter : exit, pseudo); } function notify(state, mode) { // Unity 側(cè)收到的結(jié)果一定要帶 mode不然分不清是真全屏還是降級(jí) if (window.__unityInstance) { window.__unityInstance.SendMessage(WebBridge, OnFullscreenChanged, JSON.stringify({ state: state, mode: mode })); } } function enter() { if (!canNative()) { applyPseudo(true); return; } const p el.requestFullscreen ? el.requestFullscreen({ navigationUI: hide }) : el.webkitRequestFullscreen(); if (p p.catch) { p.catch(function () { applyPseudo(true); }); } } function exit() { if (isNative()) { const p document.exitFullscreen ? document.exitFullscreen() : document.webkitExitFullscreen(); if (p p.catch) { p.catch(function () {}); } } else { applyPseudo(false); } } function bind() { // 關(guān)鍵直接掛 DOM 點(diǎn)擊不要經(jīng)過(guò) Unity 的輸入鏈路轉(zhuǎn)一圈再調(diào) btn.addEventListener(click, function () { if (isNative() || el.classList.contains(pseudo-fs)) { exit(); } else { enter(); } }); [fullscreenchange, webkitfullscreenchange].forEach(function (ev) { document.addEventListener(ev, function () { const on isNative(); btn.textContent on ? 退出全屏 : 全屏; notify(on ? enter : exit, native); // 布局穩(wěn)定后再觸發(fā)重算見(jiàn) 5.3 setTimeout(function () { window.dispatchEvent(new Event(resize)); if (window.__canvas) { window.__canvas.focus(); } }, 120); }); }); } window.__fsApi { enter: enter, exit: exit, toggle: function () { if (isNative() || el.classList.contains(pseudo-fs)) exit(); else enter(); } }; window.addEventListener(DOMContentLoaded, bind); if (document.readyState ! loading) bind(); })();這里最值得單獨(dú)拎出來(lái)講的是按鈕掛載的位置。很多教程給的方案是Unity 里做一個(gè) UI 按鈕點(diǎn)擊后走 C# → jslib → 調(diào)requestFullscreen()。這條路在 Chromium 內(nèi)核上通常能跑通因?yàn)橛脩艏せ顮顟B(tài)有大約五秒的有效期但在 WebKit 內(nèi)核上全屏調(diào)用必須嚴(yán)格發(fā)生在事件處理函數(shù)的調(diào)用棧里經(jīng)過(guò) Unity 的輸入系統(tǒng)轉(zhuǎn)一圈之后激活狀態(tài)可能已經(jīng)被判定失效表現(xiàn)就是點(diǎn)了完全沒(méi)反應(yīng)控制臺(tái)報(bào)一個(gè) attempt to use fullscreen API failure。所以我的做法是把全屏按鈕做成 DOM 元素浮在 canvas 上面。這樣做還有個(gè)額外好處全屏按鈕在 Unity 加載完成之前就能用用戶不會(huì)遇到點(diǎn)了沒(méi)反應(yīng)因?yàn)橛螒蜻€在加載的情況。代價(jià)是按鈕樣式要自己寫不能復(fù)用游戲內(nèi)的 UI 組件——但說(shuō)實(shí)話一個(gè)全屏按鈕而已兩種狀態(tài)、一個(gè)圖標(biāo)五分鐘的事。4.2 Unity 側(cè)C# 與 jslib 的橋接怎么寫才不翻車Unity 調(diào) JS 走 jslib文件放Assets/Plugins/WebGL/下擴(kuò)展名是.jslib。內(nèi)容是標(biāo)準(zhǔn)的mergeInto結(jié)構(gòu)mergeInto(LibraryManager.library, { FS_Enter: function () { if (window.__fsApi) window.__fsApi.enter(); }, FS_Exit: function () { if (window.__fsApi) window.__fsApi.exit(); }, FS_Toggle: function () { if (window.__fsApi) window.__fsApi.toggle(); }, FS_IsActive: function () { var on !!(document.fullscreenElement || document.webkitFullscreenElement); var pseudo document.getElementById(unity-viewport); if (!on pseudo) on pseudo.classList.contains(pseudo-fs); return on ? 1 : 0; } });C# 這頭包一層重點(diǎn)是條件編譯不能少using System.Runtime.InteropServices; using UnityEngine; public static class FullscreenBridge { #if UNITY_WEBGL !UNITY_EDITOR [DllImport(__Internal)] private static extern void FS_Enter(); [DllImport(__Internal)] private static extern void FS_Exit(); [DllImport(__Internal)] private static extern void FS_Toggle(); [DllImport(__Internal)] private static extern int FS_IsActive(); #endif public static void Enter() { #if UNITY_WEBGL !UNITY_EDITOR FS_Enter(); #endif } public static void Exit() { #if UNITY_WEBGL !UNITY_EDITOR FS_Exit(); #endif } public static void Toggle() { #if UNITY_WEBGL !UNITY_EDITOR FS_Toggle(); #endif } public static bool IsActive { get { #if UNITY_WEBGL !UNITY_EDITOR return FS_IsActive() 1; #else return Screen.fullScreen; #endif } } }DllImport(__Internal)里的雙下劃線加 Internal 是固定寫法寫成別的名字在瀏覽器里會(huì)直接報(bào)找不到函數(shù)。另外編輯器下必須走#else分支否則 Play 模式一跑就拋異常一堆人第一次搭這套東西的時(shí)候就被這個(gè)卡住以為是 jslib 沒(méi)生效。回過(guò)頭來(lái)接收 JS 的回調(diào)需要一個(gè)掛在場(chǎng)景里的 GameObject名字要和 JS 里SendMessage的第一個(gè)參數(shù)完全一致。我一般叫它WebBridge掛在啟動(dòng)場(chǎng)景最上面的一個(gè)空物體上里面就這么點(diǎn)東西using UnityEngine; using System; public class WebBridge : MonoBehaviour { public static event Actionbool, string OnFullscreenChanged; // 由 JS 調(diào)用參數(shù)是 JSON 字符串 public void OnFullscreenChanged(string json) { var state json.Contains(\enter\); var mode json.Contains(native) ? native : pseudo; OnFullscreenChanged?.Invoke(state, mode); } }解析 JSON 那里我用字符串包含判斷看起來(lái)很土。原因是這個(gè)回調(diào)調(diào)用頻率極低用戶點(diǎn)一次全屏才觸發(fā)一次引入一個(gè) JSON 庫(kù)不值當(dāng)而且 WebGL 下 IL2CPP 裁剪有可能把反射用到的字段裁掉我遇到過(guò)一次序列化出來(lái)全是默認(rèn)值的情況從那以后這種極簡(jiǎn)場(chǎng)景我就手寫了。4.3 狀態(tài)雙向同步別讓 UI 和真實(shí)狀態(tài)打架真全屏有個(gè)繞不過(guò)去的特性用戶按 Esc 就能退出你攔不住也不該攔。所以游戲里顯示全屏中實(shí)際早就退出來(lái)了這種狀態(tài)錯(cuò)位只能靠事件監(jiān)聽(tīng)解決靠按鈕點(diǎn)擊是解決不了的。我的同步規(guī)則是三條第一UI 狀態(tài)只由事件驅(qū)動(dòng)不由按鈕點(diǎn)擊驅(qū)動(dòng)。點(diǎn)了按鈕不改 UI等f(wàn)ullscreenchange回來(lái)再改。這樣用戶按 Esc 退出的時(shí)候UI 也會(huì)跟著變回全屏。第二Unity 側(cè)的響應(yīng)要區(qū)分模式。真全屏和偽全屏在游戲內(nèi)的處理不一樣真全屏下瀏覽器 UI 消失可視區(qū)變大相機(jī)需要重新算比例偽全屏下視口尺寸其實(shí)沒(méi)變position: fixed的元素本來(lái)就是這個(gè)尺寸只是被提到了最上層相機(jī)不需要調(diào)整。如果不區(qū)分模式偽全屏下會(huì)出現(xiàn)畫面被二次拉伸的詭異效果。第三進(jìn)入和退出都要能被打斷。全屏請(qǐng)求是異步的返回一個(gè) Promise可能成功也可能失敗。失敗之后必須走降級(jí)而不是停在那里。我在enter()里掛的.catch就是干這個(gè)的。注意不要在fullscreenchange里立刻讀尺寸。這個(gè)事件觸發(fā)的時(shí)候布局往往還沒(méi)穩(wěn)定讀到的clientWidth可能是舊值重算出來(lái)的緩沖區(qū)尺寸就是錯(cuò)的。加一個(gè) 100 到 150 毫秒的延遲或者用requestAnimationFrame套兩層實(shí)測(cè)都行。4.4 iframe 嵌入這兩個(gè)屬性少一個(gè)就白干交付給第三方嵌入的時(shí)候問(wèn)題基本都出在 iframe 上。宿主頁(yè)面那邊iframe標(biāo)簽必須同時(shí)帶上allowfullscreen和allowfullscreen。前一個(gè)是老式寫法后一個(gè)是新式的權(quán)限策略寫法兩個(gè)都寫是為了覆蓋不同版本的瀏覽器。只寫一個(gè)的話在某些組合下全屏請(qǐng)求會(huì)被靜默拒絕。嵌入方這邊你的index.html里沒(méi)法自己給自己授權(quán)。所以能力探測(cè)這一步特別重要document.fullscreenEnabled返回false的時(shí)候立刻走偽全屏別去嘗試真全屏。嘗試失敗的后果是用戶點(diǎn)了按鈕畫面完全沒(méi)變化連降級(jí)都不會(huì)觸發(fā)——因?yàn)?Promise 被拒絕了而你如果沒(méi)寫 catch那就什么都不會(huì)發(fā)生。還有一個(gè)更麻煩的情況如果宿主和 iframe 不同源你連fullscreenEnabled都可能讀不到真實(shí)值。這種場(chǎng)景我一般直接默認(rèn)走偽全屏同時(shí)給宿主方提供一段說(shuō)明告訴他們?nèi)绻嫒列枰?iframe 上加哪些屬性。把選擇權(quán)交出去比自己猜要靠譜。如果游戲里有需要鼠標(biāo)鎖定的操作比如第一人稱視角requestPointerLock也有類似的權(quán)限要求iframe 上要額外加allowfullscreen; pointer-lock。這個(gè)細(xì)節(jié)我在一個(gè)項(xiàng)目里漏了導(dǎo)致嵌入版里視角拖不動(dòng)查了兩天才發(fā)現(xiàn)問(wèn)題在宿主頁(yè)面的 iframe 標(biāo)簽上。5. 全屏之后才是真正的難點(diǎn)分辨率與畫面比例5.1 DPR 與渲染分辨率清晰度和顯存的拉扯進(jìn)全屏之后畫面變糊八成是 DPR 的問(wèn)題。window.devicePixelRatio在普通筆記本上一般是 1 或 1.25在高端顯示器上是 2在手機(jī)上普遍是 2 到 3。Unity 的 WebGL 框架會(huì)讀取這個(gè)值把 canvas 的緩沖區(qū)尺寸按 DPR 放大這樣在高分屏上畫面才清晰。問(wèn)題在于這個(gè)放大是平方級(jí)的。假設(shè)你的可視區(qū)是 1920×1080DPR 是 2緩沖區(qū)就是 3840×2160像素?cái)?shù)是原來(lái)的四倍。WebGL 的填充率、顯存占用、后期處理的采樣成本全部翻四倍。我一個(gè)項(xiàng)目在開(kāi)發(fā)機(jī)上跑得挺流暢到了配置一般的機(jī)器上開(kāi)了全屏直接掉到二十幀原因就是這個(gè)。我的處理原則是給 DPR 設(shè)一個(gè)上限并且允許玩家自己調(diào)。具體做法是在createUnityInstance之前先覆寫一次像素比(function () { const MAX_DPR 1.5; const raw window.devicePixelRatio || 1; const capped Math.min(raw, MAX_DPR); if (capped raw) return; Object.defineProperty(window, devicePixelRatio, { get: function () { return capped; }, configurable: true }); })();這段必須在 Unity 的加載腳本執(zhí)行之前跑放在index.html里加載腳本的上方就行。1.5 這個(gè)值是我反復(fù)試出來(lái)的折中從 1 提到 1.5清晰度提升肉眼可見(jiàn)從 1.5 提到 2多數(shù)場(chǎng)景下幾乎看不出差別但性能開(kāi)銷是實(shí)打?qū)嵉?。另外提一句Application.targetFrameRate在 WebGL 里是生效的設(shè)成 60 配合瀏覽器的刷新節(jié)奏比較穩(wěn)。但要注意標(biāo)簽頁(yè)切到后臺(tái)時(shí)瀏覽器會(huì)主動(dòng)降頻這時(shí)候測(cè)出來(lái)的幀率沒(méi)有參考價(jià)值測(cè)性能必須保證標(biāo)簽頁(yè)在前臺(tái)。5.2 寬高比變化拉伸、裁切還是留黑邊從普通頁(yè)面進(jìn)全屏可視區(qū)的寬高比一定變了。原來(lái)是瀏覽器里嵌著一塊 16:9 的區(qū)域全屏之后可能變成 16:10 甚至 21:9。這時(shí)候畫面怎么處理只有三個(gè)選項(xiàng)。拉伸鋪滿canvas 直接 100% 撐滿不改相機(jī)。畫面會(huì)被橫向或縱向拉伸圓形變橢圓角色變胖變瘦。除非你的游戲是純 2D 抽象的否則別選這個(gè)。留黑邊canvas 保持原始比例居中顯示兩邊或上下留黑。做法是在容器的 flex 布局基礎(chǔ)上給 canvas 設(shè)aspect-ratio: 16 / 9;同時(shí)max-width: 100%; max-height: 100%;。這是最省事、最不破壞畫面構(gòu)圖的方式代價(jià)是浪費(fèi)一部分屏幕面積。動(dòng)態(tài)適配canvas 撐滿然后 Unity 側(cè)根據(jù)新的寬高比調(diào)整相機(jī)。正交相機(jī)調(diào)orthographicSize透視相機(jī)調(diào)fieldOfView或者用Camera.rect做視野擴(kuò)展。這種方式觀感最好但要處理多出來(lái)的視野里露出場(chǎng)景邊界的問(wèn)題——我們的做法是在場(chǎng)景四周預(yù)留一圈裝飾性元素視野擴(kuò)大時(shí)露出來(lái)也不突兀。實(shí)際項(xiàng)目里我用得最多的是留黑邊 關(guān)鍵 UI 動(dòng)態(tài)適配的組合。渲染層保持嚴(yán)格的比例保證畫面不變形UI 層用CanvasScaler的Match Width Or Height模式match值設(shè)成 0.5讓 UI 在寬高比變化時(shí)做等比縮放兩邊的錨點(diǎn)該貼邊的貼邊。這樣一個(gè) 16:9 的工程在 21:9 的屏幕上畫面居中留黑邊UI 該在右上角的還在右上角不會(huì)跑到屏幕外面去。5.3 重算尺寸的時(shí)機(jī)與順序順序錯(cuò)了白算全屏切換之后尺寸重算涉及三個(gè)動(dòng)作順序有講究第一等 CSS 布局落地。全屏切換會(huì)引起容器尺寸變化瀏覽器需要一幀來(lái)重新布局。這就是為什么fullscreenchange里不能立刻讀尺寸。第二讓 canvas 的 CSS 尺寸先正確。框架讀的是clientWidth/clientHeight這兩個(gè)值由 CSS 決定必須先對(duì)。第三觸發(fā)重算。多數(shù)版本的做法是派發(fā)一個(gè)窗口resize事件讓 Unity 的框架按它自己的邏輯去更新緩沖區(qū)。我實(shí)測(cè)下來(lái)的寫法是function refreshCanvas() { requestAnimationFrame(function () { requestAnimationFrame(function () { window.dispatchEvent(new Event(resize)); }); }); }雙requestAnimationFrame是為了保證布局一定已經(jīng)完成。用setTimeout100 毫秒也行但rAF更精確而且不會(huì)在后臺(tái)標(biāo)簽頁(yè)里亂跑。如果你的版本框架重算不靈還有一個(gè)兜底方案手動(dòng)改canvas.width/canvas.height然后等下一次框架自己校準(zhǔn)。但我不推薦長(zhǎng)期用這個(gè)因?yàn)槭謩?dòng)改和框架內(nèi)部的尺寸記錄會(huì)打架容易出現(xiàn)改完一幀之后又被改回去的現(xiàn)象表現(xiàn)是畫面抖一下。還有一點(diǎn)重算之后要主動(dòng)把焦點(diǎn)還給 canvas。前面提過(guò)tabindex-1的用法配合canvas.focus()一起用。不做這一步的用戶體驗(yàn)是全屏之后打字打不了、按方向鍵頁(yè)面在滾動(dòng)尤其在有聊天框或者輸入功能的項(xiàng)目里必現(xiàn)。6. 踩坑記錄與排查手冊(cè)6.1 高頻問(wèn)題速查表下面這張表是我這幾年攢下來(lái)的遇到現(xiàn)象先查這張表能覆蓋八成情況?，F(xiàn)象最可能的原因處理方式點(diǎn)按鈕完全無(wú)反應(yīng)調(diào)用不在用戶手勢(shì)的調(diào)用棧里或 iframe 缺全屏權(quán)限按鈕掛 DOM 層直接監(jiān)聽(tīng)檢查allowfullscreen與allow全屏后畫面模糊DPR 過(guò)高或 canvas 緩沖區(qū)未重算限制 DPR 上限全屏后延遲派發(fā)resize全屏后畫面拉伸變形canvas 撐滿但相機(jī)未適配用aspect-ratio留黑邊或按寬高比重算相機(jī)按 Esc 退出后 UI 狀態(tài)錯(cuò)亂UI 只由點(diǎn)擊事件驅(qū)動(dòng)沒(méi)監(jiān)聽(tīng)fullscreenchange改為事件驅(qū)動(dòng)點(diǎn)擊后不改狀態(tài)全屏后鼠標(biāo)點(diǎn)擊位置偏移canvas 上有 padding、border 或transform: scale去掉所有影響clientRect的樣式全屏后鍵盤輸入失效焦點(diǎn)沒(méi)回到 canvascanvas.focus()并加tabindex-1頁(yè)面底部有一條空白用了100vh但移動(dòng)端地址欄變化改用100dvh并保留vh兜底全屏按鈕被畫面擋住UI 層層級(jí)或pointer-events設(shè)置錯(cuò)誤覆蓋層pointer-events: none按鈕單獨(dú)開(kāi)auto全屏進(jìn)入后立刻自動(dòng)退出同時(shí)調(diào)了兩次進(jìn)入/退出或和頁(yè)面其他全屏邏輯沖突調(diào)用前先查fullscreenElement判斷當(dāng)前狀態(tài)移動(dòng)端全屏后無(wú)法橫屏屏幕方向鎖定未申請(qǐng)或不被支持先進(jìn)入全屏再調(diào)screen.orientation.lock失敗則改用 UI 提示6.2 幾個(gè)不好查的疑難 case說(shuō)三個(gè)我印象最深的。第一個(gè)是全屏后鼠標(biāo)點(diǎn)不準(zhǔn)。表現(xiàn)是角色能跑但點(diǎn)擊 UI 按鈕的位置偏了大概二十來(lái)個(gè)像素。查了半天發(fā)現(xiàn)是覆蓋層的按鈕用了padding而 Unity 計(jì)算鼠標(biāo)位置的時(shí)候用的是 canvas 的包圍盒兩者坐標(biāo)系看似一樣實(shí)際因?yàn)楦采w層居中對(duì)齊多算了偏移。最后的解決方式是給 canvas 加一個(gè)明確的getBoundingClientRect打印在瀏覽器里對(duì)一遍一眼就看出來(lái) canvas 的實(shí)際位置比視覺(jué)位置高了一截。這種問(wèn)題的排查思路是不要猜把getBoundingClientRect()的四個(gè)值打出來(lái)和視覺(jué)位置對(duì)比。第二個(gè)是偽全屏下畫面被放大了一倍。原因是偽全屏的 CSS 里寫了transform: scale(1)之類的變換而 Unity 框架在算緩沖區(qū)尺寸的時(shí)候用的是offsetWidthtransform不改變offsetWidth但它會(huì)改變視覺(jué)呈現(xiàn)。視覺(jué)上放大了緩沖區(qū)沒(méi)跟上于是糊。教訓(xùn)是布局不要用transform要用尺寸本身去控制。第三個(gè)是退出全屏后黑屏一瞬。原因是退出全屏?xí)r容器尺寸從大變小框架重算緩沖區(qū)還沒(méi)完成瀏覽器已經(jīng)用舊的緩沖區(qū)做了拉伸顯示。視覺(jué)上就是一閃。處理方式是在容器上加一個(gè)短暫的背景色過(guò)渡或者干脆接受這一幀——如果追求極致可以在退出前先把 canvas 縮放到目標(biāo)尺寸再退出全屏但這樣代碼復(fù)雜度會(huì)上去不少。6.3 我總結(jié)的幾條硬規(guī)矩最后這幾條是長(zhǎng)期踩坑總結(jié)出來(lái)的寫在這里當(dāng)備忘。全屏按鈕永遠(yuǎn)是 DOM 元素不做成 Unity 內(nèi) UI。這條前面說(shuō)過(guò)再?gòu)?qiáng)調(diào)一次因?yàn)樗芤淮涡越鉀Q點(diǎn)了沒(méi)反應(yīng)和加載期間不能用兩個(gè)問(wèn)題。能力探測(cè)在調(diào)用那一刻做不在加載時(shí)緩存。iframe 的權(quán)限、用戶手勢(shì)狀態(tài)、瀏覽器策略這些都可能在運(yùn)行期間變化。緩存一個(gè)布爾值看起來(lái)省事實(shí)際會(huì)埋雷。狀態(tài)只認(rèn)事件不認(rèn)操作。UI 顯示什么完全由fullscreenchange決定。用戶按 Esc 退出這件事你管不了能管的只有自己的狀態(tài)。降級(jí)路徑必須是默認(rèn)路徑的一部分不是異常處理。我在enter()里把降級(jí)寫在.catch里但更重要的是canNative()返回false的時(shí)候直接走偽全屏那條分支。這兩條路在我這里地位是對(duì)等的。尺寸重算永遠(yuǎn)延遲一幀。任何一個(gè)進(jìn)入/退出全屏之后立即讀尺寸的寫法都有概率讀到舊值。加rAF不加成本不加就是玄學(xué) bug。別在 iframe 里賭權(quán)限。拿不到fullscreenEnabled的時(shí)候直接告訴嵌入方需要加什么屬性比自己嘗試要快。這套代碼現(xiàn)在是我們幾個(gè) WebGL 項(xiàng)目的標(biāo)準(zhǔn)模板新建工程直接拷過(guò)去改一下按鈕位置和配色就能用。中間那層混合方案的設(shè)計(jì)其實(shí)是被逼出來(lái)的——?jiǎng)傞_(kāi)始只想做真全屏結(jié)果第一個(gè)交付的客戶就用 iPad 驗(yàn)收當(dāng)場(chǎng)翻車回來(lái)才把偽全屏補(bǔ)上?，F(xiàn)在回頭看早一點(diǎn)接受全屏不是一個(gè)按鈕的事而是一套狀態(tài)機(jī)能省下的時(shí)間遠(yuǎn)超寫這套代碼的時(shí)間。