react-native-rate

本项目基于 KjellConnelly/react-native-rate 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

react-native-rate 是一个 React Native 评分引导库的 HarmonyOS 适配版本，通过统一 API 发起应用内评论、应用市场详情页或外部链接跳转。

主要能力包括：

• 通过 Rate.rate(options, callback) 按配置发起评分引导，并通过回调返回是否成功发起及失败原因。
• 在设备能力可用且配置满足条件时优先调用 HarmonyOS 应用内评论弹窗。
• 通过 AppGalleryKit 打开应用市场详情页，目标 bundleName 按 HarmonyBundleName、GooglePackageName、宿主应用 bundleName 依次回退。
• 按配置打开自定义链接或兜底链接；AndroidMarket.Amazon 在鸿蒙侧映射为华为应用市场详情页。
• 通过 Rate.openURL(url, callback) 直接打开指定链接。
• 通过 Rate.filterOptions(options) 补齐默认配置。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-rate

本库将 react-native（>= 0.72）声明为 peer 依赖，请确保宿主工程已安装对应版本，并已完成 React Native for OpenHarmony 基础接入。

Autolinking

安装依赖后由 React Native for OpenHarmony 宿主工程自动接入，无需手动注册。

导入

import Rate, { AndroidMarket } from '@hxa-rn/react-native-rate';
import type { RateOptions, RateCallback } from '@hxa-rn/react-native-rate';

使用说明

基础用法

import React from 'react';
import { Button, View } from 'react-native';
import Rate, { AndroidMarket } from '@hxa-rn/react-native-rate';
import type { RateOptions } from '@hxa-rn/react-native-rate';

const options: RateOptions = {
  GooglePackageName: 'com.example.myapp',
  preferredAndroidMarket: AndroidMarket.Google,
  preferInApp: true,
  openAppStoreIfInAppFails: true,
  fallbackPlatformURL: 'https://appgallery.huawei.com/',
};

export default function App(): React.JSX.Element {
  const handleRate = (): void => {
    Rate.rate(options, (success, error) => {
      if (success) {
        console.log('评分引导已发起');
      } else {
        console.log('评分引导失败：', error);
      }
    });
  };

  return (
    <View>
      <Button title="去评分" onPress={handleRate} />
    </View>
  );
}

• 应用内评论仅在 preferInApp 为 true 且 preferredAndroidMarket 为 AndroidMarket.Google 时尝试；应用内评论失败后是否继续打开应用详情页由 openAppStoreIfInAppFails 决定。
• 应用详情页的 bundleName 优先取 HarmonyBundleName，未配置时在 AndroidMarket.Google 下取 GooglePackageName，仍未配置时回退为宿主应用的 bundleName。
• 回调统一为 (success: boolean, error?: string)，失败原因通过 error 返回。
• AppleAppID、AmazonPackageName 和 inAppDelay 仅为上游 API 兼容保留，HarmonyOS 侧不消费。
• 示例工程通过常量声明宿主应用的 bundleName，需与 example/harmony/AppScope/app.json5 保持一致。

打开自定义链接

import Rate from '@hxa-rn/react-native-rate';

Rate.openURL('https://appgallery.huawei.com/app/detail?id=C27162', (success, error) => {
  if (success) {
    console.log('链接已打开');
  } else {
    console.log('链接打开失败：', error);
  }
});

• HarmonyOS 侧通过原生 context.openLink(...) 打开链接，失败时把原生异常信息透传给回调。
• Rate.openURL 在 HarmonyOS 侧固定以非 App Linking 模式调用原生 openURL；需要开启 appLinkingOnly 时可通过 Rate.rate 的链接配置使用。
• 传入空链接或链接无法打开时，回调返回失败原因。

接口文档

以下 API 依据 src/index.ts 的导出及 src/specs/v1/NativeRNRate.ts 的 TurboModule 定义整理。

Rate

评分引导服务类，通过默认导出提供。

Rate.rate

static rate(inputOptions: RateOptions, callback?: RateCallback): void

按配置发起评分引导。HarmonyOS 侧的处理顺序如下：

1. 当 preferInApp 为 true 且 preferredAndroidMarket 为 AndroidMarket.Google 时，优先尝试应用内评论；失败且 openAppStoreIfInAppFails 为 false 时直接返回该结果。
2. preferredAndroidMarket 为 AndroidMarket.Amazon 时，依次尝试市场链接（HarmonyLink）、华为应用市场详情页、fallbackPlatformURL。
3. preferredAndroidMarket 为 AndroidMarket.Google 时，依次尝试应用市场详情页、HarmonyLink 与 fallbackPlatformURL。
4. 其余情况按优先级尝试 HarmonyLink、OtherAndroidURL（仅 AndroidMarket.Other）和 fallbackPlatformURL。
5. 通过回调返回动作是否成功发起。

Rate.openURL

static openURL(url: string, callback?: RateCallback): void

打开指定链接。HarmonyOS 侧通过原生 context.openLink(...) 发起跳转，并以非 App Linking 模式调用。

Rate.filterOptions

static filterOptions(inputOptions?: RateOptions): Required<RateOptions>

将传入配置与默认配置合并，返回全部字段必填的完整配置对象。

Rate.toHarmonyOptions

