@cordova-ohos/cordova-plugin-navigationbar

v1.0.32

Published

13 days ago

Cordova Navigationbar Plugin

0High
0Medium
0Low

cordova navigationbar ecosystem:cordova cordova-openharmony

cordova-plugin-navigationbar

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

cordova-plugin-navigationbar

简介

cordova-plugin-navigationbar 是一款专为 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

指定平台安装 ohos

仅为 OHOS 平台安装插件：

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

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

从 GitCode 仓库安装

仅为 OHOS 平台安装插件：

# 仅安装到 OHOS 平台

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

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

离线安装（本地包）

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

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

安装后验证

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

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

卸载

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

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

约束与限制

本插件强制依赖于 cordova-plugin-navigationbar-color 插件，具体功能由 cordova-plugin-navigationbar-color 插件实现

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | 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.setUp(true,function(){
        console.log("设置成功");
});

2. 隐藏导航栏

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

NavigationBar.hide();

使用说明

核心说明

插件调用：所有 API 均通过全局对象 window.NavigationBar 调用，无需额外引入，直接调用对应方法即可。
功能说明：setUp(true) 用于显示导航栏，hide() 用于隐藏导航栏，适配系统原生导航栏规则，临时隐藏后切换页面可能恢复显示，永久隐藏需遵循对应系统规则。
权限说明：插件无需额外申请权限，自动适配系统导航栏控制权限，无需手动编写权限申请代码。
错误处理：API 调用失败时，可通过回调函数查看错误信息，便于问题排查。

目录结构

cordova-plugin-navigationbar  # [根目录] 导航栏插件项目根目录
├── .gitignore                # [Git 配置] 指定 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

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