沉浸式开了状态栏盖住标题,安全区不是全屏就完事

一个视频详情页,产品要求沉浸式体验:状态栏透明,内容延伸到屏幕顶部,返回按钮浮在视频画面上。你调了 setWindowLayoutFullScreen(true),状态栏变透明了,视频画面确实延伸到了顶部。然后标题和返回按钮被状态栏盖住了,用户看不清左上角的返回箭头,也看不清标题文字。你把标题的 padding 调大,返回按钮往下挪,勉强避开了状态栏。换到深色模式,状态栏文字变成白色,盖在浅色的视频画面上,几乎看不见。折叠屏展开,安全区变了,标题又被挖孔摄像头盖住。

问题不在 setWindowLayoutFullScreen 有没有生效,在于沉浸式布局开启的是"内容延伸到系统栏下面",不是"系统栏消失"。状态栏、导航栏、挖孔摄像头、手势条这些系统区域仍然存在,它们占据的物理空间变成了"安全区",你的内容需要在安全区之外展示,否则就会被遮挡。你把"全屏"当成了"没有系统栏",布局自然会对不上。

setWindowLayoutFullScreen 只是让内容延伸到系统栏下面,安全区还在

先把这条边界钉死。window.setWindowLayoutFullScreen(true) 的语义是:窗口的布局区域扩展到整个屏幕,包括状态栏和导航栏占据的区域。内容可以画到这些区域下面,但系统栏本身不会消失,它们仍然以悬浮的形式显示在内容上面。状态栏的文字、图标,导航栏的返回手势条,都在那里。

这意味着你的内容需要一个"避让"机制。Column 或 Stack 的顶部如果直接从 y=0 开始放标题,标题会被状态栏盖住。正确的做法是用 safeArea 或者 expandSafeArea 的语义来决定哪些区域避让、哪些区域延伸。

safeArea 描述的是屏幕上的安全区域,它排除了状态栏、导航栏、挖孔、圆角这些不可用区域。expandSafeArea 的属性可以声明"这个组件延伸到安全区之外",比如视频画面延伸到状态栏下面,但标题栏不延伸。

typescript

复制代码
@Entry
@Component
struct VideoDetailPage {
  aboutToAppear(): void {
    const win = this.getUIContext().getHostContext() as common.UIAbilityContext;
    window.getLastWindow(win).then((w) => {
      // 内容延伸到系统栏下面,但系统栏本身仍然可见
      w.setWindowLayoutFullScreen(true);
      // 状态栏透明,让视频画面透上来
      w.setWindowSystemBarProperties({
        statusBarColor: '#00000000',
        statusBarContentColor: '#FFFFFF',
        navigationBarColor: '#00000000'
      });
    });
  }

  build() {
    Stack({ alignContent: Alignment.TopStart }) {
      // 视频区域:延伸到状态栏下面,不需要避让
      Video({ src: this.videoUrl })
        .width('100%')
        .height('40%')
        .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP])

      // 标题栏:避让状态栏,不延伸到系统栏下面
      Row() {
        Image($r('app.media.ic_back')).width(24).height(24)
        Text('视频标题').fontSize(18)
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 8, bottom: 8 })
      // 不设 expandSafeArea,默认避让安全区
    }
  }
}

Video 组件上的 expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP]) 声明了"视频延伸到顶部系统栏下面",所以视频画面会顶到屏幕最上沿。Row 标题栏没有设 expandSafeArea,它默认避让安全区,y 坐标从状态栏下沿开始,标题和返回按钮不会被状态栏盖住。两者的区别不是"有没有开沉浸式",是"谁延伸、谁避让"。

expandSafeArea 的 SafeAreaType.SYSTEM 涵盖状态栏和导航栏,SafeAreaType.KEYBOARD 涵盖软键盘,SafeAreaType.CUTOUT 涵盖挖孔和刘海。只写 SYSTEM 时,挖孔区域仍然避让;如果视频需要覆盖挖孔区域,SafeAreaType 里要同时包含 CUTOUT。

状态栏文字颜色不是跟着深色模式自动切的,要显式设置

