{"_id":"@cordova-ohos/cordova-plugin-appversion","_rev":"5-c5c1933c8e5776d74e19acb8a4cfea34","name":"@cordova-ohos/cordova-plugin-appversion","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@cordova-ohos/cordova-plugin-appversion","version":"1.0.0","keywords":["cordova","appversion","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-appversion@1.0.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-appversion/issues"},"dist":{"shasum":"5137e97f19feb1a659989b318ee870d4bffdc84c","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-appversion/-/cordova-plugin-appversion-1.0.0.tgz","fileCount":8,"integrity":"sha512-C1+UpskSR8tA0uwPb4H4/bzpXfu93240QBcNLpUulpm3DfrMNMzpyjdbZwyKe3SFv/ndThyHC2ybSykna/go8g==","signatures":[{"sig":"MEUCIBinfMsUCdC5uV18pZ48/1Gtqadxcd3uUb69ycBaZlJdAiEA+l3QCdeqGVfXmnvAR2qHeKFHSKHcrqsgmjuOuuOCNWI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28967},"cordova":{"id":"cordova-plugin-appversion","platforms":["ohos"]},"engines":{"cordovaDependencies":{"1.0.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"96aaeecc759083787e5662d73c21a83fe14f1258","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-appversion","type":"git"},"_npmVersion":"10.5.1","description":"Cordova appversion Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-appversion_1.0.0_1773927737517_0.8019535219545941","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cordova-ohos/cordova-plugin-appversion","version":"1.0.1","description":"Cordova appversion Plugin","cordova":{"id":"cordova-plugin-appversion","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-appversion"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-appversion/issues"},"keywords":["cordova","appversion","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"1.0.1":{"@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-appversion@1.0.1","gitHead":"4cabf9cae46d106ff01d1e7fb34dbfae3d6cbaae","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-WBKuK9PLVHzvZiPEey/u68iEk77YMxNBIQ5/P860LbKsGm2UeqPL6dtChnh7RiSkEkkew+ZJAnwn05p2fESCXA==","shasum":"c71ab5afcb5fb8af346a873e0cc48b58b346a2ac","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-appversion/-/cordova-plugin-appversion-1.0.1.tgz","fileCount":9,"unpackedSize":57579,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD/yY2tvM9ddoY/gCHbIBJ3FsM2pCuy4Ixpj/JUDKFBoQIgF84sU5sPmlswnkFhMfEI/Ox7GCGHrzawaC8WE77VH3U="}]},"_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-appversion_1.0.1_1785144980635_0.9817269688149834"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T13:42:17.448Z","modified":"2026-07-27T09:36:21.059Z","1.0.0":"2026-03-19T13:42:17.653Z","1.0.1":"2026-07-27T09:36:20.882Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-appversion/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","appversion","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-appversion"},"description":"Cordova appversion 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-appversion</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-appversion@1.0.0](https://www.npmjs.com/package/cordova-plugin-appversion/v/1.0.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-appversion](#cordova-plugin-appversion)\r\n  - [简介](#简介)\r\n  - [核心特性](#核心特性)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [1. 基础安装（推荐）](#1-基础安装推荐)\r\n    - [2. 安装指定版本](#2-安装指定版本)\r\n    - [3. 从 GitCode 安装（开发版本）](#3-从-gitcode-安装开发版本)\r\n    - [4. 离线安装（本地包）](#4-离线安装本地包)\r\n    - [5. 安装后验证](#5-安装后验证)\r\n    - [6. 卸载插件](#6-卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：快速获取版本信息（基础用法）](#示例-1快速获取版本信息基础用法)\r\n    - [示例 2：获取所有版本信息](#示例-2获取所有版本信息)\r\n    - [示例 3：TypeScript 用法](#示例-3typescript-用法)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心使用前提](#1-核心使用前提)\r\n    - [2. 核心 API 说明](#2-核心-api-说明)\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\r\n轻量级 Cordova 插件，专注于跨平台获取应用版本信息，支持 Android、iOS、OHOS 等多平台，无需关注底层系统差异。可快速获取应用名称、版本号、构建号、包名（Android）/Bundle ID（iOS）等核心信息，广泛用于应用更新检测、日志上报、用户反馈等场景，帮助开发者实现版本相关的业务逻辑。本文档主要说明在 OHOS 系统中的应用。\r\n\r\n## 核心特性\r\n\r\n- **跨平台统一接口**：一套代码适配 Android、iOS、OHOS 等主流平台，无需编写平台差异化代码，保持 API 调用统一，适配各平台应用配置规范。\r\n\r\n- **版本信息获取**：支持获取应用名称、版本号（Version Name）、构建号（Build Number）、包名 / Bundle ID 等核心信息，覆盖开发者对版本信息的各类需求。\r\n\r\n- **轻量级设计**：插件体积小（仅～50KB），无额外第三方依赖，不增加应用包体积负担，不影响 OHOS 应用运行性能。\r\n\r\n- **快速集成**：API 简洁直观，3 行代码即可实现版本信息获取，学习成本低，便于开发者快速集成到项目中。\r\n\r\n- **实时信息同步**：获取的版本信息与应用配置实时同步，无需重启应用即可获取更新后的配置数据，适配 OHOS 应用配置更新场景。\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## 下载安装\r\n\r\n通过 hcordova 命令化工具完成插件的安装、卸载，支持全平台或指定 OHOS 平台操作，安装过程自动完成平台配置，快速集成到 Cordova 项目。\r\n\r\n### 1. 基础安装（推荐）\r\n\r\n通过 npm 安装最新稳定版，自动集成到 Cordova 项目，支持全平台或指定 OHOS 平台安装：\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装\r\nhcordova plugin add cordova-plugin-appversion\r\n\r\n# 指定 OHOS 平台安装\r\nhcordova plugin add cordova-plugin-appversion --platform ohos\r\n```\r\n\r\n### 2. 安装指定版本\r\n\r\n如需兼容特定 Cordova 或平台版本，可指定版本号安装（仅 OHOS 平台）：\r\n\r\n```bash\r\n# 安装 1.0.0 版本（指定 OHOS 平台）\r\nhcordova plugin add cordova-plugin-appversion@1.0.0 --platform ohos\r\n```\r\n\r\n### 3. 从 GitCode 安装（开发版本）\r\n\r\n如需测试最新功能或问题修复，可从 GitCode 仓库安装开发分支（仅 OHOS 平台）：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-appversion.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-appversion.git@develop --platform ohos\r\n```\r\n\r\n### 4. 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-appversion）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-appversion  --platform ohos\r\n```\r\n\r\n### 5. 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n### 6. 卸载插件\r\n\r\n如需移除插件，执行以下命令，支持全平台卸载或仅卸载 OHOS 平台插件：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-appversion\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-appversion --platform ohos\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以下示例均适配 OHOS 平台，涵盖基础用法、快速获取、TypeScript 用法，可直接复制到项目中使用（需确保 Cordova 环境就绪）。\r\n\r\n### 示例 1：快速获取版本信息（基础用法）\r\n\r\n通过 AppVersion 对象直接获取版本号和构建号，简洁高效，适合快速获取核心信息：\r\n\r\n```javascript\r\n// 等待 Cordova 环境完全加载（必须在 deviceready 事件后调用插件）\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\n\r\nfunction onDeviceReady() {\r\n  // 检查插件是否成功加载\r\n  if (window.cordova && window.cordova.plugins && window.AppVersion) {\r\n    // 通过 AppVersion 对象获取 version 和 build（OHOS 平台适配）\r\n    function getAppVersion() {\r\n      console.log(\"version:\" + AppVersion.version + \",code:\" + AppVersion.build);\r\n    }\r\n    // 调用方法获取并打印版本信息\r\n    getAppVersion();\r\n  } else {\r\n    console.error(\"插件未加载，请检查安装是否正确\");\r\n  }\r\n}\r\n```\r\n\r\n### 示例 2：获取所有版本信息\r\n\r\n获取应用名称、版本号、构建号、Bundle Name 等所有核心信息，适合应用关于页、版本更新检测等场景：\r\n\r\n```javascript\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\n\r\nfunction onDeviceReady() {\r\n  if (window.AppVersion) {\r\n    // 获取应用名称\r\n    const appName = AppVersion.appName;\r\n    // 获取版本号（Version Name）\r\n    const version = AppVersion.version;\r\n    // 获取构建号（Build Number）\r\n    const build = AppVersion.build;\r\n    // 获取 OHOS Bundle Name（对应 Android 包名、iOS Bundle ID）\r\n    const bundleName = AppVersion.packageName;\r\n\r\n    // 打印所有版本信息\r\n    console.log(\"应用名称：\", appName);\r\n    console.log(\"版本号：\", version);\r\n    console.log(\"构建号：\", build);\r\n    console.log(\"OHOS Bundle Name：\", bundleName);\r\n\r\n    // 在页面中展示版本信息\r\n    document.getElementById(\"app-version\").textContent = `v${version} (build: ${build})`;\r\n  } else {\r\n    console.error(\"AppVersion 插件未加载\");\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 { AppVersion } from \"cordova-plugin-appversion\";\r\n\r\ndocument.addEventListener(\"deviceready\", onDeviceReady, false);\r\n\r\nfunction onDeviceReady() {\r\n  const appVersion: AppVersion = window.AppVersion;\r\n  if (!appVersion) {\r\n    throw new Error(\"cordova-plugin-appversion 插件未加载\");\r\n  }\r\n\r\n  // 类型提示下获取版本信息\r\n  console.log(`版本号：${appVersion.version}，构建号：${appVersion.build}`);\r\n  console.log(`应用名称：${appVersion.appName}，Bundle Name：${appVersion.packageName}`);\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` 事件触发后执行，否则会出现“插件未加载”“接口未定义”等错误（所有示例均已遵循此前提）。\r\n\r\n### 2. 核心 API 说明\r\n\r\n插件在全局对象 `window.AppVersion` 下暴露核心属性，无需复杂调用，直接获取对应版本信息，适配 OHOS 平台的属性如下：\r\n\r\n| 属性名 | 类型 | 说明（OHOS 平台） |\r\n|---|---|---|\r\n| appName | string | 应用名称，同步于 OHOS 应用配置文件（module.json5）中的相关配置。 |\r\n| version | string | 版本号（Version Name），用户可见，同步于 OHOS 应用配置文件中的版本配置。 |\r\n| build | string | 构建号（Build Number），内部版本号，同步于 OHOS 应用配置文件中的构建配置。 |\r\n| packageName | string | OHOS 应用的 Bundle Name，来源于 OHOS 应用配置文件（module.json5）中的 bundleName 字段。 |\r\n\r\n### 3. OHOS 平台注意事项\r\n\r\n- OHOS 平台中，所有版本信息（appName、version、build、packageName）均同步于应用配置文件（module.json5），若修改配置，需重新构建项目，插件才能获取到更新后的数据。\r\n\r\n- 插件无需申请任何系统权限，安装后即可直接调用所有属性，无需额外配置权限声明，简化集成流程。\r\n\r\n- TypeScript 项目可直接使用插件内置的类型定义，无需额外安装类型文件，支持完整类型提示，提升开发效率。\r\n\r\n- 若获取不到版本信息，可检查 OHOS 应用配置文件（module.json5）中是否正确配置了应用名称、版本号、bundleName 等字段，配置后重新构建项目即可。\r\n\r\n### 4. 调用方式选择\r\n\r\n- 快速调用：适合仅需获取版本号、构建号等核心信息的场景，直接通过 AppVersion 对象获取，代码简洁（对应示例 1）。\r\n\r\n- 全参数调用：适合需要获取所有版本信息的场景（如应用关于页），一次性获取所有属性，提升代码简洁度（对应示例 2）。\r\n\r\n- TypeScript 调用：适合 TypeScript 开发的项目，利用内置类型定义，实现类型校验与提示（对应示例 3）。\r\n\r\n## 常见问题\r\n\r\n- 问题 1：OHOS 平台获取不到版本信息，提示“AppVersion is undefined”？\r\n解决：检查插件是否安装成功（通过 hcordova plugin list 确认），确保在 deviceready 事件后调用插件，重新安装插件并重启项目。\r\n\r\n- 问题 2：获取的版本信息与 OHOS 应用配置文件中的配置不一致？\r\n解决：版本信息同步于应用配置文件，修改配置后需重新构建项目，插件才能获取到更新后的数据。\r\n\r\n- 问题 3：TypeScript 项目中提示“找不到 AppVersion 类型定义”？\r\n解决：插件内置类型定义文件，无需额外安装，检查插件安装是否完整，重新安装插件即可。\r\n\r\n- 问题 4：OHOS 平台获取 packageName 返回 undefined？\r\n解决：确保 OHOS 应用配置文件（module.json5）中 bundleName 字段配置正确，重新构建项目后重试。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-appversion/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       └── cpp/                  # C++ 原生代码\r\n│           └── AppVersion/       # 应用版本模块\r\n│               ├── RareloopAppVersion.cpp  # 应用版本信息的 C++ 实现\r\n│               └── RareloopAppVersion.h    # 应用版本信息的头文件\r\n├── www/                          # Web 资源目录\r\n│   └── app-version.js            # JavaScript 接口（Cordova 桥接层）\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-appversion/issues)，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-appversion/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- OHOS 插件仓库：[https://gitcode.com/CPF-Cordova/cordova-plugin-appversion](https://gitcode.com/CPF-Cordova/cordova-plugin-appversion)\r\n\r\n- Android、iOS 插件说明：[https://www.npmjs.com/package/cordova-plugin-appversion](https://www.npmjs.com/package/cordova-plugin-appversion)\r\n\r\n- Cordova 官方文档：[Cordova Documentation](https://cordova.apache.org/)\r\n\r\n- OHOS 开发文档：[OpenHarmony 官方文档](https://docs.openharmony.cn/)\r\n","readmeFilename":"README.md"}