@cordova-ohos/cordova-plugin-navigationbar-color

v0.1.1

Published

4 days ago

Cordova Navigationbar Plugin

0High
0Medium
0Low

cordova navigationbar-color ecosystem:cordova cordova-openharmony

cordova-plugin-navigationbar-color

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

cordova-plugin-navigationbar-color

简介

cordova-plugin-navigationbar-color 是一款专为 Cordova 混合移动应用打造的导航栏控制插件，支持跨平台自定义设备导航栏的显示和隐藏等核心属性，助力开发者实现与应用风格统一的导航栏视觉效果，提升用户体验。

灵活显示控制：支持导航栏的显示/隐藏切换，可设置临时隐藏或永久隐藏（需适配系统规则）
无依赖轻量设计：不依赖第三方 UI 库，插件体积小巧，对应用性能影响极小

支持平台

Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+

下载安装

通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取。

从 npm 安装（推荐）

# 使用 hcordova CLI 安装

# 安装 hcordova 命令化工具
npm install -g hcordova

# 全平台安装插件
hcordova plugin add cordova-plugin-navigationbar-color

指定平台安装 ohos

仅为 OHOS 平台安装插件：

# 仅安装到 OHOS 平台
hcordova plugin add cordova-plugin-navigationbar-color --platform ohos

# 指定版本安装
hcordova plugin add [email protected] --platform ohos

从 GitCode 仓库安装

仅为 OHOS 平台安装插件：

# 仅安装到 OHOS 平台

# 默认分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-navigationbar-color.git --platform ohos

# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-navigationbar-color.git@develop --platform ohos

离线安装（本地包）

适用于无网络环境，先下载插件包到本地，再执行离线安装：

# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-navigationbar-color）
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-plugin-navigationbar-color --platform ohos

安装后验证

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

# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list

卸载

# Cordova CLI 全平台卸载
hcordova plugin remove cordova-plugin-navigationbar-color 

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

约束与限制

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |

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

| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |

使用示例

插件暴露全局对象 window.NavigationBar，所有方法均支持回调函数语法，以下为核心功能的使用示例，可直接复制到项目中使用。

1. 显示导航栏

显示隐藏的导航栏，若导航栏已显示则无效果。

NavigationBar.show();

2. 隐藏导航栏

隐藏当前显示的导航栏，实现沉浸式全屏效果。

NavigationBar.hide();

3. 设置导航栏颜色

支持通过颜色名称或十六进制颜色字符串设置导航栏颜色，可指定是否高亮显示导航栏。

参数说明：

colorname：颜色名称（支持常见标准颜色）
hexString：十六进制颜色字符串（如 #000000）
lightNavigationBar：是否高亮显示导航栏（布尔值）

支持的颜色名称及对应十六进制值：

| 名称 | 颜色 | |---|---| | "black" | "#000000" | | "darkGray" | "#A9A9A9" | | "lightGray" | "#D3D3D3" | | "white" | "#FFFFFF" | | "gray" | "#808080" | | "red" | "#FF0000" | | "green" | "#00FF00" | | "blue" | "#0000FF" | | "cyan" | "#00FFFF" | | "yellow" | "#FFFF00" | | "magenta" | "#FF00FF" | | "orange" | "#FFA500" | | "purple" | "#800080" | | "brown" | "#A52A2A" |

// 通过名称设置导航栏颜色
NavigationBar.backgroundColorByName("blue", false);

// 通过十六进制字符串设置导航栏颜色
NavigationBar.backgroundColorByHexString("#000000", false);

使用说明

核心说明

插件调用：所有 API 均通过全局对象 window.NavigationBar 调用，无需额外引入，直接调用对应方法即可。
功能说明：show() 用于显示导航栏，hide() 用于隐藏导航栏；backgroundColorByName() 和 backgroundColorByHexString() 用于设置导航栏颜色，适配系统原生导航栏规则，临时隐藏后切换页面可能恢复显示，永久隐藏需遵循对应系统规则。
颜色设置说明：颜色名称需严格匹配支持的列表，十六进制颜色字符串需规范（以 # 开头，后跟 6 位字符）；lightNavigationBar 参数设为 true 时导航栏高亮显示，false 时为默认显示效果。
权限说明：插件无需额外申请权限，自动适配系统导航栏控制权限，无需手动编写权限申请代码。
错误处理：API 调用失败时，可通过回调函数查看错误信息，便于问题排查；颜色设置不生效时，需检查颜色名称/十六进制字符串是否正确、平台是否适配。

目录结构

cordova-plugin-navigationbar-color # [根目录] 导航栏颜色插件项目根目录
├── src                            # [源码目录] 存放原生平台代码
│   └── main                       # [主目录] 主代码目录
│       ├── cpp                    # [C++ 目录] C++ 原生代码目录
│       │   └── NavigationBar      # [C++ 模块] 导航栏 C++ 模块文件夹
│       │       ├── NavigationBar.cpp # [C++ 实现] C++ 源文件，实现底层逻辑
│       │       └── NavigationBar.h   # [C++ 声明] C++ 头文件，定义接口
│       └── ets                    # [ArkTS 目录] ArkTS/ETS 代码目录
│           └── components         # [组件目录] 存放 UI 组件
│               └── NavigationBar  # [TS 模块] 导航栏 TS 模块文件夹
│                   └── NavigationBar.ets # [ETS 文件] ArkTS 界面组件实现
├── www                            # [前端目录] 存放供 Web 端调用的 JS 接口文件
│   └── navigationbar.js           # [JS 文件] 导航栏操作的 JS 接口逻辑
├── .gitignore                     # [配置文件] Git 版本控制忽略列表
├── LICENSE                        # [文本文件] 项目开源许可证
├── OAT.xml                        # [配置文件] 门禁审查文件
├── package.json                   # [配置文件] NPM 包管理及依赖配置
├── plugin.xml                     # [配置文件] Cordova 插件核心配置文件
└── README.md                      # [说明文档] 项目的使用说明文档

贡献代码

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

许可证

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

官方资源

OHOS Cordova https://gitcode.com/CPF-Cordova/cordova-plugin-navigationbar-color

Android/iOS：https://npmjs.com/cordova-plugin-navigationbar-color