大家好,我是[晚风依旧似温柔],新人一枚,欢迎大家关注~

前言

在 ArkWeb 中加载第三方 H5 视频时,有一种现象很容易被误判成“全屏失效”:点击网页播放器的全屏按钮后,视频确实变大了,但它只占满了 Web 组件,应用自己的标题栏、操作区,甚至系统状态栏仍然存在。

这里其实叠加了两层不同的“全屏”。

华为官方已经针对这个场景给出了专门的“Web组件支持视频沉浸式全屏播放”指导:Web 组件可以通过 onFullScreenEnter 和 onFullScreenExit 感知网页进入、退出全屏,但如果希望视频进一步形成应用窗口级的沉浸式效果,还需要应用侧同步调整 ArkUI 组件以及窗口状态。

这篇文章就围绕这个边界做一个最小实践:H5 负责发起网页全屏,ArkWeb 负责把全屏事件交给应用,ArkUI 负责隐藏页面其他组件,Window 再负责处理系统界面元素。

一、先复现:为什么视频只撑满 Web 组件

假设页面结构很普通,上面是一条应用自己的标题栏,下面使用 Web 加载视频页面:

Column
├── 应用标题栏
└── Web
    └── H5 Video

第三方 H5 中的视频播放器触发全屏后,不能简单理解成“整个 HarmonyOS 应用已经进入沉浸式全屏”。

华为官方对这个现象的描述非常明确:Web 组件引用第三方 H5 页面加载视频时,点击视频全屏,视频可能只扩展到整个 Web 组件区域;要获得系统全屏的沉浸式视频播放效果,应用需要监听进入、退出全屏事件,并调整界面其他组件。

所以排查这种问题时,先不要把注意力放在 CSS 的 width: 100%、height: 100% 上。如果视频已经占满 Web,却没有占满应用窗口,问题的边界已经从 H5 布局进入 ArkUI 和窗口管理层。

二、网页全屏和系统沉浸式全屏不是一回事

这个场景最好拆成三层理解。

层级负责什么本文处理方式
H5 / ArkWeb网页视频请求进入或退出全屏onFullScreenEnter、onFullScreenExit
ArkUI 页面应用标题栏、按钮等原生组件Visibility.None / Visible
应用窗口状态栏、底部导航区域、沉浸式布局setWindowLayoutFullScreen、setSpecificSystemBarEnabled

官方窗口文档对“沉浸式布局”的定义也需要特别注意:进入沉浸式布局并不是把某个 Web 组件单独放大,而是改变窗口内元素的布局方式;沉浸式布局下,可用布局区域延伸到整个窗口,应用内容可以与系统 UI 区域重叠。官方同时说明,隐藏系统界面元素可以用于游戏、电影等沉浸式场景。

这也解释了为什么单独处理 Web 的宽高通常不够:Web 外面还有 ArkUI,ArkUI 外面还有应用窗口。

三、版本、Kit 和权限先核对

本文以 HarmonyOS 7 / API 26.0.0 为开发基线。华为当前的升级适配资料明确说明 HarmonyOS 7.0 对应 API 26.0.0;从 26.0.0 开始,HarmonyOS 开发套件的 API 版本号采用新的语义化版本格式。

核心依赖很少:Web 侧使用 ArkWeb Kit,通过 @kit.ArkWeb 引入 webview;窗口管理能力来自 ArkUI,通过 @kit.ArkUI 引入 window。官方当前的 Web 沉浸式全屏专题直接给出了 import { webview } from '@kit.ArkWeb' 以及 onFullScreenEnter、onFullScreenExit 的使用方式;最新窗口沉浸式指导则使用 @kit.ArkUI 中的 window。

这里对最低 API 版本需要保持克制:当前公开的“Web组件支持视频沉浸式全屏播放”专题页确认了这两个回调的当前用法,但该专题页本身没有标注它们各自的首次支持版本。因此本文只把已经能够公开核验的 HarmonyOS 7 / API 26 作为实践基线,不反推一个无法从当前专题资料确认的最低版本。

全屏事件本身不需要为了本文额外增加权限。如果加载的是在线第三方 H5,则涉及网络资源获取,官方 ArkWeb FAQ 明确要求在 module.json5 中声明 ohos.permission.INTERNET;加载纯本地页面时则不涉及这一步。

在线 H5 的配置可以写成:

{
  "module": {
    // ...
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

实际项目如果 H5 还使用定位等其他能力,应继续按照对应能力的权限要求处理,不能把 INTERNET 理解成 ArkWeb 的“万能权限”。

四、搭一个最小实践页面

为了把问题收敛到全屏切换本身,页面只保留两个区域:顶部模拟应用自己的标题栏,下面放 Web。

Web 页面可以换成业务中的第三方视频地址;如果只是验证全屏逻辑,也可以按照华为官方专题示例使用 $rawfile('FullScreen.html') 加载本地测试页面。官方示例本身就是通过一个状态变量控制标题区域的 visibility,在 onFullScreenEnter 时隐藏,在 onFullScreenExit 时恢复。

但我们还要比官方最小示例多走一步:不仅隐藏应用标题栏,还同步调整主窗口,让 Web 内容能够进入真正的窗口沉浸式布局。

五、核心代码:把两层全屏接起来

下面代码按照官方 ArkWeb 全屏事件和 ArkUI 窗口沉浸式接口组织为一个最小示例。这里假设页面进入前是普通非沉浸式状态。

import { webview } from '@kit.ArkWeb';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebVideoPage {
  private controller: webview.WebviewController =
    new webview.WebviewController();

  @State isFullScreen: boolean = false;

  private async updateWindowForVideo(fullScreen: boolean): Promise<void> {
    try {
      const mainWindow: window.Window =
        await window.getLastWindow(this.getUIContext().getHostContext());

      if (fullScreen) {
        // 让应用内容扩展到系统UI区域
        await mainWindow.setWindowLayoutFullScreen(true);

        // 隐藏状态栏和底部导航区域
        await mainWindow.setSpecificSystemBarEnabled('status', false);
        await mainWindow.setSpecificSystemBarEnabled(
          'navigationIndicator',
          false
        );
      } else {
        // 恢复系统界面元素
        await mainWindow.setSpecificSystemBarEnabled('status', true);
        await mainWindow.setSpecificSystemBarEnabled(
          'navigationIndicator',
          true
        );

        // 恢复普通布局
        await mainWindow.setWindowLayoutFullScreen(false);
      }
    } catch (error) {
      const err = error as BusinessError;
      console.error(
        `updateWindowForVideo failed, code: ${err.code}, message: ${err.message}`
      );
    }
  }

  build() {
    Column() {
      Row() {
        Text('视频详情')
          .fontSize(20)
      }
      .width('100%')
      .height(56)
      .justifyContent(FlexAlign.Center)
      .visibility(
        this.isFullScreen ? Visibility.None : Visibility.Visible
      )

      Web({
        src: $rawfile('FullScreen.html'),
        controller: this.controller
      })
        .onFullScreenEnter((event) => {
          console.info('ArkWeb onFullScreenEnter');
          this.isFullScreen = true;
          this.updateWindowForVideo(true);
        })
        .onFullScreenExit(() => {
          console.info('ArkWeb onFullScreenExit');
          this.isFullScreen = false;
          this.updateWindowForVideo(false);
        })
        .width('100%')
        .height('100%')
        .zIndex(10)
    }
    .width('100%')
    .height('100%')
  }
}

真正需要关注的不是代码量,而是两个状态必须一起切换。

isFullScreen 管的是应用自己的 ArkUI 页面。Visibility.None 与 Hidden 不能混为一谈:官方全屏专题明确采用 Visibility.None,原因是组件不可见的同时不再参与布局、不占位。如果只是把标题内容画成透明或者仍然保留布局空间,Web 顶部仍可能留出一块区域。

updateWindowForVideo() 管的则是主窗口。官方最新沉浸式窗口指导给出的方案同样是先使用 setWindowLayoutFullScreen(true) 进入沉浸式布局,再通过 setSpecificSystemBarEnabled() 控制状态栏等系统界面元素。

六、几个容易理解错的地方

1. onFullScreenEnter 不是“系统已经全屏”的通知

它首先解决的是 ArkWeb 与应用之间的状态同步问题。官方专题要求应用在这个回调中根据业务调整组件显隐、margin 等属性,本身就说明 Web 的全屏状态不会替应用自动处理 Web 外部的 ArkUI 布局。

因此,标题栏还在时,不应该继续给 H5 加 CSS,而应该检查应用有没有响应 ArkWeb 的全屏事件。

2. setWindowLayoutFullScreen(true) 也不等于“隐藏所有系统 UI”

窗口沉浸式布局解决的是布局区域问题。官方文档明确说明,沉浸式布局会让应用可用布局区域延伸到整个窗口,但系统界面元素层级仍高于应用内容。要获得视频场景常见的沉浸效果,还需要按需求隐藏对应系统界面元素。

所以本文才同时调用 setWindowLayoutFullScreen() 和 setSpecificSystemBarEnabled()。

3. 不要把“全屏”强行等同于“横屏”

视频进入全屏和窗口旋转是两个不同状态。

华为的视频横竖屏最佳实践指出,应用可以通过 module.json5 的 orientation 或运行时的 setPreferredOrientation() 设置旋转策略;运行时修改方向适合视频播放等进入页面后还需要改变显示方向的场景。官方同时提醒,窗口旋转在分屏、悬浮窗、自由多窗等特殊状态下存在行为限制。

因此这个最小 Demo 没有在 onFullScreenEnter 中强制写死横屏。业务如果明确要求“点击 H5 全屏后强制横屏”,应再按照官方视频横竖屏方案加入 setPreferredOrientation(),并在退出时恢复自己的旋转策略,而不是把旋转逻辑偷偷塞进 Web 布局代码。

4. 自由窗口不能照搬手机全屏逻辑

最新窗口文档明确说明,setSpecificSystemBarEnabled()、setWindowSystemBarEnable() 这类控制系统界面元素的接口,只在非自由窗口状态下的主窗口支持;辅助窗口或自由窗口状态下调用不会按普通全屏窗口的方式生效。

这意味着 Phone 上验证通过,并不能直接推导 PC/2in1 自由窗口也会呈现完全相同的效果。自由窗口需要按照官方针对窗口标题栏、窗口装饰区域的方案单独适配。

七、退出全屏为什么也要认真处理

onFullScreenExit 不是简单把一个 Boolean 改回 false。

进入时我们修改了两类状态:ArkUI 组件状态和 Window 状态。退出时也要成对恢复。否则很容易出现视频已经回到普通页面,但状态栏仍然隐藏,或者标题栏恢复了、窗口却还保持沉浸式布局的情况。

本文示例假设“进入视频前页面是普通非沉浸式页面”,因此退出时恢复系统栏并执行 setWindowLayoutFullScreen(false)。

如果应用本来就是全局沉浸式,这个恢复策略就不能直接照搬。更合理的做法是让视频全屏逻辑接入应用已有的窗口状态管理:退出 H5 全屏时恢复业务原来的窗口策略,而不是无条件恢复成非沉浸式。

这个区别在复杂项目里很关键。

八、横竖屏和多窗口怎么验证

不要只验证“点一次全屏,再点一次退出”。窗口旋转本身会带来窗口尺寸变化,华为视频横竖屏最佳实践也要求布局根据窗口尺寸变化进行适配,并给出了 windowSizeChange 的监听思路。

实际项目可以按下面的矩阵做人工验证:

场景重点观察
竖屏进入 H5 全屏自定义标题栏是否退出布局,Web 是否铺满可用区域
全屏后旋转横屏Web 是否跟随窗口尺寸重新布局
横屏退出全屏应用标题栏、系统栏是否恢复到业务预期状态
连续进入/退出全屏isFullScreen 与窗口状态是否保持一致
分屏/自由窗口不假设手机全屏行为仍然成立,按窗口模式重新验证
在线第三方 H5网络权限、H5 自身播放器全屏能力和 ArkWeb 回调是否分别正常

九、实际项目中的排查顺序

如果遇到“点了全屏但还是不像全屏”,可以从外到内排查,而不是一开始就改 H5。

先确认当前 SDK 和目标系统版本,再确认 onFullScreenEnter 是否真的触发;随后检查 Web 外部的 ArkUI 标题栏、Tabs、底部操作区有没有退出布局;再检查主窗口有没有进入沉浸式布局以及系统栏状态;如果还伴随方向异常,再单独检查旋转策略。在线 H5 如果连页面加载本身都不稳定,则应先确认 ohos.permission.INTERNET 和 ArkWeb 加载错误,官方的 Web 白屏 FAQ 也把网络权限列在在线页面排查的前置步骤中。

这样拆开以后,问题通常会落到 H5 全屏事件、ArkUI 布局、Window 沉浸式或者窗口旋转中的某一层,而不是笼统地归因成“Web 全屏有问题”。

开发经验总结

这类 ArkWeb 视频问题最值得记住的是边界。

H5 全屏负责视频在 Web 内容中的全屏状态,应用沉浸式负责 Web 外部的 ArkUI 和窗口显示状态。 onFullScreenEnter / onFullScreenExit 正好是连接这两个世界的状态节点。

页面层优先通过明确的状态变量控制标题栏等组件是否参与布局;窗口层再使用官方窗口管理接口处理沉浸式布局和系统界面元素。横竖屏则作为第三个独立维度处理,不要看到“视频全屏”就默认必须锁定横屏。

另外,本文代码是依据华为当前官方接口和示例整理的最小实现,没有在 HarmonyOS 工程中实际编译、运行,因此正式接入业务前仍应使用目标 HarmonyOS 7 设备,对第三方 H5、横竖屏切换以及应用自身的窗口策略做完整验证。

如果自己的页面正好也存在“Web 全屏后顶部还剩一条标题栏”的问题,可以先观察一个最简单的信号:onFullScreenEnter 已经到了,但 Web 外面的组件和主窗口有没有跟着改变状态? 这个切入点通常比继续调整 H5 的宽高更接近问题本身。

如果觉得有帮助,别忘了点个赞+关注支持一下~
喜欢记得关注,别让好内容被埋没~

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