static toHarmonyOptions(options: Required<RateOptions>): {
  appleAppID: string;
  googlePackageName: string;
  amazonPackageName: string;
  otherAndroidURL: string;
  preferredAndroidMarket: AndroidMarket;
  preferInApp: boolean;
  openAppStoreIfInAppFails: boolean;
  inAppDelay: number;
  fallbackPlatformURL: string;
  harmonyBundleName: string;
  harmonyLink: string;
  appLinkingOnly: boolean;
}

把补齐默认值后的配置转换为 HarmonyOS 原生侧使用的小写字段对象，供原生 rate 调用，不修改传入的配置对象。

AndroidMarket

市场类型常量，通过命名导出提供。

常量	值	说明
AndroidMarket.Google	1	Google 市场主链路；HarmonyOS 侧用于应用内评论和应用详情页尝试。
AndroidMarket.Amazon	2	Amazon 市场兼容配置；鸿蒙侧不存在 Amazon 应用市场，链路映射为华为应用市场详情页，不生成 amzn://apps/android?p=... 链接。
AndroidMarket.Other	3	其他 Android 市场；使用 OtherAndroidURL 或其他兜底链接。

RateOptions

评分引导配置类型。

属性	类型	默认值	说明
AppleAppID	string	''	上游 iOS 配置兼容字段，HarmonyOS 侧不消费。
GooglePackageName	string	''	Google 目标应用包名；preferredAndroidMarket 为 AndroidMarket.Google 时作为应用详情页的 bundleName 候选。
AmazonPackageName	string	''	Amazon 目标应用包名；上游配置兼容字段，HarmonyOS 侧不消费。
OtherAndroidURL	string	''	其他 Android 市场链接；仅 preferredAndroidMarket 为 AndroidMarket.Other 时参与跳转。
preferredAndroidMarket	AndroidMarket	AndroidMarket.Google	选择评分或市场跳转主链路。
preferInApp	boolean	false	是否优先尝试应用内评论。
openAppStoreIfInAppFails	boolean	true	应用内评论失败后是否继续尝试应用详情页或链接兜底。
inAppDelay	number	3.0	上游配置兼容字段，HarmonyOS 侧不消费。
fallbackPlatformURL	string	''	没有可用特化链路时使用的最终兜底链接。
HarmonyBundleName	string	''	HarmonyOS 目标应用 bundleName；用于应用详情页，也是 AndroidMarket.Amazon 链路在鸿蒙侧打开华为应用市场详情页的目标（未配置时按 GooglePackageName、宿主应用 bundleName 回退）。
HarmonyLink	string	''	HarmonyOS 自定义跳转链接，在链接候选中优先尝试。
appLinkingOnly	boolean	false	链接跳转时是否仅允许 App Linking。

RateCallback

回调类型，通过命名导出提供。

type RateCallback = (success: boolean, error?: string) => void;

rate 与 openURL 共用该签名；失败原因通过 error 返回，原生侧 Promise 拒绝时取 error.message。

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>=20
React Native for OpenHarmony	0.72.139
HarmonyOS SDK	API 21+

运行步骤

1. 获取开发分支源码

git clone -b react-native-rate_dev https://gitcode.com/hxa-rn/react-native-rate.git

2. 进入仓库根目录

cd react-native-rate

3. 安装根目录依赖

npm install

4. 生成供示例工程安装的本地安装包

npm pack

5. 进入 example 目录

cd example

6. 安装示例工程依赖

npm install

7. 生成 React Native JavaScript Bundle

npm run dev

8. 使用 DevEco Studio 打开 example/harmony，等待依赖同步完成，完成签名配置后构建运行到设备或模拟器。

约束与限制

兼容性

依赖	要求
React Native for OpenHarmony	0.72.139（peer 依赖 react-native >= 0.72）
HarmonyOS SDK	API 21+
Example 工程 compatibleSdkVersion	6.0.1(21)
Example 工程 targetSdkVersion	6.1.1(24)
Node.js	>=18

使用限制

• 应用内评论依赖 SystemCapability.AppGalleryService.Distribution.Comment，应用详情页依赖 SystemCapability.AppGalleryService.Distribution.Recommendations；能力不可用时返回失败原因，并按配置继续尝试后续链路。
• 应用详情页拉起需要有效的目标 bundleName；HarmonyOS 侧按 HarmonyBundleName、GooglePackageName（仅 AndroidMarket.Google）、宿主应用 bundleName 的顺序解析。
• 应用详情页打开超过 5 秒未回调时按超时处理，返回「应用详情页打开超时。」。
• 鸿蒙侧不存在 Amazon 应用市场，amzn://apps/android?p=... 链接没有应用可以接住。preferredAndroidMarket 为 AndroidMarket.Amazon 时链路映射为华为应用市场详情页，目标取自 HarmonyBundleName（未配置时按上述顺序回退）；目标应用需已在华为应用市场上架，否则详情页拉起会失败并返回原因。
• 链接兜底会跳过空链接和重复链接；当所有候选链接均不可打开时，回调返回失败原因。
• AppleAppID、AmazonPackageName 和 inAppDelay 仅为上游 API 兼容保留，HarmonyOS 侧不会消费。
• HarmonyOS 原生模块未接入时，回调返回 RNRate native module is not linked on HarmonyOS。
• Rate.openURL 的 HarmonyOS 封装使用默认的非 App Linking 模式；需要开启 appLinkingOnly 时应通过 Rate.rate 的链接配置使用。

系统权限

本库不依赖额外的 HarmonyOS 系统权限。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交 Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。