@cordova-ohos/cordova-plugin-app-version

v0.1.15

Published

23 days ago

Cordova App Version Plugin

Downloads

810

0High
0Medium
0Low

cordova app-version ecosystem:cordova cordova-openharmony

cordova-plugin-app-version

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

cordova-plugin-app-version

简介

一款轻量级 Cordova 插件，专注于跨平台获取应用版本相关信息。无需关注不同操作系统的底层实现差异，即可轻松获取应用名称、版本号、构建号、包名（Android）/Bundle Name 等核心数据，广泛应用于应用更新检测、用户反馈统计、日志上报等场景，助力开发者高效实现版本相关业务逻辑。本文档说明在 OHOS 系统中的应用。

核心特性

跨平台一致性：一套代码适配 Android、iOS、OHOS 等多平台，无需编写平台专属逻辑
支持属性：支持获取应用名称、版本号（用户可见）、构建号（内部版本）、应用唯一标识（包名 / Bundle ID）
轻量无依赖：插件体积仅～40KB，无额外第三方依赖，不增加应用包体积负担
易用性强：API 设计简洁直观，3 行代码即可完成版本信息获取，降低开发学习成本
实时同步：获取的版本信息与应用配置实时同步，无需重启应用即可获取更新后的配置数据
TypeScript 兼容：内置类型定义文件，支持 TypeScript 项目开发，提供完整类型提示

支持平台

Android 平台：适配 Android 系统，支持获取应用名称、版本号、构建号、包名等信息。
iOS 平台：适配 iOS 系统，支持获取应用名称、版本号、构建号、Bundle ID 等信息。
OHOS 平台：适配 OHOS 系统，支持获取应用名称、版本号、构建号、Bundle Name 等信息，贴合 OHOS 应用配置规范。
Browser 平台：适配浏览器环境，支持基础版本信息获取。

下载安装

通过 hcordova 命令化工具完成插件的安装、卸载，支持全平台或指定 OHOS 平台操作。

安装插件

# 安装 hcordova
npm install -g hcordova

# 从 npm 全平台安装
hcordova plugin add cordova-plugin-app-version

# 从 npm 指定 OHOS 平台安装
hcordova plugin add cordova-plugin-app-version --platform ohos

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

# 从 GitCode 安装开发版
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-app-version.git --platform ohos

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

离线安装（本地包）

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

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

安装后验证

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

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

卸载插件

# 全平台卸载
hcordova plugin remove cordova-plugin-app-version

# 指定 OHOS 平台卸载
hcordova plugin remove cordova-plugin-app-version --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) |

常见问题

问题 1：OHOS 平台获取版本信息失败？解决：检查插件是否安装成功（通过 hcordova plugin list 确认），确保 OHOS 应用配置文件（module.json5）中已正确配置应用名称、版本号、Bundle Name，重新安装插件并重启项目。
问题 2：getPackageName 方法返回 undefined？解决：OHOS 平台需确保 module.json5 中 "bundleName" 字段配置正确，插件通过该字段获取 Bundle Name，配置后重新构建项目即可。
问题 3：deviceready 事件未触发，导致插件无法调用？解决：检查 Cordova 环境配置，确保 OHOS 平台添加正确，重新构建项目并重启应用，确保在 deviceready 事件后调用插件 API。

使用示例

以下示例均适配 OHOS 平台，涵盖基础使用、单独获取、TypeScript 用法，可直接复制到项目中使用（需确保 Cordova 环境就绪）。

示例 1：基础用法（批量获取所有版本信息）

一次性获取应用名称、版本号、构建号、Bundle Name 等所有信息，适合大多数场景：

// 等待 Cordova 环境完全加载（必须在 deviceready 事件后调用插件）
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
 // 检查插件是否成功加载
 if (window.cordova && window.cordova.plugins && window.cordova.plugins.appVersion) {
   const appVersion = window.cordova.plugins.appVersion;
   // 一次性获取所有版本信息（推荐，减少回调次数）
   appVersion.getVersionInfo((info) => {
     console.log("应用版本信息：", info);
     // OHOS 平台示例输出：
     // {
     //   appName: "MyApplication",    // 应用名称
     //   version: "3.2.1",            // 版本号（用户可见）
     //   build: "321",                // 构建号（内部版本）
     //   packageName: "com.example.myapp" // OHOS Bundle Name
     // }
     // 在页面中展示版本信息
     document.getElementById("app-name").textContent = info.appName;
     document.getElementById("app-version").textContent = `v${info.version} (build: ${info.build})`;
     document.getElementById("app-id").textContent = info.packageName || info.bundleId;
   }, (error) => {
     console.error("获取版本信息失败：", error);
     alert(`版本信息获取失败：${error.message}`);
   });
 } else {
   console.error("插件未加载，请检查安装是否正确");
 }
}

示例 2：单独获取指定版本信息

按需获取某一项版本数据，灵活适配不同业务场景，示例包含所有单独获取 API 的用法：

