npm package: @luqi_test/cordova-plugin-statusbar
Description: Cordova statusbar Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 4.0.0

# cordova-plugin-statusbar

## 1. 插件介绍

`cordova-plugin-statusbar` 是 Apache Cordova 生态中用于管理移动应用状态栏（Status Bar）的核心插件。状态栏作为移动设备屏幕顶部的系统级界面元素，包含时间、电池电量、信号强度等关键信息，该插件允许开发者在跨平台 Cordova 应用中，对状态栏的样式、可见性、行为进行全方位自定义，从而实现应用视觉风格与系统状态栏的统一，提升用户体验，本文档主要说明该插件在OHOS系统中的应用

## 2. 支持平台

该插件已针对以下操作系统和平台完成深度适配，确保状态栏控制功能的稳定性和兼容性：

* **Android** (API 级别 21 及以上，覆盖 Android 5.0 及更高版本，支持 Material Design 风格状态栏配置)

* **iOS** (iOS 10.0 及以上，支持 iPhone、iPad 全系列设备，含 iOS 15+ 动态岛、 notch 屏适配)

* **Windows** (Windows 10 及以上，包含 UWP 通用应用场景，支持桌面端与移动端状态栏统一控制)

* **Browser** (主流桌面及移动浏览器，如 Chrome、Firefox、Edge、Safari，模拟状态栏样式与行为)

* **OHOS** (5.0+)

## 3. 安装步骤

### 3.1 前提条件

在安装插件前，请确保开发环境满足以下基础要求：



1. 已安装 Node.js (v14.0.0 及以上) 和 npm (v6.0.0 及以上)，可通过 `node -v` 和 `npm -v` 命令验证版本。

2. 已全局安装 Cordova CLI (v10.0.0 及以上)，若未安装，可执行以下命令：



```bash
npm install -g hcordova
```

3. 已创建 Cordova 项目（若尚未创建，可通过 `hcordova create MyStatusBarApp com.example.statusbarapp 状态栏示例应用` 命令快速创建）。


### 3.2 插件安装命令

在 Cordova 项目根目录下，根据需求选择以下方式安装插件：

#### 默认安装


```bash
hcordova plugin add cordova-plugin-statusbar
```

#### 从 GitCode 源码安装


```bash
hcordova plugin add https://github.com/apache/cordova-plugin-statusbar.git --platform ohos
```

#### 安装指定版本

若项目需兼容特定版本插件，可指定版本号安装（例如安装 4.0.0 版本）：



```bash
hcordova plugin add cordova-plugin-statusbar@4.0.0 --platform ohos
```

### 3.3 插件卸载命令

若需移除插件，在项目根目录执行以下命令：



```bash
#全平台卸载
hcordova plugin remove cordova-plugin-statusbar

#指定平台卸载
hcordova plugin remove cordova-plugin-statusbar --platform ohos
```

### 3.4 插件查看命令

安装完成后，可通过以下命令验证插件是否成功添加到项目中：



```bash
hcordova plugin list
```

若输出结果包含 `cordova-plugin-statusbar`，则表示插件已成功安装。

## 4. 核心配置（config.xml）

状态栏的基础样式和默认行为需在项目根目录的 `config.xml` 文件中配置，配置项会在应用启动时生效，覆盖系统默认状态栏设置。以下是完整的配置示例及详细说明：

```xml
<!--配置是否沉浸式布局,系统模式是非沉浸式布局 -->
<  preference name="StatusBarOverlaysWebView" value="true" />
<!--配置状态栏颜色 -->
< preference name="StatusBarBackgroundColor" value="#000000" />
<!--配置状态栏文字颜色,在鸿蒙中新增加的属性，安卓和ios不具备 -->
< preference name="StatusBarTextColor" value="#ffffff" />
<!--配置状态栏是否高亮度显示,-->
<!--在鸿蒙中，默认是非高亮度的，所以不是高亮度的不要配置 -->
< preference name="StatusBarStyle" value="lightcontent" />
<!--cordova内部系统导航条背景色 -->
< preference name="NavigationBarBackgroundColor" value="#F90707" />
<!--cordova内部系统导航条文字颜色 -->
< preference name="NavigationBarFontColor" value="#ffffff" />
<!--cordova内部系统导航条title位置left|center|right -->
< preference name="NavigationBarFontAlign" value="center" />
<!--导航条高亮显示，在鸿蒙中，默认是非高亮度的，所以不是高亮度的不要配置-->
< preference name="NavigationBarLight" value="true" />
```