setWindowSystemBarProperties 里的 statusBarContentColor 决定了状态栏文字和图标的颜色。它不会跟着应用的深色/浅色模式自动切换,你设了白色就是白色,用户切到浅色模式,白色文字在浅色背景上看不见,状态栏变成了"隐形"的。

正确的做法是在应用的主题切换逻辑里,同步更新 statusBarContentColor。深色背景配白色文字,浅色背景配黑色文字。如果页面顶部的背景色是动态的(比如视频画面颜色随内容变化),状态栏文字颜色可能需要根据背景的亮度动态调整。

typescript

复制代码
function updateStatusBarColor(isDark: boolean): void {
  const win = this.getUIContext().getHostContext() as common.UIAbilityContext;
  window.getLastWindow(win).then((w) => {
    w.setWindowSystemBarProperties({
      statusBarContentColor: isDark ? '#FFFFFF' : '#000000',
      navigationBarContentColor: isDark ? '#FFFFFF' : '#000000'
    });
  });
}

statusBarContentColor 的取值是颜色字符串,支持 #RRGGBB 和 #AARRGGBB。它只影响文字和图标的颜色,不影响状态栏背景。背景由 statusBarColor 控制,设为 #00000000 时状态栏透明,背景由页面内容决定。

键盘弹起时安全区变了,底部布局没跟上

沉浸式布局下,键盘弹起时安全区的底部边界会向上移动,让出键盘的空间。如果你的页面底部有一个固定的输入栏或按钮,它需要在键盘弹起时跟着上移,否则会被键盘盖住。

expandSafeArea 不处理键盘避让,键盘避让由 KeyboardAvoidMode 控制。前面写过的 RESIZE 模式让页面高度被压缩,底部固定栏被推到键盘上方;OFFSET 模式让页面整体上移。沉浸式布局下,如果底部栏设了 expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM]),它延伸到了导航栏下面,但键盘弹起时这个延伸不自动收缩,底部栏仍然在导航栏的位置,键盘盖住了它。

typescript

复制代码
// 底部输入栏:不延伸到系统栏下面,让键盘避让能正常生效
Row() {
  TextInput({ placeholder: '输入评论' })
  Button('发送')
}
.height(56)
// 不要给底部栏设 expandSafeArea BOTTOM,否则键盘弹起时它不会避让

底部固定栏应该避让安全区,不要延伸到导航栏下面。导航栏下面的那条手势条区域,看起来"空着",但它是系统手势的识别区,输入栏延伸进去会让用户的手势和输入栏的点击互相干扰。顶部视频可以延伸到状态栏下面,底部输入栏不应该延伸到导航栏下面,两者的 expandSafeArea 策略是不对称的。

分屏和悬浮窗下,窗口尺寸和安全区都是动态的

应用被拖到分屏或者悬浮窗,窗口尺寸变化,安全区的边界也跟着变。分屏模式下,应用窗口不再占满整个屏幕,状态栏可能不在窗口顶部,导航栏可能不在窗口底部,安全区的计算基于当前窗口的几何形状,不是基于整个屏幕。

如果布局里用的是固定的 padding({ top: 24 }) 来避让状态栏,分屏时状态栏的位置变了,24 这个值可能太大或者太小。正确的方式是用 safeArea 相关的布局能力,让组件自动从当前窗口的安全区边界开始布局,而不是硬编码一个像素值。

typescript

复制代码
// 用安全区自动避让,不要硬编码状态栏高度
Column() {
  // 内容
}
// 不设 expandSafeArea 时,组件默认从安全区内部开始布局
// 安全区的边界随窗口形态变化,组件会自动适应

expandSafeArea 不设的时候,组件默认避让安全区,这个避让是动态计算的,分屏、悬浮窗、折叠屏展开时都会自动调整。硬编码的 padding 不会。排查"分屏时布局错位"的时候,先检查有没有手写的 padding 去模拟状态栏高度,有的话删掉,交给安全区机制。

折叠屏展开和挖孔区域,安全区不是只有状态栏

