@capacitor/status-bar

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/status-bar 是 capacitor 生态系统中的核心插件，StatusBar API 提供了配置状态栏样式以及显示或隐藏状态栏的方法，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境，本文档主要说明在 OpenHarmony 系统中的使用。

该插件可以控制状态栏的显示隐藏、样式风格（深色/浅色）、背景颜色，帮助开发者统一应用状态栏样式，提升应用整体视觉效果。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

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

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/status-bar

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

[
  {
    "pkg": "@capacitor/status-bar",
    "classpath": "StatusBar"
  }
]

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(StatusBar)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  StatusBar
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

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

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

4. 添加 ArkTS 配置

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

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

卸载

# 卸载 status-bar 插件
hionic plugin remove @capacitor/status-bar

配置

在 capacitor.config.json 中可以配置默认状态栏样式：

{
  "plugins": {
     "StatusBar": {
        "overlaysWebView": true,
        "style": "DARK",
        "backgroundColor": "#ffffff"
     }
  }
}

| 配置项 | 类型 | 描述 | |---------|------|------| | overlaysWebView | boolean | 状态栏是否覆盖 WebView | | style | string | 状态栏文本的样式 | | backgroundColor | string | 状态栏背景颜色的十六进制格式，#RRGGBB。如果 overlaysWebView 为 true 则不生效 |

约束与限制

兼容性

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

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

权限要求

不涉及特殊权限。

使用示例

基础示例：切换状态栏样式

import { StatusBar, Style } from '@capacitor/status-bar';

const toggleStyle = async (currentStyle) => {
  try {
    // 切换状态栏样式（深色/浅色）
    const newStyle = currentStyle.value === Style.Dark ? Style.Light : Style.Dark;
    await StatusBar.setStyle({ style: newStyle });
    
    console.log(`状态栏样式已切换为: ${newStyle}`);
  } catch (error) {
    console.error('设置状态栏样式失败:', error);
  }
};

基础示例：设置状态栏背景色

import { StatusBar } from '@capacitor/status-bar';

const setRandomBackgroundColor = async () => {
  try {
    const colors = ['#FF5733', '#33FF57', '#3357FF', '#F333FF', '#33FFF5'];
    const randomColor = colors[Math.floor(Math.random() * colors.length)];
    
    await StatusBar.setBackgroundColor({ color: randomColor });
    console.log(`状态栏背景颜色已设置为: ${randomColor}`);
  } catch (error) {
    console.error('设置状态栏背景颜色失败:', error);
  }
};

基础示例：显示/隐藏状态栏

import { StatusBar } from '@capacitor/status-bar';

const toggleVisibility = async (currentVisible) => {
  try {
    if (currentVisible) {
      await StatusBar.hide();
      console.log('状态栏已隐藏');
    } else {
      await StatusBar.show();
      console.log('状态栏已显示');
    }
  } catch (error) {
    console.error('切换状态栏显示失败:', error);
  }
};

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | |----------------------------------------------------------|--------------------------|-------------------------------------| | setStyle(options: StyleOptions) | Promise<void> | 设置状态栏的当前样式 | | setBackgroundColor(options: BackgroundColorOptions) | Promise<void> | 设置状态栏的背景色 | | show() | Promise<void> | 显示状态栏 | | hide() | Promise<void> | 隐藏状态栏 | | getInfo() | Promise<StatusBarInfo> | 获取关于状态栏当前状态的信息 | | setOverlaysWebView(options: SetOverlaysWebViewOptions) | Promise<void> | 设置状态栏是否应覆盖在 WebView 之上，以允许使用其下方的空间 |

数据结构

StyleOptions

| 属性 | 类型 | 描述 | | ------------ | -------- |-------------| | style | Style | 状态栏文本的样式 |

BackgroundColorOptions

| 属性 | 类型 | 描述 | | ------------ | -------- | ------------------------------------------------------------ | | color | string | 用于设置状态栏颜色的十六进制颜色值 |

StatusBarInfo

| 属性 | 类型 | 描述 | | ------------ | -------- |--------------| | visible | boolean | 状态栏当前是否处于可见状态 | | style | Style | 当前的状态栏样式 | | color | string | 当前的状态栏颜色 | | overlays| boolean | 状态栏是否处于覆盖模式 |

Style

样式枚举：

| 成员 | 值 | 描述 | | ------------ | ---------- |---------------| | Dark | DARK | 用于深色背景的浅色文本 | | Light | LIGHT | 用于浅色背景的深色文本 | | Default | DEFAULT| 样式取决于设备的外观设置 |

SetOverlaysWebViewOptions

| 属性 | 类型 | 描述 | | ------------ | -------- |-------------| | overlay | boolean | 状态栏是否覆盖 WebView |

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- StatusBar   # 插件核心 C++ 实现
|                             |---- StatusBar.cpp
|                             |---- StatusBar.h
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- StatusBar   # ArkTS 组件实现
|                                   |---- StatusBar.ets
|                                   |---- StatusBarInfo.ets
|     |---- README.md                # 说明文档
|     |---- package.json             # npm 配置文件
|     |---- plugin.xml               # capacitor 插件配置
|     |---- LICENSE                  # 许可证文件

贡献代码

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

许可证

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