hcordova
v1.0.7
Published
Cordova CLI with OHOS support
Readme
hcordova OHOS 命令行工具
本项目对标上游 [email protected] 命令行工具，主要通过 OHOS cordova hcordova 命令行工具，构建 OHOS 项目，本文档重点阐述在 OHOS 系统中的应用
- hcordova OHOS 命令行工具
1. 项目概述
本项目基于 @cordova-ohos/ohos 开发，旨在通过 Web 技术（HTML5、CSS3、JavaScript）快速构建支持 Android、iOS、OHOS 三平台的原生移动应用。Cordova 框架将 Web 代码封装为原生应用容器，实现“一次开发，多端部署”，同时支持调用设备原生能力（如相机、定位、存储等），兼顾开发效率与原生体验。
项目核心特性：
跨平台兼容：同步支持 Android 7.0+、iOS 12.0+、OHOS 5.0+ 系统
原生能力集成：通过 Cordova 插件调用设备硬件功能
轻量化架构：基于 Web 技术栈，降低跨平台开发门槛
灵活扩展：支持自定义插件开发与第三方插件集成
2. 支持平台，环境准备
本项目为跨平台项目，支持 Linux、Windows、Mac 等系统，主要遵循 node 支持的平台。
2.1 基础依赖（必装）
- Node.js：v16.0.0 及以上（推荐 v18 LTS 版本）
node -v # 查看 Node 版本
npm -v # 查看 npm 版本- Git：用于版本控制与依赖拉取
2.2 平台专属依赖（按需安装）
2.2.1 OHOS 平台
DevEco 下载地址：https://developer.huawei.com
命令行工具下载地址：https://developer.huawei.com
安装操作方法：https://developer.huawei.com
2.2.2 Android 平台
Android Studio：用于 Android SDK 管理与模拟器运行
下载地址：developer.android.com/studio
安装后需配置：
安装 SDK Platforms：选择 Android 13（Tiramisu）及以上版本
安装 SDK Tools：勾选 "Android SDK Build-Tools"、"Android Emulator"、"Android SDK Platform-Tools"
配置环境变量
ANDROID_HOME（指向 SDK 安装目录，如C:\Users\<用户名>\AppData\Local\Android\Sdk）
2.2.3 iOS 平台（仅 macOS 支持）
Xcode：v14.0 及以上（含 iOS 模拟器与开发证书工具）
下载地址：Mac App Store 或 developer.apple.com/xcode
安装后需：
打开 Xcode 并同意许可协议
安装额外组件（Xcode 会自动提示）
配置 Apple 开发者账号（用于应用签名）
2.3 下载安装 hcordova CLI
通过 npm 全局安装 hcordova 命令行工具，用于项目创建、构建与管理：
npm install -g hcordova安装后验证：
hcordova -v # 输出 hcordova 版本（如 1.0.0）即表示成功3. 项目初始化与使用示例
3.1 创建项目
方式 1：新建项目（从零开始）
# 语法：cordova create <项目目录> <应用包名> <应用名称>
hcordova create MyApp com.example.MyApp MyHarmonyApp
# 进入项目目录
cd MyApp3.2 平台管理
Cordova 项目需先添加目标平台，才能进行构建与运行。
从 npm 添加平台（推荐）
# 添加 OHOS 平台
hcordova platform add ohos
# 指定版本添加，可以指定 branch、tag
hcordova platform add [email protected]
# 添加 Android 平台
hcordova platform add android
# 添加 iOS 平台（仅 macOS）
hcordova platform add ios从 GitCode 添加平台（开发版）
# 添加 OHOS 平台，仅支持 OHOS 平台
hcordova platform add https://gitcode.com/CPF-Cordova/cordova-openharmony.git
# 指定版本添加，可以指定 branch、tag
hcordova platform add https://gitcode.com/CPF-Cordova/cordova-openharmony.git@develop
查看已添加平台
hcordova platform ls
# 输出示例：Installed platforms:
# OHOS (installed)
# android 12.0.0
# ios 7.0.0更新/移除平台
# 移除 OHOS 平台
hcordova platform remove ohos
# 移除 Android 平台
hcordova platform remove android3.3 插件管理
HCordova 通过 插件 扩展应用能力（如调用相机、获取定位），核心插件由 Apache 维护，第三方插件可从 npm 获取。OHOS 插件有 OHOS 官方维护，gitcode 获取
安装插件
# 安装相机插件（核心插件）
hcordova plugin add cordova-plugin-camera
# 指定平台安装
hcordova plugin add cordova-plugin-camera --platform ohos
# 指定版本号安装（版本号不存在，默认最新版本号安装）
hcordova plugin add [email protected] --platform ohos
# 指定仓库安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-camera.git --platform ohos
# 安装自定义本地插件（需指定插件目录）
hcordova plugin add ../local-plugin-directory查看已安装插件
hcordova plugin ls
# 输出示例：@cordova-ohos/cordova-plugin-camera 7.0.0 "Camera"移除插件
# 全平台移除插件
hcordova plugin remove cordova-plugin-camera
# 指定平台移除插件
hcordova plugin remove cordova-plugin-camera --platform ohos4. 开发与调试
4.1 鸿蒙系统
项目构建成功后，推荐使用 DevEco 进行开发和调试，当前命令行工具不支持开发调试 4.2 本地浏览器预览（快速调试）
通过 Cordova 浏览器平台，可在电脑浏览器中快速预览应用界面与逻辑（不支持原生插件）：
# 添加浏览器平台（首次使用需添加）
hcordova platform add browser
# 运行浏览器预览
hcordova run browser
# 效果：自动打开浏览器，地址为 http://localhost:80004.3 模拟器/真机运行（推荐 cordova 命令工具）
运行 Android 应用
# 方式 1：自动检测模拟器/真机并运行
cordova run android
# 方式 2：仅运行到模拟器
cordova emulate android
# 方式 3：带调试模式运行（支持 Chrome 开发者工具调试）
cordova run android --debug运行 iOS 应用（仅 macOS）
# 方式 1：自动检测模拟器/真机并运行
cordova run ios
# 方式 2：指定模拟器型号（如 iPhone 15）
cordova run ios --emulator="iPhone 15"
# 方式 3：带调试模式运行（支持 Safari 开发者工具调试）
cordova run ios --debug4.4 日志查看
- Android 日志：建议采用 Android Studio 查看日志
- iOS 日志：建议采用 Xcode 查看日志
- OHOS 日志：建议采用 DevEco 查看日志
4.5 兼容性
本项目在以下系统中测试通过：
CentOS 7，CentOS 9，Windows 10/11，macOS 系统上进行测试
5. 项目目录结构说明
通过 hcordova 创建项目后的目录结构如下：
your-cordova-app/
|—— harmonyos # ohos 工程目录（目录名称保持和之前版本相同）
|—— oh-plugins # 鸿蒙专用插件
├── config.xml # 项目配置文件（应用名称、版本、权限、插件配置等）
├── www/ # Web 代码目录（核心开发目录）
│ ├── index.html # 应用入口页面
│ ├── css/ # 样式文件目录
│ ├── js/ # 脚本文件目录（含 cordova.js，自动注入）
│ └── img/ # 图片资源目录
├── platforms/ # 平台目录（自动生成，存放 Android/iOS 原生项目）
├── plugins/ # 插件目录（自动生成，存放已安装插件）
├── hooks/ # 钩子脚本目录（可选，用于自定义构建流程）
└── package.json # 项目依赖配置文件6. hcordova 项目目录结构
hcordova # [根目录] hcordova 命令行工具项目根目录
├── bin # [可执行文件] 存放命令行入口脚本
│ └── hcordova # [入口脚本] CLI 的主执行文件
├── src # [源码目录] 存放工具的核心逻辑代码
│ └── utils # [工具类] 存放各种辅助功能的模块
│ ├── DependencyChecker.js # [工具] 依赖检查器：用于检查系统环境或项目依赖是否满足要求
│ ├── PlatformProject.js # [工具] 平台项目管理：处理特定平台（如 OHOS）的项目结构操作
│ ├── PluginConfigParser.js # [工具] 插件配置解析器：解析 plugin.xml 或相关配置文件
│ ├── PluginDownloader.js # [工具] 插件下载器：负责从仓库下载插件包
│ ├── PluginHandler.js # [工具] 插件处理器：执行插件的安装、卸载、更新逻辑
│ ├── ReleaseFetcher.js # [工具] 版本获取器：用于获取最新发布版本的信息
│ └── VariableValidator.js # [工具] 变量验证器：验证用户输入或配置变量的合法性
│ └── base-cli.js # [核心逻辑] CLI 的基础命令定义和主逻辑入口
├── templates # [模板目录] 存放创建新项目或文件时使用的模板文件
├── .gitignore # [配置] Git 版本控制忽略文件配置
├── LICENSE # [文本] 开源许可证文件
├── OAT.xml # [配置] 开源软件声明文件（Open Source Acknowledgment Tool）
├── package-lock.json # [锁定] NPM 依赖版本锁定文件，确保安装的一致性
├── package.json # [配置] NPM 包配置文件，定义依赖、脚本和元数据
└── README.md # [文档] 项目说明文档7. 贡献代码
使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。
8. 许可证
本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。
9. 官方资源
官方文档：Apache Cordova 文档
Apache Cordova 核心插件列表：Cordova Plugins
Harmony Cordova 插件列表：gitcode
HarmonyOS 发布指南：DevEco 发布应用