前言

状态栏和导航栏的样式控制是UI定制化的重要部分。通过设置状态栏文字颜色、背景色等属性，可以让应用界面更加协调统一。@pura/harmony-utils 的 WindowUtil 封装了状态栏和导航栏的属性设置方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、WindowUtil状态栏核心API

WindowUtil 提供了以下状态栏和导航栏属性设置方法：

方法	说明	参数	使用场景
setStatusBarColor(color)	设置状态栏背景色	ARGB颜色字符串	主题适配
setStatusBarContentColor(color)	设置状态栏内容颜色	颜色字符串	文字可见性
setNavigationBarColor(color)	设置导航栏背景色	ARGB颜色字符串	底部栏适配

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 即时生效：颜色设置后立即生效

1.2 状态栏配色方案

方案	背景色	内容色	适用场景
深色主题	#FF4A90D9	#FFFFFF	蓝色系应用
浅色主题	#FFFFFFFF	#000000	白色系应用
沉浸式	#00000000	#FFFFFF	全屏沉浸

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 设置状态栏样式

import { WindowUtil } from '@pura/harmony-utils';

Button('深色状态栏')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setStatusBarColor('#FF4A90D9');
      WindowUtil.setStatusBarContentColor('#FFFFFF');
      this.result = '状态栏: 深色背景 + 白色文字';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('浅色状态栏')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setStatusBarColor('#FFFFFFFF');
      WindowUtil.setStatusBarContentColor('#000000');
      this.result = '状态栏: 浅色背景 + 深色文字';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 设置导航栏样式

Button('设置导航栏颜色')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setNavigationBarColor('#FFF5F5F5');
      this.result = '导航栏颜色已设置';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { WindowUtil } from '@pura/harmony-utils';

@Entry
@Component
struct StatusBarDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('蓝色状态栏').width('100%').onClick(() => {
        WindowUtil.setStatusBarColor('#FF4A90D9');
        WindowUtil.setStatusBarContentColor('#FFFFFF');
        this.result = '蓝色状态栏已设置';
      });
      Button('白色状态栏').width('100%').onClick(() => {
        WindowUtil.setStatusBarColor('#FFFFFFFF');
        WindowUtil.setStatusBarContentColor('#333333');
        this.result = '白色状态栏已设置';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 根据页面主题动态切换

import { WindowUtil } from '@pura/harmony-utils';

function applyTheme(isDark: boolean) {
  if (isDark) {
    WindowUtil.setStatusBarColor('#FF1A1A1A');
    WindowUtil.setStatusBarContentColor('#FFFFFF');
  } else {
    WindowUtil.setStatusBarColor('#FFFFFFFF');
    WindowUtil.setStatusBarContentColor('#000000');
  }
}

4.2 渐变色状态栏

aboutToAppear() {
  WindowUtil.setWindowLayoutFullScreen(true);
  WindowUtil.setStatusBarColor('#00000000');
}

五、注意事项

1. 颜色格式：使用ARGB格式，如 #FF4A90D9
2. 内容颜色：仅支持黑色和白色两种
3. 初始化依赖：使用前需确保 AppUtil.init() 已调用
4. 页面切换：页面切换时注意恢复状态栏样式
5. 沉浸式配合：与沉浸式布局配合使用效果更佳

六、常见问题

Q1: 设置状态栏颜色后没有生效？

检查颜色格式是否正确（ARGB格式），以及 AppUtil.init() 是否已调用。

Q2: 内容颜色只能设置黑白吗？

是的，HarmonyOS系统限制状态栏内容颜色仅支持黑色和白色。

Q3: 如何实现透明状态栏？

设置颜色为 #00000000 并配合沉浸式布局即可实现透明效果。

Q4: 导航栏颜色设置后底部有间隙？

需要配合沉浸式布局使用，让内容延伸到导航栏区域。

总结

WindowUtil 的状态栏和导航栏属性设置方法为应用UI定制化提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用这些方法，可以让应用界面更加协调统一。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。