@ionic-native/status-bar

本项目基于@ionic-native/[email protected]开发。

简介

一个用于管理设备状态栏的插件，支持对状态栏的样式、可见性、行为进行全方位自定义。兼容Android、iOS和OpenHarmony平台，为跨平台应用开发提供统一的设备差异化适配能力。本文档主要说明在OpenHarmony系统中的应用。

在移动应用开发中，状态栏管理是常见的功能需求，常用于应用视觉风格与系统状态栏的统一，提升用户体验。@ionic-native/status-bar插件通过封装原生平台API，为开发者提供了统一的跨平台接口，无需深入原生开发即可实现状态栏的全方位自定义。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @ionic-native/status-bar

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @ionic-native/status-bar

手动引入安装

1.添加插件配置

根据plugin.xml的config-json项，找到entry模块中config.xml文件，并根据param标签添加配置

<feature name="StatusBar">
  <param name="harmony-package" value="StatusBar" />
  <param name="onload" value="true" />
</feature>

2.修改CMake配置

根据plugin.xml的CMakeLists项，找到cordova模块，路径为target字段的文件CMakeLists.txt，添加add_library

add_library(cordova SHARED
  // ...
  StatusBar/StatusBar.cpp
  // ...
)

3.复制源码文件

根据plugin.xml的source-file项，将src字段的路径代码复制到cordova模块中target-dir字段的目录中：

将源码中src/main/cpp/StatusBar目录下的StatusBar.h、StatusBar.cpp文件引入到cordova模块中src/main/cpp/StatusBar目录下。

将源码中src/main/ets/components/StatusBar目录下的StatusBarAction.ets文件引入到cordova模块中src/main/ets/components/StatusBar目录下。

4.添加ArkTS配置

在cordova模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤3中拷贝的ets文件路径:

"buildOption":{
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/StatusBar/StatusBarAction.ets"
        // ...
      ]
    }
  }
}

卸载

# hionic CLI卸载
hionic plugin remove @ionic-native/status-bar

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不涉及

配置

以下配置可用：

| 数据 | 类型 | 描述 | |------|------|------| | StatusBarOverlaysWebView | string | 配置是否沉浸式布局 | | StatusBarBackgroundColor | string | 配置状态栏颜色 | | StatusBarTextColor | string | 配置状态栏文字颜色 | | StatusBarStyle | string | 配置状态栏是否高亮度显示 | | NavigationBarBackgroundColor | string | 配置cordova内部系统导航条背景色 | | NavigationBarFontColor | string | 配置cordova内部系统导航条文字颜色 | | NavigationBarFontAlign | string | 配置cordova内部系统导航条title位置 | | NavigationBarLight | string | 配置cordova内部系统导航条是否高亮度显示 |

示例

config.xml

<preference name="StatusBarOverlaysWebView" value="true" />
<preference name="StatusBarBackgroundColor" value="#000000" />
<preference name="StatusBarTextColor" value="#ffffff" />
<preference name="StatusBarStyle" value="lightcontent" />
<preference name="NavigationBarBackgroundColor" value="#F90707" />
<preference name="NavigationBarFontColor" value="#ffffff" />
<preference name="NavigationBarFontAlign" value="center" />
<preference name="NavigationBarLight" value="true" />

使用示例

示例1：显示/隐藏状态栏

实现显示和隐藏状态栏的功能，支持带动画过渡效果。

import { StatusBar } from "@ionic-native/status-bar";

// 显示状态栏
const showStatusBar = async () => {
  try {
    await StatusBar.show();
    console.log('状态栏已显示');
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('显示状态栏失败:', errorMsg);
  }
};

// 隐藏状态栏
const hideStatusBar = async () => {
  try {
    await StatusBar.hide();
    console.log('状态栏已隐藏');
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('隐藏状态栏失败:', errorMsg);
  }
};

示例2：设置状态栏背景色

实现设置状态栏背景色的功能，支持十六进制颜色格式。

import { StatusBar } from "@ionic-native/status-bar";

const setStatusBarColor = async () => {
  try {
    // 设置状态栏背景色为蓝色
    await StatusBar.backgroundColorByHexString('#2196F3');
    console.log('状态栏背景色已设置为蓝色');
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('设置状态栏背景色失败:', errorMsg);
  }
};

示例3：设置状态栏文字颜色

实现设置状态栏文字颜色的功能，true为浅色，false为深色。

import { StatusBar } from "@ionic-native/status-bar";

const setStatusBarTextColor = async () => {
  try {
    // 设置状态栏文字为浅色（适用于深色背景）
    await StatusBar.styleLightContent(true);
    console.log('状态栏文字已设置为浅色');
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('设置状态栏文字颜色失败:', errorMsg);
  }
};

示例4：设置状态栏是否覆盖WebView

实现设置状态栏是否覆盖WebView的功能，true为覆盖，false为不覆盖。

import { StatusBar } from "@ionic-native/status-bar";

const setStatusBarOverlay = async () => {
  try {
    // 设置状态栏覆盖WebView（沉浸式）
    await StatusBar.overlaysWebView(true);
    console.log('状态栏已设置为覆盖WebView');
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('设置状态栏覆盖WebView失败:', errorMsg);
  }
};

示例5：检查状态栏是否可见

实现检查状态栏是否可见的功能。

import { StatusBar } from "@ionic-native/status-bar";

const checkStatusBarVisibility = async () => {
  try {
    const isVisible = StatusBar.isVisible;
    console.log('状态栏当前状态:', isVisible ? '显示中' : '隐藏中');
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('检查状态栏可见性失败:', errorMsg);
  }
};

使用说明

插件在全局对象 StatusBar 下暴露所有功能接口，使用前需确保设备就绪事件（deviceready）已触发。

1. 显示状态栏

显示状态栏，支持带动画过渡效果。

方法签名

StatusBar.show()

2. 隐藏状态栏

隐藏状态栏，支持带动画过渡效果。

方法签名

StatusBar.hide()

3. 设置状态栏背景色

设置状态栏背景色，支持十六进制颜色格式。

方法签名

StatusBar.backgroundColorByHexString(hexString)

4. 设置状态栏文字/图标颜色

设置状态栏文字/图标颜色，true为浅色，false为深色。

方法签名

StatusBar.styleLightContent(isLight)

5. 设置状态栏是否覆盖WebView

设置状态栏是否覆盖WebView，true为覆盖，false为不覆盖。

方法签名

StatusBar.overlaysWebView(overlay)

6. 使用默认状态栏样式

使用默认状态栏样式，深色文本 + 浅色背景。

方法签名

StatusBar.styleDefault()

7. 使用黑色半透明状态栏

使用黑色半透明状态栏，浅色文本 + 深色背景。

方法签名

StatusBar.styleBlackTranslucent()

8. 使用黑色不透明状态栏

使用黑色不透明状态栏，浅色文本 + 深色背景。

方法签名

StatusBar.styleBlackOpaque()

9. 检查状态栏是否可见

检查状态栏是否可见，只读属性。

属性签名

StatusBar.isVisible

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |---- cpp  # C++ 代码
|           |---- ets  # ArkTS 代码
|     |---- www    # Web 侧代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提Issue，当然，也非常欢迎发PR共建。

许可证

本插件基于Apache License 2.0开源，详见LICENSE文件。