## 5. 核心 API 说明

插件通过全局对象 `StatusBar` 暴露状态栏控制 API，支持在应用运行过程中动态修改状态栏样式、可见性等属性。所有 API 需在 `deviceready` 事件触发后调用（确保 Cordova 环境就绪），以下是各 API 的详细说明：

### 5.1 显示状态栏（show）

用于在应用运行过程中显示已隐藏的状态栏，支持带动画过渡效果（部分平台支持）。

#### 方法说明

```js
StatusBar.show();
```


#### 示例代码


```js
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
  // 点击按钮显示状态栏
  document.getElementById('showStatusBarBtn').addEventListener('click', function() {
      if (typeof StatusBar !== 'undefined') {
          // 带动画显示状态栏
          StatusBar.show();
          console.log('状态栏已显示（带动画）');
      } else {
          console.error('StatusBar API 未加载，可能是插件未安装或环境未就绪');
      }
  });
}, false);
```

### 5.2 隐藏状态栏（hide）

用于在应用运行过程中隐藏状态栏，支持带动画过渡效果（部分平台支持），适合全屏场景（如视频播放、游戏）。

#### 方法说明


```js
StatusBar.hide();
```


#### 示例代码


```js
document.addEventListener('deviceready', function() {
  // 点击“进入全屏”按钮隐藏状态栏
  document.getElementById('enterFullscreenBtn').addEventListener('click', function() {
      if (StatusBar) {
          // 带动画隐藏状态栏
          StatusBar.hide(true);
          // 同时设置 WebView 全屏（避免状态栏隐藏后留下空白）
          document.body.style.height = '100vh';
          document.body.style.overflow = 'hidden';
          console.log('已隐藏状态栏，进入全屏模式');
      }
  });

  // 点击“退出全屏”按钮显示状态栏
  document.getElementById('exitFullscreenBtn').addEventListener('click', function() {
      if (StatusBar) {
          StatusBar.show(true);
          document.body.style.height = 'auto';
          document.body.style.overflow = 'auto';
          console.log('已显示状态栏，退出全屏模式');
      }
  });
}, false);
```

### 5.3 设置状态栏背景色（backgroundColorByHexString）

动态修改状态栏背景色，支持十六进制颜色格式（需带 `#` 前缀），适用于根据页面主题动态切换状态栏颜色的场景（如深色模式 / 浅色模式切换）。

#### 方法说明

```js
StatusBar.backgroundColorByHexString(hexString);
```

#### 参数说明


| 参数名         | 类型     | 是否必选 | 说明                                                                                    |
| ----------- | ------ | ---- | ------------------------------------------------------------------------------------- |
| `hexString` | String | 是    | 状态栏背景色的十六进制字符串，格式为 `#RRGGBB` 或 `#RRGGBBAA`（带透明度），例如 `#2196F3`（蓝色）、`#FF572280`（橙色半透明）。 |

#### 示例代码


```js
document.addEventListener('deviceready', function() {
  // 切换深色模式时，修改状态栏为深色背景+浅色文字
  document.getElementById('darkModeBtn').addEventListener('click', function() {
      if (StatusBar) {
          // 设置状态栏背景色为深灰色
          StatusBar.backgroundColorByHexString('#212121');

          // 设置状态栏文字/图标为浅色（适配深色背景）
          StatusBar.styleLightContent(true);

          // 同步修改页面背景色（保持风格统一）
          document.body.style.backgroundColor = '#212121';
          document.body.style.color = 'white';
          console.log('已切换为深色模式，状态栏背景色：#212121，文字颜色：浅色');
      }
  });

  // 切换浅色模式时，修改状态栏为浅色背景+深色文字
  document.getElementById('lightModeBtn').addEventListener('click', function() {
      if (StatusBar) {
          StatusBar.backgroundColorByHexString('#FFFFFF');
          StatusBar.styleLightContent(false);
          document.body.style.backgroundColor = '#FFFFFF';
          document.body.style.color = '#333333';
          console.log('已切换为浅色模式，状态栏背景色：#FFFFFF，文字颜色：深色');
      }
  });
}, false);
```

### 5.4 设置状态栏文字 / 图标颜色（styleLightContent）

动态控制状态栏文字和图标的颜色（浅色 / 深色），确保在不同背景色下的可读性（如深色背景配浅色文字，浅色背景配深色文字）。

#### 方法说明

```js
StatusBar.styleLightContent(isLight);
```

#### 参数说明