折叠屏展开时,屏幕形状变化,挖孔摄像头的位置可能从顶部中间变成左上角,圆角的半径也变了。SafeAreaType.CUTOUT 涵盖的是挖孔和刘海区域,expandSafeArea 里只写 SYSTEM 不写 CUTOUT,内容延伸到了状态栏下面,但挖孔区域仍然避让。表现是视频画面在状态栏下面铺满了,但左上角挖孔的位置有一块空白,或者标题被挖孔挡住。

typescript

复制代码
// 视频区域同时覆盖状态栏和挖孔区域
.expandSafeArea(
  [SafeAreaType.SYSTEM, SafeAreaType.CUTOUT],
  [SafeAreaEdge.TOP]
)

SafeAreaType.CUTOUT 和 SafeAreaType.SYSTEM 是两个独立的类型,前者管挖孔/刘海/圆角,后者管状态栏/导航栏。只写其中一个,另一类区域仍然避让。排查"内容没有完全铺满"的时候,看 expandSafeArea 的 SafeAreaType 是不是漏了 CUTOUT。

windowSizeChange 和安全区变化是两条信号,不要混用

window.on('windowSizeChange') 在窗口尺寸变化时触发,window.on('avoidAreaChange') 在安全区变化时触发。分屏拖拽时,窗口尺寸连续变化,windowSizeChange 高频触发;折叠屏展开时,安全区可能变化但窗口尺寸不变,avoidAreaChange 触发。

如果布局只监听了 windowSizeChange,折叠屏展开时安全区变了但窗口尺寸没变,布局不会重新计算避让;如果只监听了 avoidAreaChange,分屏拖拽时窗口尺寸变了但安全区边界可能还没更新,布局用的是旧的窗口尺寸。两个信号都要监听,各自负责各自的布局参数。

typescript

复制代码
w.on('windowSizeChange', (size: window.Size) => {
  this.onWindowSizeChange(size);
});
w.on('avoidAreaChange', (data: window.AvoidAreaOptions) => {
  this.onSafeAreaChange(data);
});

avoidAreaChange 的回调里携带的 AvoidAreaOptions 包含 type 和 area,type 区分是系统栏、键盘还是挖孔,area 给出具体的矩形边界。按 type 分别处理,不要把所有安全区变化都当成"状态栏高度变了"。

排查顺序:先看谁延伸谁避让,再看系统栏颜色,最后看安全区信号

下次沉浸式布局"内容被状态栏盖住"或者"状态栏文字看不见"的时候,按这个顺序走。

第一步,检查 expandSafeArea 的设置。需要延伸到系统栏下面的组件(视频、背景图)设了 expandSafeArea;需要避让的组件(标题栏、底部输入栏)没设。设了 expandSafeArea 的组件被状态栏盖住,是预期行为,不是 bug。

第二步,检查 setWindowSystemBarProperties 里的 statusBarContentColor 有没有跟随深色/浅色模式更新。状态栏背景透明时,文字颜色必须和页面顶部背景的亮度匹配,否则会"隐形"。

第三步,检查 SafeAreaType 有没有漏掉 CUTOUT。只写 SYSTEM 时,挖孔和圆角区域仍然避让,视频画面在挖孔位置会有空白。

第四步,确认布局里有没有硬编码的 padding 去模拟状态栏高度。分屏、悬浮窗、折叠屏展开时,安全区边界是动态的,硬编码的值会错位。

第五步,同时监听 windowSizeChange 和 avoidAreaChange,窗口尺寸和安全区边界是两条独立的信号,各自负责各自的布局参数。

setWindowLayoutFullScreen(true) 开启的是"内容延伸到系统栏下面",不是"系统栏消失"。状态栏、导航栏、挖孔、手势条仍然存在,它们占据的空间是安全区。需要沉浸的组件用 expandSafeArea 声明延伸,需要可读的组件默认避让安全区;状态栏文字颜色要跟着深色/浅色模式显式更新;分屏和折叠屏下安全区边界是动态的,硬编码的 padding 会错位。下一次沉浸式页面标题被状态栏盖住的时候,先别怀疑 setWindowLayoutFullScreen 没生效------打开布局看一眼,那个标题栏,到底有没有声明它要避让安全区。