在 HarmonyOS（鸿蒙）应用开发中，状态栏（StatusBar）的样式定制是高频需求 —— 比如不同页面需要切换状态栏文字的深浅色，适配页面背景色以保证文字可读性。如果每次调整都重复编写获取窗口、设置系统栏属性的代码，不仅冗余，还会增加后期维护成本。本文将基于 ArkTS（ArkUI），手把手教你封装一个简洁、易用的状态栏工具类，让状态栏样式调整变得优雅高效。

一、封装背景与核心需求

在 HarmonyOS 中，调整状态栏样式需要通过window模块的setWindowSystemBarProperties方法实现，但这个过程需要经历「获取上下文→获取窗口实例→设置系统栏属性」三个步骤，重复编写这些代码会让业务逻辑变得臃肿。

我们的核心封装需求：

1. 提供快捷方法，一键设置「深色文字状态栏」（黑字）和「浅色文字状态栏」（白字）；
2. 封装通用方法，支持自定义状态栏配置；
3. 代码解耦，工具类独立于业务页面，便于全局复用。

二、完整封装代码与逐行解析

先贴出最终的封装代码（即本文提供的核心代码），再逐段拆解关键逻辑：

typescript

运行

// statusBarUtils.ets
import { AppStorageV2, window } from '@kit.ArkUI'
import { SavedContext } from '../../models'

/**
 * 状态栏工具类
 * 封装状态栏样式设置的通用逻辑，简化业务层调用
 */
class StatusBar {
  /**
   * 设置深色文字状态栏（文字颜色：黑色）
   */
  async setDarkBar() {
    await this.setBar({ statusBarContentColor: '#000000' })
  }

  /**
   * 设置浅色文字状态栏（文字颜色：白色）
   */
  async setLightBar() {
    await this.setBar({ statusBarContentColor: '#FFFFFF' })
  }

  /**
   * 通用状态栏设置方法（核心）
   * @param config 系统栏配置项，继承window.SystemBarProperties
   */
  async setBar(config: window.SystemBarProperties) {
    // 1. 从AppStorageV2获取应用上下文
    const context = AppStorageV2.connect(SavedContext)!.context
    // 2. 获取当前应用的最后一个窗口实例
    const win = await window.getLastWindow(context)
    // 3. 设置窗口系统栏属性（核心API）
    await win.setWindowSystemBarProperties(config)
  }
}

// 导出单例实例，全局复用（避免重复创建实例）
export const statusBar = new StatusBar()

关键代码解析

1. 模块导入

typescript

运行

import { AppStorageV2, window } from '@kit.ArkUI'
import { SavedContext } from '../../models'

• window：HarmonyOS 提供的窗口管理模块，核心用于操作状态栏、导航栏等系统栏样式；
• AppStorageV2：鸿蒙的应用存储工具，这里用于获取应用上下文（Context）；
• SavedContext：自定义的上下文存储对象（需在项目中提前定义，用于统一管理应用上下文）。

2. 类的核心方法设计

• 快捷方法（setDarkBar/setLightBar）：封装最常用的两个场景 —— 设置黑 / 白字状态栏，内部调用通用方法setBar，简化业务层调用（无需记忆配置项字段）。

• 通用方法（setBar）：这是工具类的核心，实现了状态栏设置的完整逻辑：

  • 第一步：通过AppStorageV2.connect(SavedContext)获取应用上下文（Context 是操作窗口的前提）；
  • 第二步：调用window.getLastWindow(context)获取当前活跃的窗口实例；
  • 第三步：调用setWindowSystemBarProperties设置状态栏配置（入参为window.SystemBarProperties类型，支持更多扩展配置）。

3. 单例导出

typescript

运行

export const statusBar = new StatusBar()

通过直接导出实例而非类，保证全局只有一个StatusBar实例，避免重复创建对象，符合「工具类单例」的设计原则。

三、工具类使用示例

封装完成后，在任意页面中调用只需 3 步，极简且易读：

1. 导入工具类

typescript

运行

// 假设工具类路径为 utils/statusBarUtils.ets
import { statusBar } from '../utils/statusBarUtils'

2. 在页面生命周期中调用

推荐在onPageShow（页面显示时）或onMount（页面挂载时）调用，确保状态栏样式随页面切换生效：

typescript

运行

@Entry
@Component
struct LoginSelectPage {
  // 页面显示时设置浅色文字状态栏（适配深色背景）
  async onPageShow() {
    await statusBar.setLightBar()
  }

  // 若页面卸载时需要恢复默认样式，可在onPageHide中设置
  async onPageHide() {
    await statusBar.setDarkBar()
  }

  build() {
    // 页面布局...
    Column() {
      Text('测试页面')
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#000000') // 深色背景适配浅色文字
  }
}

3. 自定义状态栏配置（扩展使用）

如果需要设置更多状态栏属性（比如隐藏状态栏、修改背景色），可直接调用setBar方法：

typescript

运行

// 隐藏状态栏 + 设置文字颜色为白色
await statusBar.setBar({
  statusBarContentColor: '#FFFFFF',
  statusBarHidden: true // 隐藏状态栏
})

四、封装优化与扩展建议

为了让工具类更健壮、更通用，可根据实际需求扩展以下功能：

1. 增加错误处理

避免因上下文获取失败、窗口实例不存在等异常导致应用崩溃：

typescript

运行

async setBar(config: window.SystemBarProperties) {
  try {
    const context = AppStorageV2.connect(SavedContext)?.context
    if (!context) {
      console.error('StatusBar工具类：获取上下文失败')
      return
    }
    const win = await window.getLastWindow(context)
    await win.setWindowSystemBarProperties(config)
  } catch (e) {
    console.error('StatusBar工具类：设置状态栏失败', e)
  }
}

2. 扩展更多快捷方法

比如封装「隐藏状态栏」「显示状态栏」「设置状态栏背景色」等常用场景：

typescript

运行

// 隐藏状态栏
async hideStatusBar() {
  await this.setBar({ statusBarHidden: true })
}

// 显示状态栏
async showStatusBar() {
  await this.setBar({ statusBarHidden: false })
}

3. 全局状态栏管理

结合路由拦截，实现「页面路由切换时自动适配状态栏样式」，比如在路由跳转前根据目标页面配置自动设置状态栏。

五、总结

通过封装状态栏工具类，我们实现了：

1. 代码复用：将重复的「获取上下文→获取窗口→设置属性」逻辑抽离，业务层只需一行代码调用；
2. 逻辑解耦：状态栏操作与页面业务分离，便于后期统一修改（比如更换文字颜色值）；
3. 易用性提升：通过快捷方法降低新手使用成本，无需记忆复杂的 API 参数。

这种封装思路不仅适用于状态栏，也可推广到鸿蒙开发中其他高频操作（如导航栏、弹窗、网络请求等）—— 核心是「抽离通用逻辑、简化业务调用」，让代码更简洁、更易维护。