react-native-toast

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

项目介绍

@hxa-rn/react-native-toast（当前版本 1.0.7-beta.1）是 @remobile/react-native-toast 的 React Native 鸿蒙（OpenHarmony）适配版本，提供类 Android 风格的 Toast 轻提示能力。

本仓库采用 js-only wrapper 模式：仅包含 JS 封装层（src/index.js），原生 NativeToast TurboModule（ETS ToastModule + ToastPackage）由官方鸿蒙适配包 @react-native-ohos/react-native-toast 提供。JS 公开 API 与原库一致，共 8 个方法（7 个显示类方法 + hide()）。

核心能力包括：

• 显示 Toast 消息（支持自定义文本；空消息兜底为「未知数据」）
• 持续时间控制（short 约 2 秒、long 约 5 秒）
• 显示位置控制（top / center / bottom）
• 6 个快捷显示方法（短/长时长 × 顶/中/底位置组合）

集成指南

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

安装后，业务代码仍通过 harmony.alias 映射的原包名引用：

import Toast from '@remobile/react-native-toast';

Peer 依赖：

| 依赖 | 版本要求 | |------|----------| | react-native | >= 0.72 | | Node.js | >= 18（开发环境） |

本模块为 js-only 封装，原生 ToastPackage 由依赖包 @react-native-ohos/react-native-toast@~1.0.8（RN 0.72 线）提供。工程启用 Autolink 后无需手动注册 Package；若关闭 Autolink 或使用官方包 0.77 线（~1.1.0，不支持 Autolink），需在 PackageProvider.ets 中手动注册 ToastPackage（详见官方包文档）。

使用说明

import Toast from '@remobile/react-native-toast';

// 默认显示（short 时长，bottom 位置）
Toast.show('Hello HarmonyOS!');

// 短时长 + 位置组合
Toast.showShortTop('顶部短提示');
Toast.showShortCenter('中部短提示');
Toast.showShortBottom('底部短提示');

// 长时长 + 位置组合
Toast.showLongTop('顶部长提示');
Toast.showLongCenter('中部长提示');
Toast.showLongBottom('底部长提示');

// 隐藏（鸿蒙端为 no-op，调用安全但不生效）
Toast.hide();

// 空消息兜底为「未知数据」
Toast.show('');

传入空字符串或空消息时，库内兜底显示「未知数据」。

接口文档

默认导出对象 Toast，包含以下公开方法：

| 方法 | 签名 | 功能 | 参数 | 返回值 | 鸿蒙支持 | |------|------|------|------|--------|----------| | show | show(message: string): void | 显示 Toast（short 时长，bottom 位置） | message：消息文本；空值兜底「未知数据」 | void | ✅ | | showShortTop | showShortTop(message: string): void | 短时长 + 顶部 | message：消息文本 | void | ✅ | | showShortCenter | showShortCenter(message: string): void | 短时长 + 居中 | message：消息文本 | void | ✅ | | showShortBottom | showShortBottom(message: string): void | 短时长 + 底部 | message：消息文本 | void | ✅ | | showLongTop | showLongTop(message: string): void | 长时长 + 顶部 | message：消息文本 | void | ✅ | | showLongCenter | showLongCenter(message: string): void | 长时长 + 居中 | message：消息文本 | void | ✅ | | showLongBottom | showLongBottom(message: string): void | 长时长 + 底部 | message：消息文本 | void | ✅ | | hide | hide(): void | 隐藏当前 Toast | 无 | void | ❌ no-op |

底层实现：官方包 ToastModule 调用 @ohos.arkui.UIContext.PromptAction.showToast；duration 映射 short→2000ms、long→5000ms；position 映射 Alignment.Top/Center/Bottom（top 叠加 +20px、bottom 叠加 -20px 基准偏移）。

快速验证（运行 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-toast.git
cd react-native-toast
git checkout br_rnoh0.72

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

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 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 | RN >= 0.72；框架基线 RNOH 0.72（Example 使用 @react-native-oh/[email protected]） | | HarmonyOS SDK | Demo 工程 compatibleSdkVersion 为 5.0.1(13) | | Node.js | >= 18（运行 Example 建议 >= 20） | | 权限 | 无额外系统权限；Toast 通过 UIContext.PromptAction.showToast（API 10+）实现 | | 架构 | js-only 封装；原生 NativeToast 由 @react-native-ohos/react-native-toast@~1.0.8 提供 | | hide() | 鸿蒙端为 no-op（ArkUI Toast 无编程式取消接口），调用安全但不生效 | | Autolink | RN 0.72 线（~1.0.8）支持 Autolink；升级至 0.77/0.82 需同步官方包 ~1.1.0/~1.2.0 并确认是否需手动链接 |

开源license

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

问题反馈渠道

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

• GitCode 仓库：https://gitcode.com/hxa-rn/react-native-toast
• Issue 提交：https://gitcode.com/hxa-rn/react-native-toast/issues