function getSingleInfoExample() {
 const appVersion = window.cordova.plugins.appVersion;
 // 1. 获取应用名称
 appVersion.getAppName((name) => {
   console.log("应用名称：", name); // 示例："MyApplication"
 }, (error) => {
   console.error("获取应用名称失败：", error);
 });

 // 2. 获取版本号（用户可见，如 "3.2.1"）
 appVersion.getVersion((version) => {
   console.log("应用版本号：", version);
 }, (error) => {
   console.error("获取版本号失败：", error);
 });

 // 3. 获取构建号（内部版本，如 "321"）
 appVersion.getBuild((build) => {
   console.log("应用构建号：", build);
 }, (error) => {
   console.error("获取构建号失败：", error);
 });

 // 4. 获取应用唯一标识（OHOS Bundle Name）
 appVersion.getPackageName((bundleId) => {
   console.log("OHOS Bundle Name：", bundleId); // 示例："com.example.myapp"
 }, (error) => {
   console.error("获取 Bundle ID 失败：", error);
 });
}

示例 3：TypeScript 用法

插件内置 TypeScript 类型定义，支持类型提示与语法校验，适配 TypeScript 开发的 OHOS Cordova 项目：

import type { AppVersionInfo, AppVersionPlugin } from "cordova-plugin-app-version";
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
 const appVersion: AppVersionPlugin = window.cordova?.plugins?.appVersion;
 if (!appVersion) {
   throw new Error("cordova-plugin-app-version 插件未加载");
 }

 // 获取所有版本信息（TypeScript 类型约束）
 appVersion.getVersionInfo((info: AppVersionInfo) => {
   // 自动提示字段：appName、version、build、packageName、bundleId
   console.log(`当前版本：v${info.version}，构建号：${info.build}`);
   console.log(`应用标识：${info.packageName || info.bundleId}`);
 }, (error: Error) => {
   console.error("获取版本信息失败：", error.message);
 });
}

示例 4：OHOS 平台单独获取 Bundle Name

针对 OHOS 平台常用场景，单独获取应用 Bundle Name 的简化示例：

const appVersion = window.cordova.plugins.appVersion;

// 获取 OHOS Bundle Name
appVersion.getPackageName((bundleId) => {
 console.log("OHOS Bundle Name：", bundleId); // 示例："com.example.myapp"
}, (error) => {
 console.error("获取 Bundle ID 失败：", error.message);
});

使用说明

本插件使用流程简洁，核心需遵循“环境就绪→调用 API→处理结果”的逻辑，以下为详细使用说明，重点适配 OHOS 平台使用场景，可结合上方使用示例理解：

1. 核心使用前提

插件所有 API 均需在 Cordova 环境完全就绪后调用，即必须在 deviceready 事件触发后执行，否则会出现“插件未加载”错误，导致 API 调用失败（所有示例均已遵循此前提）。

2. 核心使用流程

监听 deviceready 事件，确认 Cordova 环境加载完成；
检查插件是否成功加载（可选，建议添加，提升代码健壮性）；
调用对应 API 获取版本信息（批量获取或单独获取）；
在成功回调中处理返回的版本数据，失败回调中处理异常情况。

3. OHOS 平台注意事项

OHOS 平台中，getPackageName 方法获取的是应用的 Bundle Name，该值来源于 OHOS 应用配置文件（module.json5）中的 bundleName 字段，需确保该字段配置正确。
版本信息（应用名称、版本号、构建号）均同步于 OHOS 应用配置文件，若修改配置，需重新构建项目，插件才能获取到更新后的数据。
插件无需申请任何系统权限，安装后即可直接调用所有 API，无需额外配置权限声明。
TypeScript 项目可直接使用插件内置的类型定义，无需额外安装类型文件，支持完整类型提示。

4. 调用方式选择

批量获取（getVersionInfo）：推荐用于需要同时获取多类版本信息的场景（如应用关于页、版本更新检测），减少回调次数，提升代码简洁度（对应示例 1）。
单独获取（getAppName、getVersion 等）：适合仅需某一项版本数据的场景（如仅展示版本号），灵活适配不同业务需求（对应示例 2、示例 4）。

目录结构

cordova-plugin-app-version/
├── src/                          # 源代码目录
│   └── main/                     # 主要源代码
│       ├── cpp/                  # C++ 原生代码
│       │   └── AppVersion/       # 应用版本模块
│       │       ├── AppVersion.cpp  # 获取应用版本信息的 C++ 实现
│       │       └── AppVersion.h    # 获取应用版本信息的头文件
│       ├── ets/                  # ArkTS 代码（OpenHarmony API）
│       │   └── components/       # 组件目录
│       │       └── PluginAction/ # 插件动作组件
│       │           └── GetAppInfo.ets  # 获取应用信息的实现
│── www/                          # Web 资源目录
│   ├── AppVersionPlugin.js       # JavaScript 接口（Cordova 桥接层）
│   └── LICENSE                   # Web 资源的许可证文件
├── .gitignore                    # Git 忽略文件配置
├── LICENSE                       # 项目开源许可证
├── OAT.xml                       # OpenHarmony 审核配置文件
├── package.json                  # Node.js 包配置
├── plugin.xml                    # Cordova 插件描述文件（核心配置）
└── README.md                     # 项目说明文档

贡献代码

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

许可证

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

官方资源

OHOS 插件仓库：CPF-Cordova/cordova-plugin-app-version
Android、iOS 插件说明：cordova-plugin-app-version 官方指南
Cordova 官方文档：Cordova Documentation
OHOS 开发文档：OpenHarmony 官方文档