cordova-plugin-app-version

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

核心特性

1. 跨平台一致性：一套代码适配 Android、iOS、Browser 等多平台，无需编写平台专属逻辑

2. 信息全面性：支持获取应用名称、版本号（用户可见）、构建号（内部版本）、应用唯一标识（包名 / Bundle ID）

3. 轻量无依赖：插件体积仅～40KB，无额外第三方依赖，不增加应用包体积负担

4. 易用性强：API 设计简洁直观，3 行代码即可完成版本信息获取，降低开发学习成本

5. 实时同步：获取的版本信息与应用配置实时同步，无需重启应用即可获取更新后的配置数据

6. TypeScript 兼容：内置类型定义文件，支持 TypeScript 项目开发，提供完整类型提示

安装指南

1. 基础安装（推荐）

常用安装，自动集成到 Cordova 项目：

# 安装hcordova
npm install -g hcordova

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

2. 安装指定版本

如需兼容特定 Cordova 或平台版本，可指定版本号安装：

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

3. 从 GitCode 安装开发版

hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-app-version.git --platform ohos

4. 卸载插件

# 全平台卸载
hcordova plugin remove cordova-plugin-app-version
# 指定OHOS 卸载
hcordova plugin remove cordova-plugin-app-version --platform ohos

快速上手

插件使用流程简单：等待 Cordova 环境就绪（deviceready 事件）→ 调用 API 获取信息 → 处理返回结果，以下为基础使用示例。

1. 基础示例：获取所有版本信息

// 等待 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);
     // Android 平台示例输出：
     // {
     //   appName: "MyApplication",    // 应用名称
     //   version: "3.2.1",            // 版本号（用户可见）
     //   build: "321",                // 构建号（内部版本）
     //   packageName: "com.example.myapp" // 应用包名
     // }
     // 在页面中展示版本信息
     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. 获取构建号（内部版本，如 Android "321"、iOS "156"）
 appVersion.getBuild((build) => {
   console.log("应用构建号：", build);
 }, (error) => {
   console.error("获取构建号失败：", error);
 });

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

3. TypeScript 使用示例

插件内置 TypeScript 类型定义，支持类型提示与语法校验：

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);
 });
}

API 文档

插件提供两类 API：批量获取所有信息（推荐）和单独获取指定信息（灵活），所有 API 均为异步调用，通过成功 / 失败回调返回结果。

1. 批量获取所有信息

一次性获取应用所有版本相关字段，返回对象包含通用字段与平台特有字段。

interface AppVersionInfo {
 appName: string;          // 应用名称（所有平台支持）
 version: string;          // 版本号（用户可见，如 "3.2.1"，所有平台支持）
 build: string;            // 构建号（内部版本，如 "321"，支持）
 packageName?: string;     // 应用包名
 bundleId?: string;        // 应用 Bundle Name
}

/**

* 批量获取所有版本信息
* @param successCallback 成功回调，参数为 AppVersionInfo 对象
* @param errorCallback 失败回调，参数为 Error 对象（包含 message 字段）
*/

getVersionInfo(
 successCallback: (info: AppVersionInfo) => void,
 errorCallback: (error: Error) => void
): void;

2. 单独获取指定信息

按需获取某一项信息，适合仅需部分数据的场景。

| API 方法 | 功能描述 | 返回值类型 | | ------------------------------------ | ----------------------------------- | ------ | | getAppName(success, error) | 获取应用名称 | string | | getVersion(success, error) | 获取版本号（用户可见，如 "3.2.1"） | string | | getBuild(success, error) | 获取构建号（内部版本，如 "321"） | string | | getPackageName(success, error) | Bundle Name | string |

示例：调用单独获取 API

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);
});

许可证

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

资源参考

1. OHOS：https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-app-version

2. Android、ios插件说明：https://www.npmjs.com/package/cordova-plugin-app-version