@hxa-rn/react-native-version-check

v3.5.1

Published

20 days ago

为 React Native 应用提供版本检查能力：通过原生模块读取当前应用版本信息，联网查询应用商店最新版本，基于 semver 判断是否需要更新并生成应用商店链接

Downloads

247

0High
0Medium
0Low

react-native harmony harmonyos

react-native-version-check

本项目基于 react-native-version-check 开发。如果在使用过程中有任何问题，欢迎在 AtomGit 提交 Issue，会及时跟进。

项目介绍

react-native-version-check 为 React Native 应用提供版本检查能力：通过原生模块读取当前应用的版本号、构建号、包名与设备国家码，联网查询应用商店最新版本，基于 semver 判断是否需要更新，并生成应用商店直达链接。

本鸿蒙适配包（@hxa-rn/react-native-version-check 3.5.1）将原库旧架构原生模块 RNVersionCheck 迁移为 TurboModule，鸿蒙端经 @kit.AbilityKit 的 bundleManager.getBundleInfoForSelfSync() 与 @kit.LocalizationKit 的 i18n.System.getSystemRegion() 读取应用与系统信息；JS 业务层（Provider 查询、semver 比较、商店链接生成）整体复用，并为鸿蒙平台补充 appGallery 数据源与 Platform.select 的 harmony 分支。

本库为含原生模块的适配包，支持 Autolinking。

集成指南

安装

npm install @hxa-rn/react-native-version-check

依赖要求

react-native: >=0.72（peerDependency）
Node.js: >=18（engines）

业务代码请使用原库名导入（由 harmony.alias 自动映射）：

import VersionCheck from 'react-native-version-check';

Autolinking

本模块支持 Autolinking。工程已接入 RN for OpenHarmony Autolinking 时，安装依赖后即可使用，无需手动注册。

package.json 中的鸿蒙配置如下（供参考）：

{
  "harmony": {
    "alias": "react-native-version-check",
    "autolinking": {
      "cmakeLibraryTargetName": "version_check",
      "ohPackageName": "@hxa-rn/react-native-version-check",
      "etsPackageClassName": "VersionCheckPackage",
      "cppPackageClassName": "VersionCheckPackage"
    }
  }
}

手动 Link（Autolinking 未启用时）

本模块需同时在 C++ 侧与 ETS 侧注册 Package。

1. 引入 HAR 依赖

在 entry/oh-package.json5 中添加：

{
  "dependencies": {
    "@hxa-rn/react-native-version-check": "file:../../node_modules/@hxa-rn/react-native-version-check/harmony/version_check.har"
  }
}

执行 ohpm install。

2. 配置 CMakeLists

在 entry/src/main/cpp/CMakeLists.txt 中添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@hxa-rn/react-native-version-check/src/main/cpp" ./version_check)

target_link_libraries(rnoh_app PUBLIC version_check)

3. 注册 Package（C++ 侧）

在 entry/src/main/cpp/PackageProvider.cpp 中添加：

#include "VersionCheckPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
  return {
    std::make_shared<VersionCheckPackage>(ctx),
  };
}

4. 注册 Package（ETS 侧）

在 entry/src/main/ets/RNPackagesFactory.ets 中添加：

import VersionCheckPackage from '@hxa-rn/react-native-version-check';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new VersionCheckPackage(ctx),
  ];
}

使用说明

读取当前应用版本信息

import VersionCheck from 'react-native-version-check';

VersionCheck.getCountry()
  .then(country => console.log('国家码:', country))
  .catch(err => console.warn('获取国家码失败:', err));
console.log('包名:', VersionCheck.getPackageName());
console.log('构建号:', VersionCheck.getCurrentBuildNumber());
console.log('版本号:', VersionCheck.getCurrentVersion());

getCountry() 失败时 Promise.reject；其余三个同步接口读取失败分别回退 ''、0、'0'。

查询商店最新版本

