去年接了個(gè)把 Unity 項(xiàng)目搬進(jìn)瀏覽器的活美術(shù)和策劃直接在網(wǎng)頁上驗(yàn)收第一句話就是怎么點(diǎn)了全屏沒反應(yīng)。當(dāng)時(shí)我以為加個(gè)按鈕調(diào)一下瀏覽器的全屏接口就完事結(jié)果一頭撞進(jìn)坑里按鈕點(diǎn)了沒反應(yīng)、全屏之后畫面糊成一片、按 Esc 退出來 UI 還掛著全屏中的狀態(tài)、嵌在 iframe 里干脆整套接口都摸不到。前前后后折騰了兩三天才把 UnityWebGl 網(wǎng)頁全屏顯示這件事從能點(diǎn)做到能用再到敢交付。這篇東西就是把那幾天的過程攤開講。全屏在 Unity WebGL 里從來不是調(diào)一個(gè) API的問題它橫跨三層瀏覽器的視口控制、canvas 的繪制緩沖區(qū)、Unity 內(nèi)部的相機(jī)與 UI 適配。任何一層沒對(duì)齊表現(xiàn)出來都是全屏壞了但壞的地方完全不一樣。下面這套內(nèi)容適合三類人看剛把項(xiàng)目導(dǎo)出成 WebGL、被全屏按鈕折磨過的開發(fā)者要交付給第三方嵌入、被 iframe 卡住的同學(xué)以及畫面全屏后糊掉、變形、鼠標(biāo)點(diǎn)不準(zhǔn)找不到原因的人。代碼可以直接抄思路可以直接套。1. 先把全屏拆成三層不然后面全是返工1.1 瀏覽器視口層全屏接口到底給了你什么瀏覽器提供的全屏能力本質(zhì)上是讓某一個(gè) DOM 元素脫離頁面布局獨(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——它有值就說明有元素正在獨(dú)占屏幕值是null就說明沒有。這個(gè)判斷比維護(hù)一個(gè)布爾變量可靠得多因?yàn)橛脩綦S時(shí)可以按 Esc 或用系統(tǒng)手勢(shì)退出你的變量根本收不到通知。狀態(tài)變化靠事件監(jiān)聽fullscreenchange在進(jìn)入和退出時(shí)都會(huì)觸發(fā)fullscreenerror只在失敗時(shí)觸發(fā)。這兩個(gè)事件是你做 UI 同步的唯一正確入口后面第 4 節(jié)會(huì)重點(diǎn)講。還有一個(gè)容易忽略的開關(guān)document.fullscreenEnabled。它是false的時(shí)候說明當(dāng)前環(huán)境從策略層面就不允許全屏典型場(chǎng)景就是被嵌在一個(gè)沒有授予全屏權(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ù)全屏后畫面糊的根源我見過太多人卡在這。canvas 有兩個(gè)尺寸概念。一個(gè)是 CSS 尺寸也就是它在頁面上占多大地方由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è)值重算出來的緩沖區(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í)無權(quán)直接改操作系統(tǒng)層面的窗口尺寸它能做的只是改自己那塊畫布的像素?cái)?shù)。這意味著你寫在桌面端跑得好好的全屏邏輯搬到 WebGL 上會(huì)變成什么都不發(fā)生而且不報(bào)錯(cuò)。我第一版就是這么翻車的——C# 里判斷了一下平臺(tái)以為是編輯器模擬的問題導(dǎo)出來才發(fā)現(xiàn)是真不生效。正確的分工是全屏的進(jìn)入和退出交給瀏覽器接口畫面的清晰度和比例交給 canvas 尺寸與 Unity 相機(jī)適配。Unity 側(cè)只負(fù)責(zé)發(fā)指令和收狀態(tài)不負(fù)責(zé)真正的全屏動(dòng)作。2. 方案選型真全屏、偽全屏還是兩個(gè)都要2.1 三種常見落地方式的橫向?qū)Ρ仍趧?dòng)手之前先把可選路徑擺清楚。我實(shí)測(cè)過的三種方式如下方式實(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)無差別可用瀏覽器地址欄、標(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)掉。它看上去沒有真正全屏但在移動(dòng)端瀏覽器里用戶感知上的差別遠(yuǎn)小于你的預(yù)期——尤其是當(dāng)頁面本身就沒有其他內(nèi)容的時(shí)候。真全屏和偽全屏最大的行為差異在于退出的方式真全屏下用戶按 Esc 或系統(tǒng)返回手勢(shì)會(huì)退出這個(gè)動(dòng)作你攔不住只能監(jiān)聽偽全屏下退出只能靠你自己的按鈕所以反而狀態(tài)更可控。這個(gè)差異直接影響第 4 節(jié)的狀態(tài)同步邏輯。2.2 我的選型結(jié)論默認(rèn)走混合判斷條件寫死我現(xiàn)在的固定做法是先判斷環(huán)境能力再?zèng)Q定走哪條路判斷邏輯在下發(fā)指令那一刻執(zhí)行而不是在頁面加載時(shí)緩存。判斷條件按順序來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ì)都沒有。提示混合方案里最容易出問題的是降級(jí)后狀態(tài)沒對(duì)齊。比如真全屏失敗了代碼走了偽全屏分支但 Unity 側(cè)收到的信號(hào)是進(jìn)入成功UI 顯示成退出全屏按鈕用戶點(diǎn)了才發(fā)現(xiàn)根本沒全屏。所以指令的下發(fā)結(jié)果必須回傳不能只發(fā)不收。3. 改造發(fā)布模板把控制權(quán)從 Unity 手里拿回來3.1 自定義模板目錄怎么建名字和路徑都是硬要求Unity 的 WebGL 發(fā)布模板放在工程目錄下的Assets/WebGLTemplates/里。這個(gè)路徑的名字、大小寫、層級(jí)都不能錯(cuò)錯(cuò)一個(gè)字母在發(fā)布面板里就看不到你的模板。建目錄的步驟很死板但每次新建工程我都得提醒自己一遍在Assets下建WebGLTemplates文件夾注意首字母大寫、其余小寫、中間不能有空格和下劃線然后在這個(gè)文件夾里建你的模板文件夾比如叫FullscreenTpl把默認(rèn)模板里的index.html復(fù)制進(jìn)去再檢查一下模板文件夾里有沒有thumbnail.png——沒有的話發(fā)布面板里那塊預(yù)覽圖是空白的不影響功能但影響心情。發(fā)布的時(shí)候在 Player Settings 的 Resolution and Presentation 里把 WebGL Template 選成你的模板名。選完之后建議清一次瀏覽器緩存在本地跑一遍因?yàn)槲矣龅竭^發(fā)布配置改了但瀏覽器拿著舊 index.html 的情況排查半天以為是代碼問題。模板里的占位符在不同 Unity 版本寫法有差異。老版本用的是%UNITY_WIDTH%、%UNITY_HEIGHT%、%UNITY_WEBGL_LOADER_URL%、%UNITY_WEBGL_DATA_URL%這種百分號(hào)包裹的形式2020 之后的版本改成了{(lán){{ UNITY_WIDTH }}}這種大括號(hào)形式。改模板之前先打開原始文件看一眼用的是哪套別照著一個(gè)四年前的教程硬改改完占位符沒被替換頁面白屏。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é)值得說。canvas上的tabindex-1是為了讓它能被腳本聚焦——退出全屏后如果不把焦點(diǎn)還給 canvas鍵盤輸入會(huì)丟玩家按 WASD 沒反應(yīng)這是我在一個(gè)項(xiàng)目里被反饋了三次的 bug。#fs-ui這層要有pointer-events: none只給按鈕開pointer-events: auto否則它會(huì)擋住 canvas 的鼠標(biāo)事件全屏進(jìn)去之后點(diǎn)哪兒都沒反應(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)無處可寫。我的做法是保留結(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頁面頂上會(huì)留 8 像素的白邊全屏之后白邊跟著進(jìn)去看起來像畫面沒鋪滿。#unity-viewport上設(shè)position: fixed; inset: 0;比width: 100%; height: 100%更省心因?yàn)樗皇芨讣?jí)定位影響。第二類是高度單位。移動(dòng)端瀏覽器用100vh會(huì)有經(jīng)典的地址欄問題——地址欄收起時(shí)100vh比可視區(qū)小地址欄展開時(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)元素基線帶來的底部空隙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)過 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ā)重算見 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ú)拎出來講的是按鈕掛載的位置。很多教程給的方案是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)過 Unity 的輸入系統(tǒng)轉(zhuǎn)一圈之后激活狀態(tài)可能已經(jīng)被判定失效表現(xiàn)就是點(diǎn)了完全沒反應(yīng)控制臺(tái)報(bào)一個(gè) attempt to use fullscreen API failure。所以我的做法是把全屏按鈕做成 DOM 元素浮在 canvas 上面。這樣做還有個(gè)額外好處全屏按鈕在 Unity 加載完成之前就能用用戶不會(huì)遇到點(diǎn)了沒反應(yīng)因?yàn)橛螒蜻€在加載的情況。代價(jià)是按鈕樣式要自己寫不能復(fù)用游戲內(nèi)的 UI 組件——但說實(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 沒生效。回過頭來接收 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 那里我用字符串包含判斷看起來很土。原因是這個(gè)回調(diào)調(diào)用頻率極低用戶點(diǎn)一次全屏才觸發(fā)一次引入一個(gè) JSON 庫不值當(dāng)而且 WebGL 下 IL2CPP 裁剪有可能把反射用到的字段裁掉我遇到過一次序列化出來全是默認(rèn)值的情況從那以后這種極簡(jiǎn)場(chǎng)景我就手寫了。4.3 狀態(tài)雙向同步別讓 UI 和真實(shí)狀態(tài)打架真全屏有個(gè)繞不過去的特性用戶按 Esc 就能退出你攔不住也不該攔。所以游戲里顯示全屏中實(shí)際早就退出來了這種狀態(tài)錯(cuò)位只能靠事件監(jiān)聽解決靠按鈕點(diǎn)擊是解決不了的。我的同步規(guī)則是三條第一UI 狀態(tài)只由事件驅(qū)動(dòng)不由按鈕點(diǎn)擊驅(qū)動(dòng)。點(diǎn)了按鈕不改 UI等fullscreenchange回來再改。這樣用戶按 Esc 退出的時(shí)候UI 也會(huì)跟著變回全屏。第二Unity 側(cè)的響應(yīng)要區(qū)分模式。真全屏和偽全屏在游戲內(nèi)的處理不一樣真全屏下瀏覽器 UI 消失可視區(qū)變大相機(jī)需要重新算比例偽全屏下視口尺寸其實(shí)沒變position: fixed的元素本來就是這個(gè)尺寸只是被提到了最上層相機(jī)不需要調(diào)整。如果不區(qū)分模式偽全屏下會(huì)出現(xiàn)畫面被二次拉伸的詭異效果。第三進(jìn)入和退出都要能被打斷。全屏請(qǐng)求是異步的返回一個(gè) Promise可能成功也可能失敗。失敗之后必須走降級(jí)而不是停在那里。我在enter()里掛的.catch就是干這個(gè)的。注意不要在fullscreenchange里立刻讀尺寸。這個(gè)事件觸發(fā)的時(shí)候布局往往還沒穩(wěn)定讀到的clientWidth可能是舊值重算出來的緩沖區(qū)尺寸就是錯(cuò)的。加一個(gè) 100 到 150 毫秒的延遲或者用requestAnimationFrame套兩層實(shí)測(cè)都行。4.4 iframe 嵌入這兩個(gè)屬性少一個(gè)就白干交付給第三方嵌入的時(shí)候問題基本都出在 iframe 上。宿主頁面那邊iframe標(biāo)簽必須同時(shí)帶上allowfullscreen和allowfullscreen。前一個(gè)是老式寫法后一個(gè)是新式的權(quán)限策略寫法兩個(gè)都寫是為了覆蓋不同版本的瀏覽器。只寫一個(gè)的話在某些組合下全屏請(qǐng)求會(huì)被靜默拒絕。嵌入方這邊你的index.html里沒法自己給自己授權(quán)。所以能力探測(cè)這一步特別重要document.fullscreenEnabled返回false的時(shí)候立刻走偽全屏別去嘗試真全屏。嘗試失敗的后果是用戶點(diǎn)了按鈕畫面完全沒變化連降級(jí)都不會(huì)觸發(fā)——因?yàn)?Promise 被拒絕了而你如果沒寫 catch那就什么都不會(huì)發(fā)生。還有一個(gè)更麻煩的情況如果宿主和 iframe 不同源你連fullscreenEnabled都可能讀不到真實(shí)值。這種場(chǎng)景我一般直接默認(rèn)走偽全屏同時(shí)給宿主方提供一段說明告訴他們?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)問題在宿主頁面的 iframe 標(biāo)簽上。5. 全屏之后才是真正的難點(diǎn)分辨率與畫面比例5.1 DPR 與渲染分辨率清晰度和顯存的拉扯進(jìn)全屏之后畫面變糊八成是 DPR 的問題。window.devicePixelRatio在普通筆記本上一般是 1 或 1.25在高端顯示器上是 2在手機(jī)上普遍是 2 到 3。Unity 的 WebGL 框架會(huì)讀取這個(gè)值把 canvas 的緩沖區(qū)尺寸按 DPR 放大這樣在高分屏上畫面才清晰。問題在于這個(gè)放大是平方級(jí)的。假設(shè)你的可視區(qū)是 1920×1080DPR 是 2緩沖區(qū)就是 3840×2160像素?cái)?shù)是原來的四倍。WebGL 的填充率、顯存占用、后期處理的采樣成本全部翻四倍。我一個(gè)項(xiàng)目在開發(fā)機(jī)上跑得挺流暢到了配置一般的機(jī)器上開了全屏直接掉到二十幀原因就是這個(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ù)試出來的折中從 1 提到 1.5清晰度提升肉眼可見從 1.5 提到 2多數(shù)場(chǎng)景下幾乎看不出差別但性能開銷是實(shí)打?qū)嵉?。另外提一句Application.targetFrameRate在 WebGL 里是生效的設(shè)成 60 配合瀏覽器的刷新節(jié)奏比較穩(wěn)。但要注意標(biāo)簽頁切到后臺(tái)時(shí)瀏覽器會(huì)主動(dòng)降頻這時(shí)候測(cè)出來的幀率沒有參考價(jià)值測(cè)性能必須保證標(biāo)簽頁在前臺(tái)。5.2 寬高比變化拉伸、裁切還是留黑邊從普通頁面進(jìn)全屏可視區(qū)的寬高比一定變了。原來是瀏覽器里嵌著一塊 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ò)展。這種方式觀感最好但要處理多出來的視野里露出場(chǎng)景邊界的問題——我們的做法是在場(chǎng)景四周預(yù)留一圈裝飾性元素視野擴(kuò)大時(shí)露出來也不突兀。實(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ì)引起容器尺寸變化瀏覽器需要一幀來重新布局。這就是為什么fullscreenchange里不能立刻讀尺寸。第二讓 canvas 的 CSS 尺寸先正確。框架讀的是clientWidth/clientHeight這兩個(gè)值由 CSS 決定必須先對(duì)。第三觸發(fā)重算。多數(shù)版本的做法是派發(fā)一個(gè)窗口resize事件讓 Unity 的框架按它自己的邏輯去更新緩沖區(qū)。我實(shí)測(cè)下來的寫法是function refreshCanvas() { requestAnimationFrame(function () { requestAnimationFrame(function () { window.dispatchEvent(new Event(resize)); }); }); }雙requestAnimationFrame是為了保證布局一定已經(jīng)完成。用setTimeout100 毫秒也行但rAF更精確而且不會(huì)在后臺(tái)標(biāo)簽頁里亂跑。如果你的版本框架重算不靈還有一個(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。前面提過tabindex-1的用法配合canvas.focus()一起用。不做這一步的用戶體驗(yàn)是全屏之后打字打不了、按方向鍵頁面在滾動(dòng)尤其在有聊天框或者輸入功能的項(xiàng)目里必現(xiàn)。6. 踩坑記錄與排查手冊(cè)6.1 高頻問題速查表下面這張表是我這幾年攢下來的遇到現(xiàn)象先查這張表能覆蓋八成情況?，F(xiàn)象最可能的原因處理方式點(diǎn)按鈕完全無反應(yīng)調(diào)用不在用戶手勢(shì)的調(diào)用棧里或 iframe 缺全屏權(quán)限按鈕掛 DOM 層直接監(jiān)聽檢查allowfullscreen與allow全屏后畫面模糊DPR 過高或 canvas 緩沖區(qū)未重算限制 DPR 上限全屏后延遲派發(fā)resize全屏后畫面拉伸變形canvas 撐滿但相機(jī)未適配用aspect-ratio留黑邊或按寬高比重算相機(jī)按 Esc 退出后 UI 狀態(tài)錯(cuò)亂UI 只由點(diǎn)擊事件驅(qū)動(dòng)沒監(jiān)聽fullscreenchange改為事件驅(qū)動(dòng)點(diǎn)擊后不改狀態(tài)全屏后鼠標(biāo)點(diǎn)擊位置偏移canvas 上有 padding、border 或transform: scale去掉所有影響clientRect的樣式全屏后鍵盤輸入失效焦點(diǎn)沒回到 canvascanvas.focus()并加tabindex-1頁面底部有一條空白用了100vh但移動(dòng)端地址欄變化改用100dvh并保留vh兜底全屏按鈕被畫面擋住UI 層層級(jí)或pointer-events設(shè)置錯(cuò)誤覆蓋層pointer-events: none按鈕單獨(dú)開auto全屏進(jìn)入后立刻自動(dòng)退出同時(shí)調(diào)了兩次進(jìn)入/退出或和頁面其他全屏邏輯沖突調(diào)用前先查fullscreenElement判斷當(dāng)前狀態(tài)移動(dòng)端全屏后無法橫屏屏幕方向鎖定未申請(qǐng)或不被支持先進(jìn)入全屏再調(diào)screen.orientation.lock失敗則改用 UI 提示6.2 幾個(gè)不好查的疑難 case說三個(gè)我印象最深的。第一個(gè)是全屏后鼠標(biāo)點(diǎn)不準(zhǔn)。表現(xiàn)是角色能跑但點(diǎn)擊 UI 按鈕的位置偏了大概二十來個(gè)像素。查了半天發(fā)現(xiàn)是覆蓋層的按鈕用了padding而 Unity 計(jì)算鼠標(biāo)位置的時(shí)候用的是 canvas 的包圍盒兩者坐標(biāo)系看似一樣實(shí)際因?yàn)楦采w層居中對(duì)齊多算了偏移。最后的解決方式是給 canvas 加一個(gè)明確的getBoundingClientRect打印在瀏覽器里對(duì)一遍一眼就看出來 canvas 的實(shí)際位置比視覺位置高了一截。這種問題的排查思路是不要猜把getBoundingClientRect()的四個(gè)值打出來和視覺位置對(duì)比。第二個(gè)是偽全屏下畫面被放大了一倍。原因是偽全屏的 CSS 里寫了transform: scale(1)之類的變換而 Unity 框架在算緩沖區(qū)尺寸的時(shí)候用的是offsetWidthtransform不改變offsetWidth但它會(huì)改變視覺呈現(xiàn)。視覺上放大了緩沖區(qū)沒跟上于是糊。教訓(xùn)是布局不要用transform要用尺寸本身去控制。第三個(gè)是退出全屏后黑屏一瞬。原因是退出全屏?xí)r容器尺寸從大變小框架重算緩沖區(qū)還沒完成瀏覽器已經(jīng)用舊的緩沖區(qū)做了拉伸顯示。視覺上就是一閃。處理方式是在容器上加一個(gè)短暫的背景色過渡或者干脆接受這一幀——如果追求極致可以在退出前先把 canvas 縮放到目標(biāo)尺寸再退出全屏但這樣代碼復(fù)雜度會(huì)上去不少。6.3 我總結(jié)的幾條硬規(guī)矩最后這幾條是長(zhǎng)期踩坑總結(jié)出來的寫在這里當(dāng)備忘。全屏按鈕永遠(yuǎn)是 DOM 元素不做成 Unity 內(nèi) UI。這條前面說過再強(qiáng)調(diào)一次因?yàn)樗芤淮涡越鉀Q點(diǎn)了沒反應(yīng)和加載期間不能用兩個(gè)問題。能力探測(cè)在調(diào)用那一刻做不在加載時(shí)緩存。iframe 的權(quán)限、用戶手勢(shì)狀態(tài)、瀏覽器策略這些都可能在運(yùn)行期間變化。緩存一個(gè)布爾值看起來省事實(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)模板新建工程直接拷過去改一下按鈕位置和配色就能用。中間那層混合方案的設(shè)計(jì)其實(shí)是被逼出來的——?jiǎng)傞_始只想做真全屏結(jié)果第一個(gè)交付的客戶就用 iPad 驗(yàn)收當(dāng)場(chǎng)翻車回來才把偽全屏補(bǔ)上。現(xiàn)在回頭看早一點(diǎn)接受全屏不是一個(gè)按鈕的事而是一套狀態(tài)機(jī)能省下的時(shí)間遠(yuǎn)超寫這套代碼的時(shí)間。