{"_id":"@cordova-ohos/cordova-plugin-app-version","_rev":"5-b324d10d18c558104d284f5ca31ffbbd","name":"@cordova-ohos/cordova-plugin-app-version","dist-tags":{"latest":"0.1.15"},"versions":{"0.1.14":{"name":"@cordova-ohos/cordova-plugin-app-version","version":"0.1.14","keywords":["cordova","app-version","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-app-version@0.1.14","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-app-version/issues"},"dist":{"shasum":"ee1bfc93e73c25ed90611e302bc03d27a85122f4","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-app-version/-/cordova-plugin-app-version-0.1.14.tgz","fileCount":10,"integrity":"sha512-35zLR0mnuTmgSaVliLI5xhS/ZttIlvWPX/NpM+D92ZjuzusMIoV3dFcnWu1eo2JVDMNWDAvLt9sj23Z3fvdybg==","signatures":[{"sig":"MEQCIBMo1PvTsSy/PGsLzzZcslvkEVAHpxP8d32c82gW6cMwAiBsyFHS4ZLAVoCsC035dfVL7NwX9eTUVQdp+NxEypowhQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37751},"cordova":{"id":"cordova-plugin-app-version","platforms":["ohos"]},"engines":{"cordovaDependencies":{"0.1.14":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"ef8cc07b958269348357694a39b2eea7d092da8b","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-app-version","type":"git"},"_npmVersion":"10.5.1","description":"Cordova App Version Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-app-version_0.1.14_1773927490380_0.4891394378111553","host":"s3://npm-registry-packages-npm-production"}},"0.1.15":{"name":"@cordova-ohos/cordova-plugin-app-version","version":"0.1.15","description":"Cordova App Version Plugin","cordova":{"id":"cordova-plugin-app-version","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-app-version"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-app-version/issues"},"keywords":["cordova","app-version","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"0.1.15":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-app-version@0.1.15","gitHead":"40262175eccec12ed7da2f4283e9e5953c2d2536","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-M+bZYTicncXvchsABWphkQNxqvZYCD6hKx+Ku3kiOJp9WJpkVYXshmn55y8NqD3FP8F6jbGEMDEies/1RMGeFg==","shasum":"96a9b7d7baaf6d1ca613c4485ab8fcaa0db9b26a","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-app-version/-/cordova-plugin-app-version-0.1.15.tgz","fileCount":11,"unpackedSize":61170,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDZSBFsQnfn7teFJuKy1eNtqMJapN9JtxDDLX9Q5GV7cgIhAJp61y8FPHYjkQcu4ej2v0i4hcHxgLjnNT3NGTBhDeTU"}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-app-version_0.1.15_1785145283789_0.3232752489828987"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T13:38:10.288Z","modified":"2026-07-27T09:41:24.144Z","0.1.14":"2026-03-19T13:38:10.534Z","0.1.15":"2026-07-27T09:41:23.918Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-app-version/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","app-version","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-app-version"},"description":"Cordova App Version Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-plugin-app-version</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-app-version@0.1.14](https://www.npmjs.com/package/cordova-plugin-app-version/v/0.1.14) 开发。本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-app-version](#cordova-plugin-app-version)\r\n  - [简介](#简介)\r\n  - [核心特性](#核心特性)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [安装插件](#安装插件)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载插件](#卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [常见问题](#常见问题)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：基础用法（批量获取所有版本信息）](#示例-1基础用法批量获取所有版本信息)\r\n    - [示例 2：单独获取指定版本信息](#示例-2单独获取指定版本信息)\r\n    - [示例 3：TypeScript 用法](#示例-3typescript-用法)\r\n    - [示例 4：OHOS 平台单独获取 Bundle Name](#示例-4ohos-平台单独获取-bundle-name)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心使用前提](#1-核心使用前提)\r\n    - [2. 核心使用流程](#2-核心使用流程)\r\n    - [3. OHOS 平台注意事项](#3-ohos-平台注意事项)\r\n    - [4. 调用方式选择](#4-调用方式选择)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\n一款轻量级 Cordova 插件，专注于跨平台获取应用版本相关信息。无需关注不同操作系统的底层实现差异，即可轻松获取应用名称、版本号、构建号、包名（Android）/Bundle Name 等核心数据，广泛应用于应用更新检测、用户反馈统计、日志上报等场景，助力开发者高效实现版本相关业务逻辑。本文档说明在 OHOS 系统中的应用。\r\n\r\n## 核心特性\r\n\r\n- **跨平台一致性**：一套代码适配 Android、iOS、OHOS 等多平台，无需编写平台专属逻辑\r\n\r\n- **支持属性**：支持获取应用名称、版本号（用户可见）、构建号（内部版本）、应用唯一标识（包名 / Bundle ID）\r\n\r\n- **轻量无依赖**：插件体积仅～40KB，无额外第三方依赖，不增加应用包体积负担\r\n\r\n- **易用性强**：API 设计简洁直观，3 行代码即可完成版本信息获取，降低开发学习成本\r\n\r\n- **实时同步**：获取的版本信息与应用配置实时同步，无需重启应用即可获取更新后的配置数据\r\n\r\n- **TypeScript 兼容**：内置类型定义文件，支持 TypeScript 项目开发，提供完整类型提示\r\n\r\n## 支持平台\r\n\r\n- Android 平台：适配 Android 系统，支持获取应用名称、版本号、构建号、包名等信息。\r\n\r\n- iOS 平台：适配 iOS 系统，支持获取应用名称、版本号、构建号、Bundle ID 等信息。\r\n\r\n- OHOS 平台：适配 OHOS 系统，支持获取应用名称、版本号、构建号、Bundle Name 等信息，贴合 OHOS 应用配置规范。\r\n\r\n- Browser 平台：适配浏览器环境，支持基础版本信息获取。\r\n\r\n## 下载安装\r\n\r\n通过 hcordova 命令化工具完成插件的安装、卸载，支持全平台或指定 OHOS 平台操作。\r\n\r\n### 安装插件\r\n\r\n```bash\r\n# 安装 hcordova\r\nnpm install -g hcordova\r\n\r\n# 从 npm 全平台安装\r\nhcordova plugin add cordova-plugin-app-version\r\n\r\n# 从 npm 指定 OHOS 平台安装\r\nhcordova plugin add cordova-plugin-app-version --platform ohos\r\n\r\n# 从 npm 指定版本安装\r\nhcordova plugin add cordova-plugin-app-version@1.0.0 --platform ohos\r\n\r\n# 从 GitCode 安装开发版\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-app-version.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-app-version.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-app-version）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-app-version --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n\r\n### 卸载插件\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-app-version\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-app-version --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 常见问题\r\n\r\n- 问题 1：OHOS 平台获取版本信息失败？\r\n解决：检查插件是否安装成功（通过 hcordova plugin list 确认），确保 OHOS 应用配置文件（module.json5）中已正确配置应用名称、版本号、Bundle Name，重新安装插件并重启项目。\r\n\r\n- 问题 2：getPackageName 方法返回 undefined？\r\n解决：OHOS 平台需确保 module.json5 中 \"bundleName\" 字段配置正确，插件通过该字段获取 Bundle Name，配置后重新构建项目即可。\r\n\r\n- 问题 3：deviceready 事件未触发，导致插件无法调用？\r\n解决：检查 Cordova 环境配置，确保 OHOS 平台添加正确，重新构建项目并重启应用，确保在 deviceready 事件后调用插件 API。\r\n\r\n## 使用示例\r\n\r\n以下示例均适配 OHOS 平台，涵盖基础使用、单独获取、TypeScript 用法，可直接复制到项目中使用（需确保 Cordova 环境就绪）。\r\n\r\n### 示例 1：基础用法（批量获取所有版本信息）\r\n\r\n一次性获取应用名称、版本号、构建号、Bundle Name 等所有信息，适合大多数场景：\r\n\r\n```javascript\r\n// 等待 Cordova 环境完全加载（必须在 deviceready 事件后调用插件）\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\nfunction onDeviceReady() {\r\n // 检查插件是否成功加载\r\n if (window.cordova && window.cordova.plugins && window.cordova.plugins.appVersion) {\r\n   const appVersion = window.cordova.plugins.appVersion;\r\n   // 一次性获取所有版本信息（推荐，减少回调次数）\r\n   appVersion.getVersionInfo((info) => {\r\n     console.log(\"应用版本信息：\", info);\r\n     // OHOS 平台示例输出：\r\n     // {\r\n     //   appName: \"MyApplication\",    // 应用名称\r\n     //   version: \"3.2.1\",            // 版本号（用户可见）\r\n     //   build: \"321\",                // 构建号（内部版本）\r\n     //   packageName: \"com.example.myapp\" // OHOS Bundle Name\r\n     // }\r\n     // 在页面中展示版本信息\r\n     document.getElementById(\"app-name\").textContent = info.appName;\r\n     document.getElementById(\"app-version\").textContent = `v${info.version} (build: ${info.build})`;\r\n     document.getElementById(\"app-id\").textContent = info.packageName || info.bundleId;\r\n   }, (error) => {\r\n     console.error(\"获取版本信息失败：\", error);\r\n     alert(`版本信息获取失败：${error.message}`);\r\n   });\r\n } else {\r\n   console.error(\"插件未加载，请检查安装是否正确\");\r\n }\r\n}\r\n```\r\n\r\n### 示例 2：单独获取指定版本信息\r\n\r\n按需获取某一项版本数据，灵活适配不同业务场景，示例包含所有单独获取 API 的用法：\r\n\r\n```javascript\r\nfunction getSingleInfoExample() {\r\n const appVersion = window.cordova.plugins.appVersion;\r\n // 1. 获取应用名称\r\n appVersion.getAppName((name) => {\r\n   console.log(\"应用名称：\", name); // 示例：\"MyApplication\"\r\n }, (error) => {\r\n   console.error(\"获取应用名称失败：\", error);\r\n });\r\n\r\n // 2. 获取版本号（用户可见，如 \"3.2.1\"）\r\n appVersion.getVersion((version) => {\r\n   console.log(\"应用版本号：\", version);\r\n }, (error) => {\r\n   console.error(\"获取版本号失败：\", error);\r\n });\r\n\r\n // 3. 获取构建号（内部版本，如 \"321\"）\r\n appVersion.getBuild((build) => {\r\n   console.log(\"应用构建号：\", build);\r\n }, (error) => {\r\n   console.error(\"获取构建号失败：\", error);\r\n });\r\n\r\n // 4. 获取应用唯一标识（OHOS Bundle Name）\r\n appVersion.getPackageName((bundleId) => {\r\n   console.log(\"OHOS Bundle Name：\", bundleId); // 示例：\"com.example.myapp\"\r\n }, (error) => {\r\n   console.error(\"获取 Bundle ID 失败：\", error);\r\n });\r\n}\r\n```\r\n\r\n### 示例 3：TypeScript 用法\r\n\r\n插件内置 TypeScript 类型定义，支持类型提示与语法校验，适配 TypeScript 开发的 OHOS Cordova 项目：\r\n\r\n```javascript\r\nimport type { AppVersionInfo, AppVersionPlugin } from \"cordova-plugin-app-version\";\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\nfunction onDeviceReady() {\r\n const appVersion: AppVersionPlugin = window.cordova?.plugins?.appVersion;\r\n if (!appVersion) {\r\n   throw new Error(\"cordova-plugin-app-version 插件未加载\");\r\n }\r\n\r\n // 获取所有版本信息（TypeScript 类型约束）\r\n appVersion.getVersionInfo((info: AppVersionInfo) => {\r\n   // 自动提示字段：appName、version、build、packageName、bundleId\r\n   console.log(`当前版本：v${info.version}，构建号：${info.build}`);\r\n   console.log(`应用标识：${info.packageName || info.bundleId}`);\r\n }, (error: Error) => {\r\n   console.error(\"获取版本信息失败：\", error.message);\r\n });\r\n}\r\n```\r\n\r\n### 示例 4：OHOS 平台单独获取 Bundle Name\r\n\r\n针对 OHOS 平台常用场景，单独获取应用 Bundle Name 的简化示例：\r\n\r\n```javascript\r\nconst appVersion = window.cordova.plugins.appVersion;\r\n\r\n// 获取 OHOS Bundle Name\r\nappVersion.getPackageName((bundleId) => {\r\n console.log(\"OHOS Bundle Name：\", bundleId); // 示例：\"com.example.myapp\"\r\n}, (error) => {\r\n console.error(\"获取 Bundle ID 失败：\", error.message);\r\n});\r\n```\r\n\r\n## 使用说明\r\n\r\n本插件使用流程简洁，核心需遵循“环境就绪→调用 API→处理结果”的逻辑，以下为详细使用说明，重点适配 OHOS 平台使用场景，可结合上方使用示例理解：\r\n\r\n### 1. 核心使用前提\r\n\r\n插件所有 API 均需在 Cordova 环境完全就绪后调用，即必须在 `deviceready` 事件触发后执行，否则会出现“插件未加载”错误，导致 API 调用失败（所有示例均已遵循此前提）。\r\n\r\n### 2. 核心使用流程\r\n\r\n1. 监听 `deviceready` 事件，确认 Cordova 环境加载完成；\r\n\r\n2. 检查插件是否成功加载（可选，建议添加，提升代码健壮性）；\r\n\r\n3. 调用对应 API 获取版本信息（批量获取或单独获取）；\r\n\r\n4. 在成功回调中处理返回的版本数据，失败回调中处理异常情况。\r\n\r\n### 3. OHOS 平台注意事项\r\n\r\n- OHOS 平台中，`getPackageName` 方法获取的是应用的 Bundle Name，该值来源于 OHOS 应用配置文件（module.json5）中的 `bundleName` 字段，需确保该字段配置正确。\r\n\r\n- 版本信息（应用名称、版本号、构建号）均同步于 OHOS 应用配置文件，若修改配置，需重新构建项目，插件才能获取到更新后的数据。\r\n\r\n- 插件无需申请任何系统权限，安装后即可直接调用所有 API，无需额外配置权限声明。\r\n\r\n- TypeScript 项目可直接使用插件内置的类型定义，无需额外安装类型文件，支持完整类型提示。\r\n\r\n### 4. 调用方式选择\r\n\r\n- 批量获取（`getVersionInfo`）：推荐用于需要同时获取多类版本信息的场景（如应用关于页、版本更新检测），减少回调次数，提升代码简洁度（对应示例 1）。\r\n\r\n- 单独获取（`getAppName`、`getVersion` 等）：适合仅需某一项版本数据的场景（如仅展示版本号），灵活适配不同业务需求（对应示例 2、示例 4）。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-app-version/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       ├── cpp/                  # C++ 原生代码\r\n│       │   └── AppVersion/       # 应用版本模块\r\n│       │       ├── AppVersion.cpp  # 获取应用版本信息的 C++ 实现\r\n│       │       └── AppVersion.h    # 获取应用版本信息的头文件\r\n│       ├── ets/                  # ArkTS 代码（OpenHarmony API）\r\n│       │   └── components/       # 组件目录\r\n│       │       └── PluginAction/ # 插件动作组件\r\n│       │           └── GetAppInfo.ets  # 获取应用信息的实现\r\n│── www/                          # Web 资源目录\r\n│   ├── AppVersionPlugin.js       # JavaScript 接口（Cordova 桥接层）\r\n│   └── LICENSE                   # Web 资源的许可证文件\r\n├── .gitignore                    # Git 忽略文件配置\r\n├── LICENSE                       # 项目开源许可证\r\n├── OAT.xml                       # OpenHarmony 审核配置文件\r\n├── package.json                  # Node.js 包配置\r\n├── plugin.xml                    # Cordova 插件描述文件（核心配置）\r\n└── README.md                     # 项目说明文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-app-version/issues)，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-app-version/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- OHOS 插件仓库：[CPF-Cordova/cordova-plugin-app-version](https://gitcode.com/CPF-Cordova/cordova-plugin-app-version)\r\n\r\n- Android、iOS 插件说明：[cordova-plugin-app-version 官方指南](https://www.npmjs.com/package/cordova-plugin-app-version)\r\n\r\n- Cordova 官方文档：[Cordova Documentation](https://cordova.apache.org/docs/en/10.x/)\r\n\r\n- OHOS 开发文档：[OpenHarmony 官方文档](https://docs.openharmony.cn/)\r\n","readmeFilename":"README.md"}