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 及以上)，若未安装，可执行以下命令：

npm install -g hcordova

3. 已创建 Cordova 项目（若尚未创建，可通过 hcordova create MyStatusBarApp com.example.statusbarapp 状态栏示例应用 命令快速创建）。

3.2 插件安装命令

在 Cordova 项目根目录下，根据需求选择以下方式安装插件：

默认安装

hcordova plugin add cordova-plugin-statusbar

从 GitCode 源码安装

hcordova plugin add https://github.com/apache/cordova-plugin-statusbar.git --platform ohos

安装指定版本

若项目需兼容特定版本插件，可指定版本号安装（例如安装 4.0.0 版本）：

hcordova plugin add [email protected] --platform ohos

3.3 插件卸载命令

若需移除插件，在项目根目录执行以下命令：

#全平台卸载
hcordova plugin remove cordova-plugin-statusbar

#指定平台卸载
hcordova plugin remove cordova-plugin-statusbar --platform ohos

3.4 插件查看命令

安装完成后，可通过以下命令验证插件是否成功添加到项目中：

hcordova plugin list

若输出结果包含 cordova-plugin-statusbar，则表示插件已成功安装。

4. 核心配置（config.xml）

状态栏的基础样式和默认行为需在项目根目录的 config.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）

用于在应用运行过程中显示已隐藏的状态栏，支持带动画过渡效果（部分平台支持）。

方法说明

StatusBar.show();

示例代码

// 等待 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）

用于在应用运行过程中隐藏状态栏，支持带动画过渡效果（部分平台支持），适合全屏场景（如视频播放、游戏）。

方法说明

StatusBar.hide();

示例代码

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）

动态修改状态栏背景色，支持十六进制颜色格式（需带 # 前缀），适用于根据页面主题动态切换状态栏颜色的场景（如深色模式 / 浅色模式切换）。

方法说明

StatusBar.backgroundColorByHexString(hexString);

参数说明

| 参数名 | 类型 | 是否必选 | 说明 | | ----------- | ------ | ---- | ------------------------------------------------------------------------------------- | | hexString | String | 是 | 状态栏背景色的十六进制字符串，格式为 #RRGGBB 或 #RRGGBBAA（带透明度），例如 #2196F3（蓝色）、#FF572280（橙色半透明）。 |

示例代码

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）

动态控制状态栏文字和图标的颜色（浅色 / 深色），确保在不同背景色下的可读性（如深色背景配浅色文字，浅色背景配深色文字）。

方法说明

StatusBar.styleLightContent(isLight);

参数说明

| 参数名 | 类型 | 是否必选 | 说明 | | --------- | ------- | ---- | --------------------------------------------------------------------------------- | | isLight | Boolean | 是 | 状态栏文字 / 图标是否为浅色：- true：文字 / 图标为浅色（白色），适用于深色背景；- false：文字 / 图标为深色（黑色），适用于浅色背景。 |

示例代码

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 界面，用于适配不同页面的布局需求（如部分页面需要避开状态栏，部分页面需要沉浸式覆盖）。

方法说明

StatusBar.overlaysWebView(overlay);

参数说明

| 参数名 | 类型 | 是否必选 | 说明 | | --------- | ------- | ---- | --------------------------------------------------------------------------------------------- | | overlay | Boolean | 是 | 是否覆盖 WebView：- true：状态栏覆盖 WebView，WebView 内容从顶部开始渲染；- false：WebView 从状态栏下方开始渲染，自动添加顶部内边距。 |

示例代码

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）

获取当前状态栏的可见状态（显示 / 隐藏），用于判断当前布局是否需要适配状态栏。

方法说明

var isVisible = StatusBar.isVisible;

返回值说明

| 返回值类型 | 说明 | | ------- | --------------------------------------- | | Boolean | true：状态栏当前处于显示状态；false：状态栏当前处于隐藏状态。 |

示例代码

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 文件。

7. 联系方式与支持

若你在使用过程中遇到问题或有功能建议，可通过以下渠道获取支持：

OHOS

• GitHub 仓库：https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-statusbar

• 提交 Issue：在仓库的 Issues 页面提交问题描述（需包含平台版本、插件版本、复现步骤及错误日志），官方团队会在 1-3 个工作日内回复。

Android/iOS

• Apache Cordova 官方论坛：https://cordova.apache.org/community/