react-native-toast

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

项目介绍

@hxa-rn/react-native-toast（当前版本 1.0.8）是 @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 main

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

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-toast@^1.0.8，不再使用本地 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/react-native-harmony@0.72.139）
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