鸿蒙平台默认数据源为 appGallery（华为应用市场）。getLatestVersion 没有 latestVersion 参数；要跳过商店页面解析，请传入 provider 函数或 { getVersion } 对象。ignoreErrors 默认 true，provider 查询抛错时返回 undefined 并 console.warn；无法识别的 provider 字符串会 Promise.reject。

// 默认走 appGallery Provider
VersionCheck.getLatestVersion()
  .then(latestVersion => {
    console.log('最新版本:', latestVersion); // 失败时为 undefined
  })
  .catch(err => console.warn('查询最新版本失败:', err));

// 用 provider 函数直接返回指定版本，不发起网络请求
VersionCheck.getLatestVersion({
  provider: async () => '2.0.0',
})
  .then(v => {
    console.log(v); // '2.0.0'
  })
  .catch(err => console.warn(err));

// 自定义 provider 对象（推荐：AppGallery 无公开版本查询 API 时）
VersionCheck.getLatestVersion({
  provider: {
    getVersion: async () => ({
      version: '3.2.1',
      storeUrl: 'https://appgallery.huawei.com/app/com.example.app',
    }),
  },
})
  .then(v => console.log(v))
  .catch(err => console.warn(err));

判断是否需要更新

显式传入 currentVersion 与 latestVersion 时只做 semver 比较，不查商店；此时 storeUrl 通常为空字符串。ignoreErrors 默认 true，异常时返回 undefined。

VersionCheck.needUpdate({
  currentVersion: '1.0.0',
  latestVersion: '2.0.0',
})
  .then(res => {
    if (!res) {
      console.warn('needUpdate 失败，已按 ignoreErrors 降级为 undefined');
      return;
    }
    console.log('需要更新:', res.isNeeded);       // true
    console.log('当前版本:', res.currentVersion); // '1.0.0'
    console.log('最新版本:', res.latestVersion);   // '2.0.0'
    console.log('商店链接:', res.storeUrl);
  })
  .catch(err => console.warn(err));

生成应用商店链接

鸿蒙平台 getStoreUrl() 默认返回华为应用市场链接。未传 ignoreErrors: true 时失败会 reject。

VersionCheck.getStoreUrl({ packageName: 'com.example.app' })
  .then(url => console.log(url))
  .catch(err => console.warn('生成商店链接失败:', err));
// https://appgallery.huawei.com/app/com.example.app

VersionCheck.getAppStoreUrl({ appID: '123456789' })
  .then(url => console.log(url))
  .catch(err => console.warn(err));
VersionCheck.getPlayStoreUrl({ packageName: 'com.example.app' })
  .then(url => console.log(url))
  .catch(err => console.warn(err));

接口文档

默认导出对象 VersionCheck 包含以下公开 API（定义于 src/builder.js）：

| API | 签名 | 功能 | 参数 | 返回值 / 空值语义 | |-----|------|------|------|-------------------| | getCountry() | () => Promise<string> | 获取设备国家/地区码 | 无 | 成功返回字符串（如 CN）；失败时 Promise.reject | | getPackageName() | () => string | 获取当前应用包名 | 无 | 同步返回 bundleName；读取失败回退空字符串 | | getCurrentBuildNumber() | () => number | 获取当前应用构建号 | 无 | 同步返回 versionCode（number）；失败回退 0 | | getCurrentVersion() | () => string | 获取当前应用版本号 | 无 | 同步返回 versionName；失败回退 '0' | | getLatestVersion(option?) | (option?) => Promise<string> | 查询应用商店最新版本 | forceUpdate?、provider?（'appStore' | 'playStore' | 'appGallery' | 函数 | { getVersion } 对象）、fetchOptions?、ignoreErrors?（默认 true）。无 latestVersion 字段，跳过网络请用 provider | 成功返回版本号字符串；ignoreErrors: true（默认）时 provider 抛错返回 undefined 并 console.warn；无法识别的 provider 字符串会 Promise.reject | | needUpdate(option?) | (option?) => Promise<NeedUpdateResult> | 基于 semver 比较判断是否需要更新 | currentVersion?、latestVersion?、depth?（默认 Infinity）、ignoreErrors?（默认 true），并继承 getLatestVersion 的 provider 等选项 | { isNeeded, storeUrl, currentVersion, latestVersion }；ignoreErrors: true 时异常降级为 undefined | | getStoreUrl(option?) | (option?) => Promise<string> | 按平台生成商店链接 | packageName?、appID?、country?、ignoreErrors? | 鸿蒙返回 AppGallery 链接；ignoreErrors: true 时异常返回 undefined | | getAppStoreUrl(option) | (option) => Promise<string> | 生成苹果 App Store 链接 | appID（必填）、country?、ignoreErrors? | itms-apps://apps.apple.com/... 格式链接 | | getPlayStoreUrl(option?) | (option?) => Promise<string> | 生成 Google Play 链接 | packageName?、ignoreErrors? | https://play.google.com/store/apps/details?id=... |

