鸿蒙 ArkTS 沉浸式状态栏开发实战:从原理到可运行示例,一次搞定!

import { UIAbility, window } from '@kit.AbilityKit';import { hilog } from '@kit.PerformanceAnalysisKit';export default class EntryAbility extends UIAbility {  onWindowStageCreate(windowStage: window.WindowStage): void {    // 加载主页面    windowStage.loadContent('pages/index', (err) => {      if (err) {        hilog.error(0x0000, 'EntryAbility', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));        return;      }    });    // 核心：设置沉浸式状态栏（异步获取窗口，避免阻塞）    windowStage.getMainWindow((err, mainWindow) => {      if (err) {        hilog.error(0x0000, 'EntryAbility', 'Failed to get main window. Cause: %{public}s', JSON.stringify(err));        return;      }      // 1. 开启窗口全屏布局：内容延伸到状态栏/导航栏      mainWindow.setWindowLayoutFullScreen(true)        .then(() => {          // 2. 配置状态栏：透明背景 + 白色文字（适配深色页面）          const systemBarProps: window.SystemBarProperties = {            statusBarColor: '#00000000', // 透明状态栏（#ARGB格式）            statusBarContentColor: '#FFFFFF' // 状态栏文字：白色（#000000为黑色）          };          return mainWindow.setWindowSystemBarProperties(systemBarProps);        })        .then(() => {          hilog.info(0x0000, 'EntryAbility', 'Immersive status bar set successfully');        })        .catch((err) => {          hilog.error(0x0000, 'EntryAbility', 'Set immersive failed. Cause: %{public}s', JSON.stringify(err));        });    });  }}

@Entry@Componentstruct Index {  build() {    // 外层Column，顶部padding=状态栏高度，保证内容不被遮挡    Column() {      // 沉浸式顶部区域：背景延伸到状态栏      Stack({ alignContent: Alignment.Center }) {        // 背景图/背景色，覆盖状态栏区域        Image($r('app.media.bg_immersive'))          .width('100%')          .height(200)          .objectFit(ImageFit.Cover)          // 关键：扩展组件绘制到状态栏，实现背景沉浸          .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP])        // 标题文字，在安全区内显示        Text('鸿蒙沉浸式状态栏实战')          .fontSize(24fp)          .fontWeight(FontWeight.Bold)          .fontColor(Color.White)      }      .width('100%')      // 页面主体内容      Scroll() {        Column({ space: 16 }) {          Text('全局窗口沉浸式方案').fontSize(20fp).fontWeight(FontWeight.Medium)          Text('✅ 全应用生效，一次配置').fontSize(16fp)          Text('✅ 背景/图片完美延伸到状态栏').fontSize(16fp)          Text('✅ 支持自定义状态栏文字颜色').fontSize(16fp)        }        .padding(16)      }    }    // 核心避让：顶部padding=状态栏高度，自动适配所有机型    .padding({ top: env('safe-area-inset-top') })    .width('100%')    .height('100%')  }}