實(shí)踐)
先聊一個(gè)查了半天的坑?？蛻裟沁吥螟櫭蓱?yīng)用的Web組件加載H5頁面頁面里放了一段視頻網(wǎng)頁在手機(jī)瀏覽器里打開一切正常點(diǎn)全屏按鈕就能橫屏播放。放進(jìn)鴻蒙應(yīng)用里視頻能播、聲音也有就是點(diǎn)全屏沒反應(yīng)或者閃一下就退出來偶爾還會(huì)出現(xiàn)黑屏但有聲的怪狀態(tài)。查日志、翻文檔、各種試錯(cuò)之后問題基本鎖定在三個(gè)層面鴻蒙Web組件的全屏權(quán)限沒開、H5頁面video標(biāo)簽和全屏API的寫法不兼容、還有全屏生命周期回調(diào)里沒有同步處理窗口旋轉(zhuǎn)和沉浸式布局。這篇文章我把排查過程和修復(fù)方案完整寫一遍給做鴻蒙應(yīng)用內(nèi)嵌H5業(yè)務(wù)的同學(xué)當(dāng)個(gè)參考。1. 全屏失效的表現(xiàn)與根因拆解1.1 四種典型失效現(xiàn)象先對號入座“全屏失效”這四個(gè)字其實(shí)很籠統(tǒng)實(shí)際開發(fā)中會(huì)遇到完全不同的表現(xiàn)。我整理了一下大部分情況可以歸為下面四類第一種點(diǎn)擊全屏按鈕完全沒反應(yīng)。視頻正常播放按鈕也能點(diǎn)但點(diǎn)了之后頁面紋絲不動(dòng)。這種通常不是H5代碼的問題是鴻蒙側(cè)Web組件壓根沒把全屏能力授權(quán)給網(wǎng)頁。第二種進(jìn)入全屏后黑屏但有聲音。這個(gè)最迷惑人。看起來像進(jìn)入了全屏狀態(tài)但畫面沒了。問題大概率出在視頻解碼和渲染環(huán)節(jié)比如媒體權(quán)限沒開、視頻編碼格式系統(tǒng)不支持、或者Web組件的媒體渲染通道被其它上層組件遮擋。第三種全屏只能堅(jiān)持一兩秒然后自動(dòng)退出。這個(gè)和全屏生命周期有關(guān)。H5頁面調(diào)用requestFullscreen之后會(huì)觸發(fā)fullscreenchange事件鴻蒙側(cè)Web組件也會(huì)回調(diào)全屏狀態(tài)。如果這個(gè)回調(diào)時(shí)機(jī)和窗口旋轉(zhuǎn)邏輯沖突就可能出現(xiàn)“剛進(jìn)入全屏就被打斷”的現(xiàn)象。第四種視頻畫面放大了但狀態(tài)欄和導(dǎo)航欄還在看起來不是真正的沉浸式全屏。這種情況屬于半全屏根本原因是窗口沒有切換成沉浸式布局頁面元素占了全屏但是系統(tǒng)欄還懸浮在上面。把現(xiàn)象對準(zhǔn)之后再動(dòng)手改代碼會(huì)省很多時(shí)間。千萬不要一上來就各種加參數(shù)、改旋轉(zhuǎn)邏輯先搞清楚屬于哪一種。1.2 全屏是一條鏈路不是video標(biāo)簽一個(gè)點(diǎn)的事很多同學(xué)容易把全屏理解成“網(wǎng)頁自己把自己放大了”其實(shí)在鴻蒙Web組件里全屏是一整條鏈路共同協(xié)作的結(jié)果。簡化一下這條鏈路H5頁面的video標(biāo)簽或者document元素調(diào)用Fullscreen API請求進(jìn)入全屏。Web內(nèi)核ArkWeb基于Chromium攔截到這個(gè)請求判斷當(dāng)前Web組件是否允許全屏。如果允許就回調(diào)給鴻蒙側(cè)宿主應(yīng)用比如觸發(fā)onFullScreenChange事件。接著鴻蒙側(cè)應(yīng)用要配合做三件事把宿主窗口旋轉(zhuǎn)到橫屏或者保持當(dāng)前方向看產(chǎn)品需求、隱藏狀態(tài)欄和導(dǎo)航欄進(jìn)入沉浸式布局、讓W(xué)eb組件占滿整個(gè)窗口。最后全屏退出的時(shí)候還要反向執(zhí)行一遍恢復(fù)窗口方向和系統(tǒng)欄。這條鏈路里任何一環(huán)斷了表現(xiàn)出來的就是各種“失效”。比如第一環(huán)沒授權(quán)就是點(diǎn)擊沒反應(yīng)最后一環(huán)沒執(zhí)行就是半全屏如果旋轉(zhuǎn)時(shí)機(jī)和全屏回調(diào)時(shí)機(jī)沖突就會(huì)出現(xiàn)閃退。打個(gè)比方舞臺(tái)上的演員視頻準(zhǔn)備開演了但是燈控全屏權(quán)限沒給信號舞臺(tái)升降窗口切換沒動(dòng)音響控制媒體權(quán)限也沒接上那這場戲肯定是演不起來的。所以在排查的時(shí)候一定要順著鏈路一段一段檢查而不是只盯著視頻標(biāo)簽看。1.3 為什么鴻蒙Web組件默認(rèn)不放行全屏有一個(gè)問題值得多說一句為什么網(wǎng)頁在瀏覽器里全屏好好的放進(jìn)鴻蒙Web組件就要額外授權(quán)因?yàn)閃eb組件本身是宿主應(yīng)用的一部分網(wǎng)頁請求全屏本質(zhì)上是在請求“脫離普通頁面展示模式”把整個(gè)應(yīng)用窗口的控制權(quán)臨時(shí)交給網(wǎng)頁。這對宿主應(yīng)用來說是一件需要明確授權(quán)的事情。你可以想象一下如果網(wǎng)頁能隨意全屏、隨意旋轉(zhuǎn)、隨意隱藏系統(tǒng)欄那用戶很容易被誘導(dǎo)明明在看內(nèi)容網(wǎng)頁某個(gè)彈窗一點(diǎn)就切到全屏狀態(tài)欄沒了退出按鈕藏在角落里。這種體驗(yàn)和安全都是有問題的。所以鴻蒙ArkWeb延續(xù)了Chromium內(nèi)核“宿主授權(quán)”的設(shè)計(jì)思路。Web組件有一個(gè)明確的屬性開關(guān)默認(rèn)關(guān)閉開發(fā)者確認(rèn)自己的業(yè)務(wù)需要承載全屏視頻或者全屏游戲頁面時(shí)再顯式打開。老Android開發(fā)者看到這個(gè)設(shè)計(jì)應(yīng)該很眼熟和Android WebView里onShowCustomView那套機(jī)制是同一個(gè)理念只是鴻蒙把它收斂成了一個(gè)配置項(xiàng)加一組回調(diào)用起來更直接。2. 鴻蒙側(cè)Web組件的權(quán)限配置先把門打開2.1 一分鐘搭建帶Web組件的基線和四個(gè)關(guān)鍵開關(guān)先把最基礎(chǔ)的工程配置寫好。下面的代碼是一個(gè)帶Web組件的頁面可以直接跑。重點(diǎn)看四個(gè)屬性javaScriptAccess、domStorageAccess、mediaAccess、allowFullScreen。import web from ohos.web.webview; Entry Component struct VideoWebPage { controller: web.WebviewController new web.WebviewController(); build() { Column() { Web({ src: https://your-domain.com/video.html, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .mediaAccess(true) .allowFullScreen(true) } .width(100%) .height(100%) } }這四個(gè)開關(guān)的職責(zé)要弄清楚不然以后調(diào)別的視頻問題還會(huì)懵。javaScriptAccess控制網(wǎng)頁腳本執(zhí)行沒有它頁面里的JS邏輯都跑不起來。domStorageAccess控制localStorage、sessionStorage和IndexedDB很多播放器腳本會(huì)往本地存播放進(jìn)度、音量設(shè)置、靜音狀態(tài)不開放這個(gè)播放器初始化可能異常。mediaAccess管理音視頻采集和播放權(quán)限視頻能不能出聲、畫面能不能渲染它說了算。allowFullScreen就是上面講的全屏總開關(guān)。實(shí)際開發(fā)里mediaAccess這個(gè)最容易被漏掉。很多時(shí)候視頻能播、聲音能出來是因?yàn)槊襟w權(quán)限在Web組件層面沒有限制但某些編碼格式或者特殊播放邏輯會(huì)額外需要這個(gè)授權(quán)。我的建議是做視頻類頁面這四個(gè)開關(guān)全部打開省得后面一個(gè)一個(gè)踩。2.2 全屏事件回調(diào)進(jìn)入和退出時(shí)要處理的窗口邏輯Web組件只是打開了全屏的“門”真正讓用戶覺得“全屏成功”的是后面的窗口配合。鴻蒙側(cè)需要監(jiān)聽全屏事件在進(jìn)入全屏?xí)r旋轉(zhuǎn)窗口、隱藏系統(tǒng)欄在退出全屏?xí)r恢復(fù)原狀。下面是一段典型的處理邏輯配合前面那個(gè)基礎(chǔ)頁面import web from ohos.web.webview; import window from ohos.window; import { BusinessError } from ohos.base; Entry Component struct VideoWebPage { controller: web.WebviewController new web.WebviewController(); private mainWindow: window.Window | null null; aboutToAppear() { window.getLastWindow(getContext(this)).then((mainWindow: window.Window) { this.mainWindow mainWindow; }).catch((err: BusinessError) { console.error(getLastWindow failed, code: err.code , msg: err.message); }); } build() { Column() { Web({ src: https://your-domain.com/video.html, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .mediaAccess(true) .allowFullScreen(true) .onFullScreenChange((event) { if (event.isEnterFullScreen) { this.enterFullScreen(); } else { this.exitFullScreen(); } }) } .width(100%) .height(100%) } private enterFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.LANDSCAPE); this.mainWindow.setWindowLayoutFullScreen(true); this.mainWindow.setWindowSystemBarEnable([]); } private exitFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.PORTRAIT); this.mainWindow.setWindowLayoutFullScreen(false); this.mainWindow.setWindowSystemBarEnable([status, navigation]); } }這里有一個(gè)細(xì)節(jié)要強(qiáng)調(diào)全屏方向不要自己寫死。H5頁面里的視頻可能橫屏、可能豎屏視頻內(nèi)容決定全屏布局鴻蒙側(cè)宿主應(yīng)用只能配合執(zhí)行不能替網(wǎng)頁做決定。所以我上面示例用了橫屏只是演示窗口操作能力。真實(shí)業(yè)務(wù)中應(yīng)該通過判斷event對象里帶的信息或者和前端約好方向策略再?zèng)Q定旋轉(zhuǎn)到哪個(gè)方向。2.3 頁面退出和路由跳轉(zhuǎn)一個(gè)容易忽略的全屏恢復(fù)很多團(tuán)隊(duì)在調(diào)試的時(shí)候視頻全屏是好的但退出視頻頁面時(shí)會(huì)出問題明明退出了當(dāng)前頁面狀態(tài)欄還是隱藏的或者上一個(gè)頁面變成了橫屏。這個(gè)問題的本質(zhì)是頁面生命周期和全屏生命周期沒有同步處理。正確做法是在頁面銷毀或者隱藏時(shí)主動(dòng)調(diào)用Web組件的退出全屏接口把狀態(tài)恢復(fù)干凈。aboutToDisappear() { this.exitFullScreen(); this.controller.exitFullScreen(); }如果你用的是Navigation導(dǎo)航頁面通過navigateTo跳轉(zhuǎn)目標(biāo)頁進(jìn)入后上一個(gè)頁面仍然存活只是被覆蓋。這種時(shí)候被覆蓋頁面里的Web組件如果還處于全屏狀態(tài)就可能出現(xiàn)窗口狀態(tài)錯(cuò)亂。建議在onPageHide里也補(bǔ)上同樣的退出邏輯。另外應(yīng)用退到后臺(tái)之前也應(yīng)當(dāng)處理一下不然從后臺(tái)回來可能還是全屏狀態(tài)用戶視角會(huì)非常困惑。還有一個(gè)多實(shí)例的坑如果你的項(xiàng)目里同一個(gè)頁面被多次push或者Web組件所在的組件被條件渲染銷毀重建全屏狀態(tài)會(huì)跟著實(shí)例一起丟。所以保存窗口引用的操作要跟著頁面生命周期走不要在頁面銷毀后還去調(diào)用已經(jīng)失效的窗口引用。3. H5頁面?zhèn)鹊募嫒輽z查與修復(fù)3.1 video標(biāo)簽上的playsinline屬性很多時(shí)候全屏失效的源頭在這兒鴻蒙Web組件的權(quán)限都打開了窗口配合也寫了但視頻全屏還是有問題。這時(shí)候就該回頭檢查H5頁面本身了。先看video標(biāo)簽。移動(dòng)端網(wǎng)頁播放視頻有一個(gè)特別的屬性叫playsinline部分舊內(nèi)核還需要webkit-playsinline。它的作用是告訴瀏覽器別把視頻彈出去用系統(tǒng)播放器就在頁面內(nèi)聯(lián)播放。為什么不設(shè)置它會(huì)導(dǎo)致全屏失效因?yàn)橐坏┫到y(tǒng)播放器接管視頻HTML5的Fullscreen API路徑就被繞開了。你點(diǎn)頁面上的全屏按鈕觸發(fā)的可能是Native播放器的那套全屏邏輯而不是網(wǎng)頁自身的requestFullscreen調(diào)用。鴻蒙側(cè)Web組件監(jiān)聽不到預(yù)期的事件自然沒法配合做窗口旋轉(zhuǎn)表現(xiàn)就是“全屏不了”或者行為異常。建議video標(biāo)簽加上如下配置video idvideoPlayer srchttps://your-domain.com/video.mp4 controls playsinline webkit-playsinline preloadmetadata x5-video-player-typeh5 x5-video-player-fullscreentrue /video關(guān)于x5-video-player-type和x5-video-player-fullscreen要說明一下這是騰訊X5內(nèi)核的歷史遺留參數(shù)在鴻蒙ArkWeb這種Chromium內(nèi)核下不會(huì)生效但寫了也不會(huì)報(bào)錯(cuò)。如果你這個(gè)頁面還要復(fù)用在其它安卓殼里建議保留。如果只跑鴻蒙Web組件刪不刪影響不大。3.2 Fullscreen API的標(biāo)準(zhǔn)寫法和手勢限制全屏請求的代碼雖然簡單但兼容性寫法還是有講究。不少老頁面還在用webkitRequestFullscreen或者webkitEnterFullScreenArkWeb作為Chromium系內(nèi)核標(biāo)準(zhǔn)接口是requestFullscreen。為了多端復(fù)用可以做一個(gè)兼容函數(shù)function enterFullscreen(element) { if (element.requestFullscreen) { element.requestFullscreen(); } else if (element.webkitRequestFullscreen) { element.webkitRequestFullscreen(); } else if (element.msRequestFullscreen) { element.msRequestFullscreen(); } }另一個(gè)很關(guān)鍵的限制是“用戶手勢”。Fullscreen API要求必須有用戶激活user activation才能調(diào)用也就是說requestFullscreen必須在用戶的點(diǎn)擊、觸摸等事件處理函數(shù)里執(zhí)行。你不能在視頻加載完成后的loadedmetadata回調(diào)里全屏也不能在定時(shí)器里全屏。如果違反這個(gè)規(guī)則瀏覽器會(huì)拋異常API can only be initiated by a user gesture。排查的時(shí)候如果看到webview控制臺(tái)輸出這類報(bào)錯(cuò)先檢查是不是頁面的全屏按鈕用了異步邏輯比如點(diǎn)擊之后先發(fā)一個(gè)埋點(diǎn)請求然后在埋點(diǎn)回調(diào)里再去調(diào)全屏。這樣一頓操作用戶激活上下文已經(jīng)丟了全屏必然失敗。3.3 在H5側(cè)監(jiān)聽fullscreenchange快速判斷全屏事件有沒有觸發(fā)當(dāng)排查陷入僵局時(shí)我習(xí)慣在H5側(cè)加監(jiān)聽器把全屏事件的發(fā)生過程完整打印出來。這一步能快速區(qū)分問題在H5側(cè)還是鴻蒙側(cè)。document.addEventListener(fullscreenchange, function() { console.log(fullscreenchange, isFullScreen:, document.fullscreenElement ? yes : no); console.log(fullscreenElement:, document.fullscreenElement ? document.fullscreenElement.tagName : null); }); document.addEventListener(webkitfullscreenchange, function() { console.log(webkitfullscreenchange, isFullScreen:, document.webkitFullscreenElement ? yes : no); });如果點(diǎn)擊全屏按鈕后控制臺(tái)根本沒有fullscreenchange日志說明H5側(cè)全屏請求沒發(fā)出來或者被瀏覽器攔了。如果有日志說明H5側(cè)問題不大需要到鴻蒙側(cè)繼續(xù)查。3.4 監(jiān)聽全屏事件時(shí)要注意時(shí)序問題還有一個(gè)容易被忽略的坑退出全屏操作會(huì)按“后進(jìn)先出”的順序逐個(gè)觸發(fā)。很多播放器自己會(huì)去調(diào)exitFullscreen頁面腳本在fullscreenchange里也保存了一個(gè)狀態(tài)。如果同時(shí)有兩個(gè)全屏請求疊在一起退一層還會(huì)剩一層。這就是為什么有些頁面“第一次退出全屏后頁面還是全屏的”。視頻類頁面尤其容易出現(xiàn)這種狀態(tài)因?yàn)関ideo自身的controls全屏按鈕和頁面自定義的全屏按鈕會(huì)分別走各自的邏輯。建議在H5側(cè)維護(hù)一個(gè)全屏狀態(tài)隊(duì)列或者干脆統(tǒng)一由頁面自定義全屏按鈕接管把原生controls里的全屏功能用controlsListnofullscreen關(guān)掉。video controls controlsListnofullscreen playsinline/video這樣能避免用戶一邊點(diǎn)系統(tǒng)自帶的全屏按鈕一邊點(diǎn)頁面的全屏按鈕導(dǎo)致狀態(tài)錯(cuò)亂。4. 完整可運(yùn)行的方案從H5測試頁到鴻蒙容器4.1 一個(gè)可以直接用來復(fù)現(xiàn)問題的H5測試頁如果你和我一樣喜歡“最小可復(fù)現(xiàn)demo”的工作方式可以做一個(gè)非常干凈的測試頁。它只有一個(gè)video標(biāo)簽、一個(gè)自定義全屏按鈕并把所有全屏相關(guān)事件打印出來。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title鴻蒙Web組件全屏測試/title style body { margin: 0; background: #222; } .player { width: 100%; } video { width: 100%; background: #000; } .full-btn { display: block; width: 200px; margin: 20px auto; padding: 10px 0; text-align: center; background: #ff6600; color: #fff; border: none; border-radius: 6px; } /style /head body video idv classplayer controls playsinline webkit-playsinline preloadmetadata source srchttps://media.w3.org/2010/05/sintel/trailer.mp4 typevideo/mp4 /video button classfull-btn onclickfullscreenFn()全屏播放/button script function fullscreenFn() { const v document.getElementById(v); if (v.requestFullscreen) { v.requestFullscreen(); } else if (v.webkitRequestFullscreen) { v.webkitRequestFullscreen(); } else { console.log(no requestFullscreen support); } } document.addEventListener(fullscreenchange, function() { console.log(fullscreenchange, fullscreenElement:, document.fullscreenElement ? document.fullscreenElement.tagName : null); }); /script /body /html這個(gè)頁面里的https://media.w3.org/2010/05/sintel/trailer.mp4是W3C提供的公開測試視頻可以放心用。把這個(gè)HTML放到你的H5服務(wù)器上或者把它作為rawfile文件內(nèi)置到鴻蒙應(yīng)用里便于離線復(fù)現(xiàn)。4.2 鴻蒙側(cè)的完整容器代碼接下來是鴻蒙側(cè)的完整代碼。我習(xí)慣把窗口操作封裝成一個(gè)類這樣頁面代碼會(huì)干凈很多。下面的示例是所有代碼都寫在頁面組件里但邏輯清楚適合當(dāng)模板。import web from ohos.web.webview; import window from ohos.window; import { BusinessError } from ohos.base; Entry Component struct VideoWebPage { controller: web.WebviewController new web.WebviewController(); private mainWindow: window.Window | null null; aboutToAppear() { window.getLastWindow(getContext(this)).then((mainWindow: window.Window) { this.mainWindow mainWindow; }).catch((err: BusinessError) { console.error(getLastWindow failed, code: err.code , msg: err.message); }); } aboutToDisappear() { this.exitFullScreen(); } build() { Column() { Web({ src: https://your-domain.com/video.html, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .mediaAccess(true) .allowFullScreen(true) .fileAccess(true) .onFullScreenChange((event) { if (event.isEnterFullScreen) { this.enterFullScreen(); } else { this.exitFullScreen(); } }) } .width(100%) .height(100%) } private enterFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.LANDSCAPE); this.mainWindow.setWindowLayoutFullScreen(true); this.mainWindow.setWindowSystemBarEnable([]); } private exitFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.PORTRAIT); this.mainWindow.setWindowLayoutFullScreen(false); this.mainWindow.setWindowSystemBarEnable([status, navigation]); } }有一點(diǎn)要提醒如果你把測試頁面內(nèi)置到了應(yīng)用資源里用$rawfile(video.html)作為src那么頁面里引用同目錄下的視頻資源也需要放進(jìn)去。不過我的建議是測試階段直接用線上H5地址因?yàn)檫@樣能一并驗(yàn)證網(wǎng)絡(luò)權(quán)限、域名校驗(yàn)、HTTPS證書等真實(shí)場景的問題。4.3 實(shí)操驗(yàn)證按順序測五個(gè)場景代碼就位之后按下面的順序驗(yàn)證每個(gè)場景單獨(dú)測避免互相干擾。第一個(gè)場景直接加載測試頁視頻能播放但不點(diǎn)全屏預(yù)期是正常內(nèi)聯(lián)播放。如果不能播放先查網(wǎng)絡(luò)權(quán)限和視頻編碼。第二個(gè)場景點(diǎn)擊頁面上的自定義全屏按鈕預(yù)期是進(jìn)入橫屏全屏、狀態(tài)欄和導(dǎo)航欄隱藏。如果沒反應(yīng)檢查鴻蒙側(cè)allowFullScreen有沒有開以及H5控制臺(tái)有沒有全屏報(bào)錯(cuò)。第三個(gè)場景全屏狀態(tài)下旋轉(zhuǎn)設(shè)備方向預(yù)期頁面跟隨旋轉(zhuǎn)視頻保持全屏。如果不跟隨可能是窗口方向鎖死了。第四個(gè)場景點(diǎn)擊系統(tǒng)的退出全屏按鈕或按返回鍵預(yù)期退出全屏、恢復(fù)豎屏和系統(tǒng)欄。如果恢復(fù)不完整檢查exitFullScreen里窗口恢復(fù)邏輯有沒有執(zhí)行。第五個(gè)場景全屏狀態(tài)下退到后臺(tái)再回前臺(tái)預(yù)期保持全屏或者自動(dòng)退出全屏但不能出現(xiàn)狀態(tài)欄丟失或者頁面變形。這一步很多團(tuán)隊(duì)會(huì)遺漏但用戶實(shí)際使用中非常常見。這五個(gè)場景全部通過基本可以認(rèn)為全屏鏈路是通的。剩下的就是和產(chǎn)品確認(rèn)某些頁面是否需要一直橫屏某些頁面是否需要禁止旋轉(zhuǎn)這些屬于產(chǎn)品策略代碼上都已經(jīng)具備調(diào)整能力。5. 常見問題速查表與實(shí)戰(zhàn)避坑5.1 問題速查表把這次排查中遇到的典型問題整理成一個(gè)速查表方便后續(xù)團(tuán)隊(duì)快速定位?，F(xiàn)象可能原因解決方案點(diǎn)擊全屏按鈕沒反應(yīng)鴻蒙側(cè)allowFullScreen未開啟Web組件添加.allowFullScreen(true)全屏黑屏但有聲音媒體權(quán)限未開或視頻編碼不支持添加.mediaAccess(true)檢查視頻編碼換h264測試全屏一兩秒自動(dòng)退出全屏事件回調(diào)與窗口旋轉(zhuǎn)時(shí)序沖突在onFullScreenChange里統(tǒng)一處理避免H5側(cè)重復(fù)調(diào)用exitFullscreen畫面半全屏但系統(tǒng)欄還在未進(jìn)入沉浸式布局調(diào)用setWindowLayoutFullScreen(true)并隱藏系統(tǒng)欄退出全屏后頁面還是全屏多層全屏請求疊加未清空用controlsListnofullscreen屏蔽原生全屏按鈕統(tǒng)一走頁面全屏邏輯返回上個(gè)頁面橫屏回不來頁面銷毀時(shí)沒恢復(fù)窗口狀態(tài)aboutToDisappear或onPageHide里主動(dòng)恢復(fù)窗口方向和系統(tǒng)欄視頻彈出系統(tǒng)播放器無法內(nèi)聯(lián)缺少playsinline屬性video標(biāo)簽添加playsinline webkit-playsinline5.2 前后臺(tái)切換和全屏狀態(tài)管理應(yīng)用退到后臺(tái)這個(gè)場景是實(shí)際使用中反饋?zhàn)疃嗟膯栴}之一。用戶在全屏狀態(tài)下按Home鍵退到桌面再回到應(yīng)用發(fā)現(xiàn)界面是橫屏的狀態(tài)欄卻回來了或者視頻變成一個(gè)小窗。我的建議是做一個(gè)統(tǒng)一的全屏狀態(tài)管理器。這個(gè)模塊不在本文展開寫了核心思路就是進(jìn)入全屏?xí)r保存當(dāng)前狀態(tài)頁面onHide時(shí)根據(jù)狀態(tài)決定是否退出全屏頁面重新onShow時(shí)再恢復(fù)。如果你不想做這么重最簡單粗暴的方案就是監(jiān)聽?wèi)?yīng)用前后臺(tái)狀態(tài)退后臺(tái)一律退出全屏。雖然損失一點(diǎn)體驗(yàn)但至少狀態(tài)不會(huì)錯(cuò)亂。還有一個(gè)細(xì)節(jié)Web組件的onFullScreenChange回調(diào)里event.isEnterFullScreen在不同API版本上可能字段名有差異。舊版本的ArkWeb用onFullScreen回調(diào)只在進(jìn)入全屏?xí)r觸發(fā)一次。如果你們的SDK比較老看到文檔里沒有onFullScreenChange就換成onFullScreen加exitFullScreen()手動(dòng)退出邏輯是一樣的只是監(jiān)聽方式不同。5.3 調(diào)試?yán)鞔蜷_Web調(diào)試和日志過濾排查這類問題一定要把Web組件的調(diào)試能力打開。鴻蒙Web組件有一個(gè)setWebDebuggingAccess(true)屬性設(shè)置之后就可以通過一些調(diào)試工具去查看網(wǎng)頁控制臺(tái)和DOM狀態(tài)。Web({ src: https://your-domain.com/video.html, controller: this.controller }) .setWebDebuggingAccess(true)打開調(diào)試之后結(jié)合DevEco Studio的Log窗口過濾關(guān)鍵字ArkWeb、FullScreen、JSFullScreen可以看到網(wǎng)頁和Web組件的關(guān)鍵事件。這里有個(gè)經(jīng)驗(yàn)很多全屏問題在網(wǎng)頁控制臺(tái)里其實(shí)是有報(bào)錯(cuò)信息的只是鴻蒙應(yīng)用的日志里不顯眼。我遇到過最典型的就是requestFullscreen() must be called from a user gesture這種報(bào)錯(cuò)信息如果不看網(wǎng)頁控制臺(tái)靠猜的話能猜一個(gè)下午。5.4 多端復(fù)用場景把全屏能力封裝成橋接接口現(xiàn)在很多團(tuán)隊(duì)都在做多端復(fù)用同一套H5頁面既要跑鴻蒙App又要跑小程序還要兼容瀏覽器。這種場景下全屏邏輯如果直接寫在頁面腳本里到了各端還要單獨(dú)適配。更合理的做法是在H5側(cè)定義一個(gè)統(tǒng)一的全屏能力接口由各端的宿主容器實(shí)現(xiàn)。舉個(gè)例子你可以約定一個(gè)window.CapabilityBridge對象暴露playFullscreen(videoElement)和exitFullscreen()兩個(gè)方法。鴻蒙端在網(wǎng)頁加載前注入實(shí)現(xiàn)內(nèi)部調(diào)用全屏API并配合窗口旋轉(zhuǎn)小程序端注入自己的一套實(shí)現(xiàn)。這樣H5業(yè)務(wù)代碼只需要調(diào)用CapabilityBridge.playFullscreen()不用關(guān)心底層容器差異。這個(gè)思路同樣適用于其它Web組件能力比如鍵盤彈起問題。熱搜詞里提到“app內(nèi)嵌h5頁面點(diǎn)擊input自動(dòng)滑動(dòng)到對應(yīng)input顯示鍵盤”這類問題的本質(zhì)也是Web組件與原生輸入法的交互鏈路。把這類交互統(tǒng)一收斂到橋接層比在每個(gè)頁面上打補(bǔ)丁要可靠得多。5.5 最后再說一個(gè)容易被忽略的媒體權(quán)限細(xì)節(jié)排查全屏問題的時(shí)候還有一個(gè)隱藏條件容易被漏掉應(yīng)用本身的媒體權(quán)限聲明。如果在module.json5里沒有聲明ohos.permission.MICROPHONE或者其它媒體相關(guān)權(quán)限部分機(jī)型在特定場景下會(huì)導(dǎo)致Web組件內(nèi)部媒體模塊初始化異常。表現(xiàn)就是視頻能播但全屏后的媒體渲染會(huì)出問題。如果你的測試機(jī)恰好是某幾個(gè)特定型號復(fù)現(xiàn)黑屏建議先檢查權(quán)限聲明再檢查代碼邏輯。權(quán)限聲明這一步雖然是基礎(chǔ)工作但很多“偶現(xiàn)”問題最后都栽在它上面。結(jié)尾這篇文章里的代碼和排查思路是我在多輪實(shí)際調(diào)試中沉淀下來的。如果你也遇到類似的全屏失效問題我強(qiáng)烈建議先做兩件事打開Web調(diào)試給H5頁面加上fullscreenchange監(jiān)聽打印事件日志判斷問題出在H5層還是鴻蒙層對照速查表快速檢查鴻蒙側(cè)Web組件的四個(gè)關(guān)鍵開關(guān)和窗口處理邏輯。九成的問題都能在十分鐘內(nèi)定位到具體環(huán)節(jié)。最后再分享一個(gè)提高效率的小技巧做一套全屏測試playground頁面把fullscreenchange、webkitfullscreenchange、resize事件全部打印出來把鴻蒙側(cè)的全屏回調(diào)也打印出來。以后不管是新項(xiàng)目還是接手的舊項(xiàng)目遇到類似H5與Web組件的交互問題直接拿這套頁面去對照比臨時(shí)寫測試代碼快得多。全屏問題看著唬人拆開來看就是權(quán)限、生命周期、窗口狀態(tài)這幾個(gè)環(huán)節(jié)的配合理順了就再也不會(huì)被它卡住了。 鴻蒙Web組件中H5視頻全屏失效的排查與修復(fù)實(shí)踐
先聊一個(gè)查了半天的坑?？蛻裟沁吥螟櫭蓱?yīng)用的Web組件加載H5頁面頁面里放了一段視頻網(wǎng)頁在手機(jī)瀏覽器里打開一切正常點(diǎn)全屏按鈕就能橫屏播放。放進(jìn)鴻蒙應(yīng)用里視頻能播、聲音也有就是點(diǎn)全屏沒反應(yīng)或者閃一下就退出來偶爾還會(huì)出現(xiàn)黑屏但有聲的怪狀態(tài)。查日志、翻文檔、各種試錯(cuò)之后問題基本鎖定在三個(gè)層面鴻蒙Web組件的全屏權(quán)限沒開、H5頁面video標(biāo)簽和全屏API的寫法不兼容、還有全屏生命周期回調(diào)里沒有同步處理窗口旋轉(zhuǎn)和沉浸式布局。這篇文章我把排查過程和修復(fù)方案完整寫一遍給做鴻蒙應(yīng)用內(nèi)嵌H5業(yè)務(wù)的同學(xué)當(dāng)個(gè)參考。1. 全屏失效的表現(xiàn)與根因拆解1.1 四種典型失效現(xiàn)象先對號入座“全屏失效”這四個(gè)字其實(shí)很籠統(tǒng)實(shí)際開發(fā)中會(huì)遇到完全不同的表現(xiàn)。我整理了一下大部分情況可以歸為下面四類第一種點(diǎn)擊全屏按鈕完全沒反應(yīng)。視頻正常播放按鈕也能點(diǎn)但點(diǎn)了之后頁面紋絲不動(dòng)。這種通常不是H5代碼的問題是鴻蒙側(cè)Web組件壓根沒把全屏能力授權(quán)給網(wǎng)頁。第二種進(jìn)入全屏后黑屏但有聲音。這個(gè)最迷惑人。看起來像進(jìn)入了全屏狀態(tài)但畫面沒了。問題大概率出在視頻解碼和渲染環(huán)節(jié)比如媒體權(quán)限沒開、視頻編碼格式系統(tǒng)不支持、或者Web組件的媒體渲染通道被其它上層組件遮擋。第三種全屏只能堅(jiān)持一兩秒然后自動(dòng)退出。這個(gè)和全屏生命周期有關(guān)。H5頁面調(diào)用requestFullscreen之后會(huì)觸發(fā)fullscreenchange事件鴻蒙側(cè)Web組件也會(huì)回調(diào)全屏狀態(tài)。如果這個(gè)回調(diào)時(shí)機(jī)和窗口旋轉(zhuǎn)邏輯沖突就可能出現(xiàn)“剛進(jìn)入全屏就被打斷”的現(xiàn)象。第四種視頻畫面放大了但狀態(tài)欄和導(dǎo)航欄還在看起來不是真正的沉浸式全屏。這種情況屬于半全屏根本原因是窗口沒有切換成沉浸式布局頁面元素占了全屏但是系統(tǒng)欄還懸浮在上面。把現(xiàn)象對準(zhǔn)之后再動(dòng)手改代碼會(huì)省很多時(shí)間。千萬不要一上來就各種加參數(shù)、改旋轉(zhuǎn)邏輯先搞清楚屬于哪一種。1.2 全屏是一條鏈路不是video標(biāo)簽一個(gè)點(diǎn)的事很多同學(xué)容易把全屏理解成“網(wǎng)頁自己把自己放大了”其實(shí)在鴻蒙Web組件里全屏是一整條鏈路共同協(xié)作的結(jié)果。簡化一下這條鏈路H5頁面的video標(biāo)簽或者document元素調(diào)用Fullscreen API請求進(jìn)入全屏。Web內(nèi)核ArkWeb基于Chromium攔截到這個(gè)請求判斷當(dāng)前Web組件是否允許全屏。如果允許就回調(diào)給鴻蒙側(cè)宿主應(yīng)用比如觸發(fā)onFullScreenChange事件。接著鴻蒙側(cè)應(yīng)用要配合做三件事把宿主窗口旋轉(zhuǎn)到橫屏或者保持當(dāng)前方向看產(chǎn)品需求、隱藏狀態(tài)欄和導(dǎo)航欄進(jìn)入沉浸式布局、讓W(xué)eb組件占滿整個(gè)窗口。最后全屏退出的時(shí)候還要反向執(zhí)行一遍恢復(fù)窗口方向和系統(tǒng)欄。這條鏈路里任何一環(huán)斷了表現(xiàn)出來的就是各種“失效”。比如第一環(huán)沒授權(quán)就是點(diǎn)擊沒反應(yīng)最后一環(huán)沒執(zhí)行就是半全屏如果旋轉(zhuǎn)時(shí)機(jī)和全屏回調(diào)時(shí)機(jī)沖突就會(huì)出現(xiàn)閃退。打個(gè)比方舞臺(tái)上的演員視頻準(zhǔn)備開演了但是燈控全屏權(quán)限沒給信號舞臺(tái)升降窗口切換沒動(dòng)音響控制媒體權(quán)限也沒接上那這場戲肯定是演不起來的。所以在排查的時(shí)候一定要順著鏈路一段一段檢查而不是只盯著視頻標(biāo)簽看。1.3 為什么鴻蒙Web組件默認(rèn)不放行全屏有一個(gè)問題值得多說一句為什么網(wǎng)頁在瀏覽器里全屏好好的放進(jìn)鴻蒙Web組件就要額外授權(quán)因?yàn)閃eb組件本身是宿主應(yīng)用的一部分網(wǎng)頁請求全屏本質(zhì)上是在請求“脫離普通頁面展示模式”把整個(gè)應(yīng)用窗口的控制權(quán)臨時(shí)交給網(wǎng)頁。這對宿主應(yīng)用來說是一件需要明確授權(quán)的事情。你可以想象一下如果網(wǎng)頁能隨意全屏、隨意旋轉(zhuǎn)、隨意隱藏系統(tǒng)欄那用戶很容易被誘導(dǎo)明明在看內(nèi)容網(wǎng)頁某個(gè)彈窗一點(diǎn)就切到全屏狀態(tài)欄沒了退出按鈕藏在角落里。這種體驗(yàn)和安全都是有問題的。所以鴻蒙ArkWeb延續(xù)了Chromium內(nèi)核“宿主授權(quán)”的設(shè)計(jì)思路。Web組件有一個(gè)明確的屬性開關(guān)默認(rèn)關(guān)閉開發(fā)者確認(rèn)自己的業(yè)務(wù)需要承載全屏視頻或者全屏游戲頁面時(shí)再顯式打開。老Android開發(fā)者看到這個(gè)設(shè)計(jì)應(yīng)該很眼熟和Android WebView里onShowCustomView那套機(jī)制是同一個(gè)理念只是鴻蒙把它收斂成了一個(gè)配置項(xiàng)加一組回調(diào)用起來更直接。2. 鴻蒙側(cè)Web組件的權(quán)限配置先把門打開2.1 一分鐘搭建帶Web組件的基線和四個(gè)關(guān)鍵開關(guān)先把最基礎(chǔ)的工程配置寫好。下面的代碼是一個(gè)帶Web組件的頁面可以直接跑。重點(diǎn)看四個(gè)屬性javaScriptAccess、domStorageAccess、mediaAccess、allowFullScreen。import web from ohos.web.webview; Entry Component struct VideoWebPage { controller: web.WebviewController new web.WebviewController(); build() { Column() { Web({ src: https://your-domain.com/video.html, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .mediaAccess(true) .allowFullScreen(true) } .width(100%) .height(100%) } }這四個(gè)開關(guān)的職責(zé)要弄清楚不然以后調(diào)別的視頻問題還會(huì)懵。javaScriptAccess控制網(wǎng)頁腳本執(zhí)行沒有它頁面里的JS邏輯都跑不起來。domStorageAccess控制localStorage、sessionStorage和IndexedDB很多播放器腳本會(huì)往本地存播放進(jìn)度、音量設(shè)置、靜音狀態(tài)不開放這個(gè)播放器初始化可能異常。mediaAccess管理音視頻采集和播放權(quán)限視頻能不能出聲、畫面能不能渲染它說了算。allowFullScreen就是上面講的全屏總開關(guān)。實(shí)際開發(fā)里mediaAccess這個(gè)最容易被漏掉。很多時(shí)候視頻能播、聲音能出來是因?yàn)槊襟w權(quán)限在Web組件層面沒有限制但某些編碼格式或者特殊播放邏輯會(huì)額外需要這個(gè)授權(quán)。我的建議是做視頻類頁面這四個(gè)開關(guān)全部打開省得后面一個(gè)一個(gè)踩。2.2 全屏事件回調(diào)進(jìn)入和退出時(shí)要處理的窗口邏輯Web組件只是打開了全屏的“門”真正讓用戶覺得“全屏成功”的是后面的窗口配合。鴻蒙側(cè)需要監(jiān)聽全屏事件在進(jìn)入全屏?xí)r旋轉(zhuǎn)窗口、隱藏系統(tǒng)欄在退出全屏?xí)r恢復(fù)原狀。下面是一段典型的處理邏輯配合前面那個(gè)基礎(chǔ)頁面import web from ohos.web.webview; import window from ohos.window; import { BusinessError } from ohos.base; Entry Component struct VideoWebPage { controller: web.WebviewController new web.WebviewController(); private mainWindow: window.Window | null null; aboutToAppear() { window.getLastWindow(getContext(this)).then((mainWindow: window.Window) { this.mainWindow mainWindow; }).catch((err: BusinessError) { console.error(getLastWindow failed, code: err.code , msg: err.message); }); } build() { Column() { Web({ src: https://your-domain.com/video.html, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .mediaAccess(true) .allowFullScreen(true) .onFullScreenChange((event) { if (event.isEnterFullScreen) { this.enterFullScreen(); } else { this.exitFullScreen(); } }) } .width(100%) .height(100%) } private enterFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.LANDSCAPE); this.mainWindow.setWindowLayoutFullScreen(true); this.mainWindow.setWindowSystemBarEnable([]); } private exitFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.PORTRAIT); this.mainWindow.setWindowLayoutFullScreen(false); this.mainWindow.setWindowSystemBarEnable([status, navigation]); } }這里有一個(gè)細(xì)節(jié)要強(qiáng)調(diào)全屏方向不要自己寫死。H5頁面里的視頻可能橫屏、可能豎屏視頻內(nèi)容決定全屏布局鴻蒙側(cè)宿主應(yīng)用只能配合執(zhí)行不能替網(wǎng)頁做決定。所以我上面示例用了橫屏只是演示窗口操作能力。真實(shí)業(yè)務(wù)中應(yīng)該通過判斷event對象里帶的信息或者和前端約好方向策略再?zèng)Q定旋轉(zhuǎn)到哪個(gè)方向。2.3 頁面退出和路由跳轉(zhuǎn)一個(gè)容易忽略的全屏恢復(fù)很多團(tuán)隊(duì)在調(diào)試的時(shí)候視頻全屏是好的但退出視頻頁面時(shí)會(huì)出問題明明退出了當(dāng)前頁面狀態(tài)欄還是隱藏的或者上一個(gè)頁面變成了橫屏。這個(gè)問題的本質(zhì)是頁面生命周期和全屏生命周期沒有同步處理。正確做法是在頁面銷毀或者隱藏時(shí)主動(dòng)調(diào)用Web組件的退出全屏接口把狀態(tài)恢復(fù)干凈。aboutToDisappear() { this.exitFullScreen(); this.controller.exitFullScreen(); }如果你用的是Navigation導(dǎo)航頁面通過navigateTo跳轉(zhuǎn)目標(biāo)頁進(jìn)入后上一個(gè)頁面仍然存活只是被覆蓋。這種時(shí)候被覆蓋頁面里的Web組件如果還處于全屏狀態(tài)就可能出現(xiàn)窗口狀態(tài)錯(cuò)亂。建議在onPageHide里也補(bǔ)上同樣的退出邏輯。另外應(yīng)用退到后臺(tái)之前也應(yīng)當(dāng)處理一下不然從后臺(tái)回來可能還是全屏狀態(tài)用戶視角會(huì)非常困惑。還有一個(gè)多實(shí)例的坑如果你的項(xiàng)目里同一個(gè)頁面被多次push或者Web組件所在的組件被條件渲染銷毀重建全屏狀態(tài)會(huì)跟著實(shí)例一起丟。所以保存窗口引用的操作要跟著頁面生命周期走不要在頁面銷毀后還去調(diào)用已經(jīng)失效的窗口引用。3. H5頁面?zhèn)鹊募嫒輽z查與修復(fù)3.1 video標(biāo)簽上的playsinline屬性很多時(shí)候全屏失效的源頭在這兒鴻蒙Web組件的權(quán)限都打開了窗口配合也寫了但視頻全屏還是有問題。這時(shí)候就該回頭檢查H5頁面本身了。先看video標(biāo)簽。移動(dòng)端網(wǎng)頁播放視頻有一個(gè)特別的屬性叫playsinline部分舊內(nèi)核還需要webkit-playsinline。它的作用是告訴瀏覽器別把視頻彈出去用系統(tǒng)播放器就在頁面內(nèi)聯(lián)播放。為什么不設(shè)置它會(huì)導(dǎo)致全屏失效因?yàn)橐坏┫到y(tǒng)播放器接管視頻HTML5的Fullscreen API路徑就被繞開了。你點(diǎn)頁面上的全屏按鈕觸發(fā)的可能是Native播放器的那套全屏邏輯而不是網(wǎng)頁自身的requestFullscreen調(diào)用。鴻蒙側(cè)Web組件監(jiān)聽不到預(yù)期的事件自然沒法配合做窗口旋轉(zhuǎn)表現(xiàn)就是“全屏不了”或者行為異常。建議video標(biāo)簽加上如下配置video idvideoPlayer srchttps://your-domain.com/video.mp4 controls playsinline webkit-playsinline preloadmetadata x5-video-player-typeh5 x5-video-player-fullscreentrue /video關(guān)于x5-video-player-type和x5-video-player-fullscreen要說明一下這是騰訊X5內(nèi)核的歷史遺留參數(shù)在鴻蒙ArkWeb這種Chromium內(nèi)核下不會(huì)生效但寫了也不會(huì)報(bào)錯(cuò)。如果你這個(gè)頁面還要復(fù)用在其它安卓殼里建議保留。如果只跑鴻蒙Web組件刪不刪影響不大。3.2 Fullscreen API的標(biāo)準(zhǔn)寫法和手勢限制全屏請求的代碼雖然簡單但兼容性寫法還是有講究。不少老頁面還在用webkitRequestFullscreen或者webkitEnterFullScreenArkWeb作為Chromium系內(nèi)核標(biāo)準(zhǔn)接口是requestFullscreen。為了多端復(fù)用可以做一個(gè)兼容函數(shù)function enterFullscreen(element) { if (element.requestFullscreen) { element.requestFullscreen(); } else if (element.webkitRequestFullscreen) { element.webkitRequestFullscreen(); } else if (element.msRequestFullscreen) { element.msRequestFullscreen(); } }另一個(gè)很關(guān)鍵的限制是“用戶手勢”。Fullscreen API要求必須有用戶激活user activation才能調(diào)用也就是說requestFullscreen必須在用戶的點(diǎn)擊、觸摸等事件處理函數(shù)里執(zhí)行。你不能在視頻加載完成后的loadedmetadata回調(diào)里全屏也不能在定時(shí)器里全屏。如果違反這個(gè)規(guī)則瀏覽器會(huì)拋異常API can only be initiated by a user gesture。排查的時(shí)候如果看到webview控制臺(tái)輸出這類報(bào)錯(cuò)先檢查是不是頁面的全屏按鈕用了異步邏輯比如點(diǎn)擊之后先發(fā)一個(gè)埋點(diǎn)請求然后在埋點(diǎn)回調(diào)里再去調(diào)全屏。這樣一頓操作用戶激活上下文已經(jīng)丟了全屏必然失敗。3.3 在H5側(cè)監(jiān)聽fullscreenchange快速判斷全屏事件有沒有觸發(fā)當(dāng)排查陷入僵局時(shí)我習(xí)慣在H5側(cè)加監(jiān)聽器把全屏事件的發(fā)生過程完整打印出來。這一步能快速區(qū)分問題在H5側(cè)還是鴻蒙側(cè)。document.addEventListener(fullscreenchange, function() { console.log(fullscreenchange, isFullScreen:, document.fullscreenElement ? yes : no); console.log(fullscreenElement:, document.fullscreenElement ? document.fullscreenElement.tagName : null); }); document.addEventListener(webkitfullscreenchange, function() { console.log(webkitfullscreenchange, isFullScreen:, document.webkitFullscreenElement ? yes : no); });如果點(diǎn)擊全屏按鈕后控制臺(tái)根本沒有fullscreenchange日志說明H5側(cè)全屏請求沒發(fā)出來或者被瀏覽器攔了。如果有日志說明H5側(cè)問題不大需要到鴻蒙側(cè)繼續(xù)查。3.4 監(jiān)聽全屏事件時(shí)要注意時(shí)序問題還有一個(gè)容易被忽略的坑退出全屏操作會(huì)按“后進(jìn)先出”的順序逐個(gè)觸發(fā)。很多播放器自己會(huì)去調(diào)exitFullscreen頁面腳本在fullscreenchange里也保存了一個(gè)狀態(tài)。如果同時(shí)有兩個(gè)全屏請求疊在一起退一層還會(huì)剩一層。這就是為什么有些頁面“第一次退出全屏后頁面還是全屏的”。視頻類頁面尤其容易出現(xiàn)這種狀態(tài)因?yàn)関ideo自身的controls全屏按鈕和頁面自定義的全屏按鈕會(huì)分別走各自的邏輯。建議在H5側(cè)維護(hù)一個(gè)全屏狀態(tài)隊(duì)列或者干脆統(tǒng)一由頁面自定義全屏按鈕接管把原生controls里的全屏功能用controlsListnofullscreen關(guān)掉。video controls controlsListnofullscreen playsinline/video這樣能避免用戶一邊點(diǎn)系統(tǒng)自帶的全屏按鈕一邊點(diǎn)頁面的全屏按鈕導(dǎo)致狀態(tài)錯(cuò)亂。4. 完整可運(yùn)行的方案從H5測試頁到鴻蒙容器4.1 一個(gè)可以直接用來復(fù)現(xiàn)問題的H5測試頁如果你和我一樣喜歡“最小可復(fù)現(xiàn)demo”的工作方式可以做一個(gè)非常干凈的測試頁。它只有一個(gè)video標(biāo)簽、一個(gè)自定義全屏按鈕并把所有全屏相關(guān)事件打印出來。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title鴻蒙Web組件全屏測試/title style body { margin: 0; background: #222; } .player { width: 100%; } video { width: 100%; background: #000; } .full-btn { display: block; width: 200px; margin: 20px auto; padding: 10px 0; text-align: center; background: #ff6600; color: #fff; border: none; border-radius: 6px; } /style /head body video idv classplayer controls playsinline webkit-playsinline preloadmetadata source srchttps://media.w3.org/2010/05/sintel/trailer.mp4 typevideo/mp4 /video button classfull-btn onclickfullscreenFn()全屏播放/button script function fullscreenFn() { const v document.getElementById(v); if (v.requestFullscreen) { v.requestFullscreen(); } else if (v.webkitRequestFullscreen) { v.webkitRequestFullscreen(); } else { console.log(no requestFullscreen support); } } document.addEventListener(fullscreenchange, function() { console.log(fullscreenchange, fullscreenElement:, document.fullscreenElement ? document.fullscreenElement.tagName : null); }); /script /body /html這個(gè)頁面里的https://media.w3.org/2010/05/sintel/trailer.mp4是W3C提供的公開測試視頻可以放心用。把這個(gè)HTML放到你的H5服務(wù)器上或者把它作為rawfile文件內(nèi)置到鴻蒙應(yīng)用里便于離線復(fù)現(xiàn)。4.2 鴻蒙側(cè)的完整容器代碼接下來是鴻蒙側(cè)的完整代碼。我習(xí)慣把窗口操作封裝成一個(gè)類這樣頁面代碼會(huì)干凈很多。下面的示例是所有代碼都寫在頁面組件里但邏輯清楚適合當(dāng)模板。import web from ohos.web.webview; import window from ohos.window; import { BusinessError } from ohos.base; Entry Component struct VideoWebPage { controller: web.WebviewController new web.WebviewController(); private mainWindow: window.Window | null null; aboutToAppear() { window.getLastWindow(getContext(this)).then((mainWindow: window.Window) { this.mainWindow mainWindow; }).catch((err: BusinessError) { console.error(getLastWindow failed, code: err.code , msg: err.message); }); } aboutToDisappear() { this.exitFullScreen(); } build() { Column() { Web({ src: https://your-domain.com/video.html, controller: this.controller }) .javaScriptAccess(true) .domStorageAccess(true) .mediaAccess(true) .allowFullScreen(true) .fileAccess(true) .onFullScreenChange((event) { if (event.isEnterFullScreen) { this.enterFullScreen(); } else { this.exitFullScreen(); } }) } .width(100%) .height(100%) } private enterFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.LANDSCAPE); this.mainWindow.setWindowLayoutFullScreen(true); this.mainWindow.setWindowSystemBarEnable([]); } private exitFullScreen() { if (!this.mainWindow) { return; } this.mainWindow.setPreferredOrientation(window.Orientation.PORTRAIT); this.mainWindow.setWindowLayoutFullScreen(false); this.mainWindow.setWindowSystemBarEnable([status, navigation]); } }有一點(diǎn)要提醒如果你把測試頁面內(nèi)置到了應(yīng)用資源里用$rawfile(video.html)作為src那么頁面里引用同目錄下的視頻資源也需要放進(jìn)去。不過我的建議是測試階段直接用線上H5地址因?yàn)檫@樣能一并驗(yàn)證網(wǎng)絡(luò)權(quán)限、域名校驗(yàn)、HTTPS證書等真實(shí)場景的問題。4.3 實(shí)操驗(yàn)證按順序測五個(gè)場景代碼就位之后按下面的順序驗(yàn)證每個(gè)場景單獨(dú)測避免互相干擾。第一個(gè)場景直接加載測試頁視頻能播放但不點(diǎn)全屏預(yù)期是正常內(nèi)聯(lián)播放。如果不能播放先查網(wǎng)絡(luò)權(quán)限和視頻編碼。第二個(gè)場景點(diǎn)擊頁面上的自定義全屏按鈕預(yù)期是進(jìn)入橫屏全屏、狀態(tài)欄和導(dǎo)航欄隱藏。如果沒反應(yīng)檢查鴻蒙側(cè)allowFullScreen有沒有開以及H5控制臺(tái)有沒有全屏報(bào)錯(cuò)。第三個(gè)場景全屏狀態(tài)下旋轉(zhuǎn)設(shè)備方向預(yù)期頁面跟隨旋轉(zhuǎn)視頻保持全屏。如果不跟隨可能是窗口方向鎖死了。第四個(gè)場景點(diǎn)擊系統(tǒng)的退出全屏按鈕或按返回鍵預(yù)期退出全屏、恢復(fù)豎屏和系統(tǒng)欄。如果恢復(fù)不完整檢查exitFullScreen里窗口恢復(fù)邏輯有沒有執(zhí)行。第五個(gè)場景全屏狀態(tài)下退到后臺(tái)再回前臺(tái)預(yù)期保持全屏或者自動(dòng)退出全屏但不能出現(xiàn)狀態(tài)欄丟失或者頁面變形。這一步很多團(tuán)隊(duì)會(huì)遺漏但用戶實(shí)際使用中非常常見。這五個(gè)場景全部通過基本可以認(rèn)為全屏鏈路是通的。剩下的就是和產(chǎn)品確認(rèn)某些頁面是否需要一直橫屏某些頁面是否需要禁止旋轉(zhuǎn)這些屬于產(chǎn)品策略代碼上都已經(jīng)具備調(diào)整能力。5. 常見問題速查表與實(shí)戰(zhàn)避坑5.1 問題速查表把這次排查中遇到的典型問題整理成一個(gè)速查表方便后續(xù)團(tuán)隊(duì)快速定位?，F(xiàn)象可能原因解決方案點(diǎn)擊全屏按鈕沒反應(yīng)鴻蒙側(cè)allowFullScreen未開啟Web組件添加.allowFullScreen(true)全屏黑屏但有聲音媒體權(quán)限未開或視頻編碼不支持添加.mediaAccess(true)檢查視頻編碼換h264測試全屏一兩秒自動(dòng)退出全屏事件回調(diào)與窗口旋轉(zhuǎn)時(shí)序沖突在onFullScreenChange里統(tǒng)一處理避免H5側(cè)重復(fù)調(diào)用exitFullscreen畫面半全屏但系統(tǒng)欄還在未進(jìn)入沉浸式布局調(diào)用setWindowLayoutFullScreen(true)并隱藏系統(tǒng)欄退出全屏后頁面還是全屏多層全屏請求疊加未清空用controlsListnofullscreen屏蔽原生全屏按鈕統(tǒng)一走頁面全屏邏輯返回上個(gè)頁面橫屏回不來頁面銷毀時(shí)沒恢復(fù)窗口狀態(tài)aboutToDisappear或onPageHide里主動(dòng)恢復(fù)窗口方向和系統(tǒng)欄視頻彈出系統(tǒng)播放器無法內(nèi)聯(lián)缺少playsinline屬性video標(biāo)簽添加playsinline webkit-playsinline5.2 前后臺(tái)切換和全屏狀態(tài)管理應(yīng)用退到后臺(tái)這個(gè)場景是實(shí)際使用中反饋?zhàn)疃嗟膯栴}之一。用戶在全屏狀態(tài)下按Home鍵退到桌面再回到應(yīng)用發(fā)現(xiàn)界面是橫屏的狀態(tài)欄卻回來了或者視頻變成一個(gè)小窗。我的建議是做一個(gè)統(tǒng)一的全屏狀態(tài)管理器。這個(gè)模塊不在本文展開寫了核心思路就是進(jìn)入全屏?xí)r保存當(dāng)前狀態(tài)頁面onHide時(shí)根據(jù)狀態(tài)決定是否退出全屏頁面重新onShow時(shí)再恢復(fù)。如果你不想做這么重最簡單粗暴的方案就是監(jiān)聽?wèi)?yīng)用前后臺(tái)狀態(tài)退后臺(tái)一律退出全屏。雖然損失一點(diǎn)體驗(yàn)但至少狀態(tài)不會(huì)錯(cuò)亂。還有一個(gè)細(xì)節(jié)Web組件的onFullScreenChange回調(diào)里event.isEnterFullScreen在不同API版本上可能字段名有差異。舊版本的ArkWeb用onFullScreen回調(diào)只在進(jìn)入全屏?xí)r觸發(fā)一次。如果你們的SDK比較老看到文檔里沒有onFullScreenChange就換成onFullScreen加exitFullScreen()手動(dòng)退出邏輯是一樣的只是監(jiān)聽方式不同。5.3 調(diào)試?yán)鞔蜷_Web調(diào)試和日志過濾排查這類問題一定要把Web組件的調(diào)試能力打開。鴻蒙Web組件有一個(gè)setWebDebuggingAccess(true)屬性設(shè)置之后就可以通過一些調(diào)試工具去查看網(wǎng)頁控制臺(tái)和DOM狀態(tài)。Web({ src: https://your-domain.com/video.html, controller: this.controller }) .setWebDebuggingAccess(true)打開調(diào)試之后結(jié)合DevEco Studio的Log窗口過濾關(guān)鍵字ArkWeb、FullScreen、JSFullScreen可以看到網(wǎng)頁和Web組件的關(guān)鍵事件。這里有個(gè)經(jīng)驗(yàn)很多全屏問題在網(wǎng)頁控制臺(tái)里其實(shí)是有報(bào)錯(cuò)信息的只是鴻蒙應(yīng)用的日志里不顯眼。我遇到過最典型的就是requestFullscreen() must be called from a user gesture這種報(bào)錯(cuò)信息如果不看網(wǎng)頁控制臺(tái)靠猜的話能猜一個(gè)下午。5.4 多端復(fù)用場景把全屏能力封裝成橋接接口現(xiàn)在很多團(tuán)隊(duì)都在做多端復(fù)用同一套H5頁面既要跑鴻蒙App又要跑小程序還要兼容瀏覽器。這種場景下全屏邏輯如果直接寫在頁面腳本里到了各端還要單獨(dú)適配。更合理的做法是在H5側(cè)定義一個(gè)統(tǒng)一的全屏能力接口由各端的宿主容器實(shí)現(xiàn)。舉個(gè)例子你可以約定一個(gè)window.CapabilityBridge對象暴露playFullscreen(videoElement)和exitFullscreen()兩個(gè)方法。鴻蒙端在網(wǎng)頁加載前注入實(shí)現(xiàn)內(nèi)部調(diào)用全屏API并配合窗口旋轉(zhuǎn)小程序端注入自己的一套實(shí)現(xiàn)。這樣H5業(yè)務(wù)代碼只需要調(diào)用CapabilityBridge.playFullscreen()不用關(guān)心底層容器差異。這個(gè)思路同樣適用于其它Web組件能力比如鍵盤彈起問題。熱搜詞里提到“app內(nèi)嵌h5頁面點(diǎn)擊input自動(dòng)滑動(dòng)到對應(yīng)input顯示鍵盤”這類問題的本質(zhì)也是Web組件與原生輸入法的交互鏈路。把這類交互統(tǒng)一收斂到橋接層比在每個(gè)頁面上打補(bǔ)丁要可靠得多。5.5 最后再說一個(gè)容易被忽略的媒體權(quán)限細(xì)節(jié)排查全屏問題的時(shí)候還有一個(gè)隱藏條件容易被漏掉應(yīng)用本身的媒體權(quán)限聲明。如果在module.json5里沒有聲明ohos.permission.MICROPHONE或者其它媒體相關(guān)權(quán)限部分機(jī)型在特定場景下會(huì)導(dǎo)致Web組件內(nèi)部媒體模塊初始化異常。表現(xiàn)就是視頻能播但全屏后的媒體渲染會(huì)出問題。如果你的測試機(jī)恰好是某幾個(gè)特定型號復(fù)現(xiàn)黑屏建議先檢查權(quán)限聲明再檢查代碼邏輯。權(quán)限聲明這一步雖然是基礎(chǔ)工作但很多“偶現(xiàn)”問題最后都栽在它上面。結(jié)尾這篇文章里的代碼和排查思路是我在多輪實(shí)際調(diào)試中沉淀下來的。如果你也遇到類似的全屏失效問題我強(qiáng)烈建議先做兩件事打開Web調(diào)試給H5頁面加上fullscreenchange監(jiān)聽打印事件日志判斷問題出在H5層還是鴻蒙層對照速查表快速檢查鴻蒙側(cè)Web組件的四個(gè)關(guān)鍵開關(guān)和窗口處理邏輯。九成的問題都能在十分鐘內(nèi)定位到具體環(huán)節(jié)。最后再分享一個(gè)提高效率的小技巧做一套全屏測試playground頁面把fullscreenchange、webkitfullscreenchange、resize事件全部打印出來把鴻蒙側(cè)的全屏回調(diào)也打印出來。以后不管是新項(xiàng)目還是接手的舊項(xiàng)目遇到類似H5與Web組件的交互問題直接拿這套頁面去對照比臨時(shí)寫測試代碼快得多。全屏問題看著唬人拆開來看就是權(quán)限、生命周期、窗口狀態(tài)這幾個(gè)環(huán)節(jié)的配合理順了就再也不會(huì)被它卡住了。