NeedUpdateResult 结构：

type NeedUpdateResult = {
  isNeeded: boolean;
  storeUrl: string;
  currentVersion: string;
  latestVersion: string;
};

内置 Provider（src/providers/）：appStore、playStore、appGallery（鸿蒙新增）。鸿蒙平台 getLatestVersion / needUpdate 默认 provider 为 appGallery。

原生 TurboModule（RNVersionCheck，Spec 见 src/specs/v1/NativeRNVersionCheck.ts）：除上述 JS 封装外，模块还通过 getConstants() 暴露 { country, packageName, currentVersion, currentBuildNumber } 四个常量；当前 JS 层 RNVersionInfo.js 经 TurboModuleRegistry.get('RNVersionCheck') 调用 getter 方法，对外语义与上表一致。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18（运行 Example 建议 >= 20，见 example/package.json） | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 13+（example/harmony 的 compatibleSdkVersion 为 5.0.1(13)） |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-version-check.git
cd react-native-version-check
git checkout main

2. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-version-check@^3.5.1，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

4. 安装鸿蒙依赖

cd harmony
ohpm install

5. 用 DevEco Studio 打开鸿蒙工程

打开 DevEco Studio
选择 example/harmony 目录
首次构建请在 File → Project Structure → Signing Configs 勾选 Automatically generate signature，Apply 后 Sync
等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 已预置 Autolinking Package 注册、Metro alias 与 HAR 依赖，无需手动 Link。编 HAP 前必须先执行 npm run dev。

约束与限制

| 项 | 说明 | |----|------| | React Native / RNOH | peerDependencies 要求 react-native >= 0.72；Demo 使用 [email protected]、@react-native-oh/[email protected]（RNOH 0.72） | | HarmonyOS SDK | Demo compatibleSdkVersion 为 5.0.1(13)；原生读取使用 bundleManager.getBundleInfoForSelfSync（API 10+） | | Node.js | 库根 >=18；运行 Example 建议 >=20 | | 权限 | HAR requestPermissions 为空，无额外系统权限；仅读取应用自身 Bundle 信息与系统区域 | | 架构 | 含原生 TurboModule RNVersionCheck 与 HAR harmony/version_check，支持 Autolinking | | 默认商店路径 | 鸿蒙 getStoreUrl() 返回 AppGallery 链接；getLatestVersion / needUpdate 默认 provider 为 appGallery | | AppGallery 查询 | 华为应用市场无公开按包名查版本 API，页面解析为 best-effort；失败时默认 ignoreErrors: true 返回 undefined。建议业务传入自定义 provider | | 类型差异 | getCurrentBuildNumber() 鸿蒙与 Android 返回 number；iOS 原库为 string，不属鸿蒙适配范围 | | 范围外 | 原库 react-native-version-check-expo 未纳入；内置 appStore / playStore 在鸿蒙为 best-effort，可用 provider 覆盖 |

开源 license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

如在集成或使用过程中遇到问题，可通过以下渠道反馈：

AtomGit Issue（推荐）
GitCode 仓库：https://gitcode.com/hxa-rn/react-native-version-check
GitCode Issue：https://gitcode.com/hxa-rn/react-native-version-check/issues