| 参数名       | 类型      | 是否必选 | 说明                                                                                |
| --------- | ------- | ---- | --------------------------------------------------------------------------------- |
| `isLight` | Boolean | 是    | 状态栏文字 / 图标是否为浅色：- `true`：文字 / 图标为浅色（白色），适用于深色背景；- `false`：文字 / 图标为深色（黑色），适用于浅色背景。 |

#### 示例代码



```js
document.addEventListener('deviceready', function() {
  // 监听页面滚动，根据滚动高度切换状态栏文字颜色
  window.addEventListener('scroll', function() {
      if (StatusBar && window.scrollY > 100) {
          // 滚动高度超过 100px，状态栏背景变为白色，文字变为深色
          StatusBar.backgroundColorByHexString('#FFFFFF');
          StatusBar.styleLightContent(false);
      } else {
          // 滚动高度小于等于 100px，状态栏背景变为蓝色，文字变为浅色
          StatusBar.backgroundColorByHexString('#2196F3');
          StatusBar.styleLightContent(true);
      }
  });
}, false);
```

### 5.5 设置状态栏是否覆盖 WebView（overlaysWebView）

动态切换状态栏是否覆盖 WebView 界面，用于适配不同页面的布局需求（如部分页面需要避开状态栏，部分页面需要沉浸式覆盖）。

#### 方法说明


```js
StatusBar.overlaysWebView(overlay);
```

#### 参数说明


| 参数名       | 类型      | 是否必选 | 说明                                                                                            |
| --------- | ------- | ---- | --------------------------------------------------------------------------------------------- |
| `overlay` | Boolean | 是    | 是否覆盖 WebView：- `true`：状态栏覆盖 WebView，WebView 内容从顶部开始渲染；- `false`：WebView 从状态栏下方开始渲染，自动添加顶部内边距。 |

#### 示例代码



```js
document.addEventListener('deviceready', function() {
  // 文章详情页：禁用状态栏覆盖，避免文字被遮挡
  document.getElementById('articleDetailBtn').addEventListener('click', function() {
      if (StatusBar) {
          StatusBar.overlaysWebView(false);
          // 手动添加顶部内边距（确保内容完全避开状态栏）
          document.getElementById('articleContainer').style.paddingTop = '20px';
          console.log('文章详情页：状态栏不覆盖 WebView，已添加顶部内边距');
      }
      // 切换到文章详情页 DOM 逻辑
      showArticleDetail();
  });

  // 图片预览页：启用状态栏覆盖，实现沉浸式预览
  document.getElementById('imagePreviewBtn').addEventListener('click', function() {
      if (StatusBar) {
          StatusBar.overlaysWebView(true);
          // 移除顶部内边距，图片全屏显示
          document.getElementById('imageContainer').style.paddingTop = '0';
          console.log('图片预览页：状态栏覆盖 WebView，实现沉浸式预览');
      }
      // 切换到图片预览页 DOM 逻辑
      showImagePreview();
  });
}, false);
```

### 5.6 检查状态栏是否可见（isVisible）

获取当前状态栏的可见状态（显示 / 隐藏），用于判断当前布局是否需要适配状态栏。

#### 方法说明



```js
var isVisible = StatusBar.isVisible;
```

#### 返回值说明



| 返回值类型   | 说明                                      |
| ------- | --------------------------------------- |
| Boolean | `true`：状态栏当前处于显示状态；`false`：状态栏当前处于隐藏状态。 |

#### 示例代码



```js
document.addEventListener('deviceready', function() {
  // 定时检查状态栏状态，在控制台输出
  setInterval(function() {
      if (StatusBar) {
          const status = StatusBar.isVisible ? '显示中' : '隐藏中';
          console.log(`当前状态栏状态：${status}`);
          // 根据状态栏状态更新 UI 提示
          document.getElementById('statusBarStatus').textContent = `状态栏：${status}`;
      }
  }, 1000);
}, false);
```


## 6. 许可证

本插件基于 **Apache License 2.0** 开源协议发布，详细许可条款请查看项目根目录下的 [LICENSE](LICENSE) 文件。


## 7. 联系方式与支持

若你在使用过程中遇到问题或有功能建议，可通过以下渠道获取支持：

### OHOS

* GitHub 仓库：[https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-statusbar](https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-statusbar)

* 提交 Issue：在仓库的 Issues 页面提交问题描述（需包含平台版本、插件版本、复现步骤及错误日志），官方团队会在 1-3 个工作日内回复。

### Android/iOS

* Apache Cordova 官方论坛：[https://cordova.apache.org/community/](https://cordova.apache.org/community/)