@bingtang-rn/react-native-toast-notifications for HarmonyOS

本项目基于 react-native-toast-notifications 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 3.4.0 | 0.72+ | 否 | API17+ |

安装

npm install @bingtang-rn/react-native-toast-notifications

使用

import React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import Toast, { ToastProvider, useToast } from 'react-native-toast-notifications';

// 1. 用 ToastProvider 包裹根组件（配置全局默认值）
function App() {
  return (
    <ToastProvider
      placement="bottom"
      duration={5000}
      animationType="slide-in"
      animationDuration={250}
      swipeEnabled={true}
      successColor="#2E7D32"
      dangerColor="#D32F2F"
      warningColor="#ED6C02"
      renderType={{
        custom_toast: (toast) => (
          <TouchableOpacity onPress={() => toast.onHide()}>
            <Text>{toast.message}</Text>
          </TouchableOpacity>
        ),
      }}
    >
      <Main />
    </ToastProvider>
  );
}

// 2. 在子树内用 useToast() 取实例
function Main() {
  const toast = useToast();

  const showSuccess = () => {
    const id = toast.show('保存成功', { type: 'success' });
    // id 可用于后续 update / hide / isOpen
  };

  const updateToast = (id: string) => {
    toast.update(id, '已更新为警告', { type: 'warning' });
  };

  return null;
}

// 3. 也可在 React 树外用全局单例 Toast（如 redux action / 工具函数）
// Toast.show('全局通知');
// Toast.hideAll();

import 时使用原库名 'react-native-toast-notifications'，而非鸿蒙包名（由 harmony.alias 自动映射到 @bingtang-rn/react-native-toast-notifications）。

平台差异：

• KeyboardAvoidingView 在 HarmonyOS 下使用 position 行为，底部 toast 会跟随键盘区域上移。
• useNativeDriver 在鸿蒙下启用 native driver（true）。
• swipeThreshold 在鸿蒙下取 10（与 Android 一致，规避误触发）。
• 未降级为 @ohos.promptAction.showToast：系统 Toast 样式单一、不可定制、不可含交互元素、单次 ≤3 秒，与「Fully Customizable」核心价值不重叠，故保留 JS 层渲染叠加。

权限要求：

• 无。本库为纯 JS/TS 实现，不申请任何 HarmonyOS 权限，不消费任何 @ohos.* Kit。Toast UI 全部由 React Native 核心原语（View/Text/Animated/PanResponder/KeyboardAvoidingView 等）在 JS 层渲染叠加。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 否 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-toast-notifications": "file:../../node_modules/@bingtang-rn/react-native-toast-notifications/harmony/toast_notifications.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

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

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-toast-notifications/src/main/cpp" ./toast_notifications)

target_link_libraries(rnoh_app PUBLIC toast_notifications)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "ToastNotificationsPackage.h"

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

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { ToastNotificationsPackage } from '@bingtang-rn/react-native-toast-notifications/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | ToastProvider | 全局 Provider，包裹根组件并配置默认值 | placement/duration/animationType/animationDuration/successColor/dangerColor/warningColor/normalColor/icon/successIcon/dangerIcon/warningIcon/textStyle/style/offset/offsetTop/offsetBottom/swipeEnabled/renderToast/renderType | — | ✅ 完全支持 | | useToast | 在 Provider 子树内获取 Toast 实例 | 无 | { show, update, hide, hideAll, isOpen } | ✅ 完全支持 | | Toast（全局单例） | React 树外调用的全局 Toast 单例 | 无 | { show, update, hide, hideAll, isOpen } | ✅ 完全支持 | | show | 显示新 toast，返回 id | message: string | JSX.Element, options?: ToastOptions | string (id) | ✅ 完全支持 | | update | 原地更新已存在的 toast（不重置计时器） | id: string, message: string | JSX.Element, options?: ToastOptions | void | ✅ 完全支持 | | hide | 关闭单条 toast（触发退场动画后移除） | id: string | void | ✅ 完全支持 | | hideAll | 关闭栈内所有 toast | 无 | void | ✅ 完全支持 | | isOpen | 查询某 toast 是否处于打开状态 | id: string | boolean | ✅ 完全支持 | | ToastOptions.type | toast 类型（含自定义类型） | 'normal' | 'success' | 'danger' | 'warning' | string | — | ✅ 完全支持 | | ToastOptions.placement | 显示位置 | 'top' | 'bottom' | 'center' | — | ✅ 完全支持 | | ToastOptions.duration | 停留时长(ms)，0 表示不自动关闭 | number | — | ✅ 完全支持 | | ToastOptions.animationType | 进出动画 | 'slide-in' | 'zoom-in' | — | ✅ 完全支持 | | ToastOptions.animationDuration | 动画时长(ms) | number | — | ✅ 完全支持 | | ToastOptions.swipeEnabled | 是否允许滑动关闭 | boolean | — | ✅ 完全支持 | | ToastOptions.id | 自定义 id（用于后续 update/hide/isOpen） | string | — | ✅ 完全支持 | | ToastOptions.onPress | 点击 toast 回调 | (id: string) => void | — | ✅ 完全支持 | | ToastOptions.onClose | 关闭后回调 | () => void | — | ✅ 完全支持 | | ToastOptions.data | 自定义 payload（供 renderType 渲染） | any | — | ✅ 完全支持 | | ToastOptions.style / textStyle | 自定义容器样式 / 文字样式 | StyleProp / StyleProp | — | ✅ 完全支持 | | ToastOptions.icon | 自定义图标 | JSX.Element | — | ✅ 完全支持 | | ToastOptions.successColor / dangerColor / warningColor / normalColor | 各类型背景色 | string | — | ✅ 完全支持 | | ToastOptions.successIcon / dangerIcon / warningIcon | 各类型图标 | JSX.Element | — | ✅ 完全支持 | | renderToast | 完全自定义 toast 渲染 | (toast: ToastProps) => JSX.Element | — | ✅ 完全支持 | | renderType | 自定义类型渲染映射 | { [type: string]: (toast: ToastProps) => JSX.Element } | — | ✅ 完全支持 | | offset / offsetTop / offsetBottom | 距顶/底偏移 | number | — | ✅ 完全支持 |

平台差异

• KeyboardAvoidingView：HarmonyOS 使用 position 行为让底部 toast 跟随键盘区域上移。
• 本库未降级为 @ohos.promptAction.showToast：系统 Toast 样式单一、不可定制、不可含交互元素、单次 ≤3 秒，与「Fully Customizable」核心价值不重叠，故保留 JS 层渲染叠加。

未实现功能

无。本库全部公开能力（show/update/hide/hideAll/isOpen、四种预置类型、renderType 自定义类型、三向 placement、slide-in/zoom-in 动画、滑动关闭、onPress/onClose、全局单例、堆叠、自定义图标/颜色/样式、offset 偏移、data payload、swipeEnabled）均已在 HarmonyOS 上实现并通过 Example 验证。

使用限制

• 无权限要求、无原生 Kit 依赖。
• 本库为纯 JS/TS 实现（js_only），无需 Manual Link / C++ / ETS Package 注册：npm install @bingtang-rn/react-native-toast-notifications 后由 harmony.alias 自动把 react-native-toast-notifications 的 import 重定向到鸿蒙化包，即可使用。
• Platform.OS 全部分支已迁移为 Platform.select({ harmony: ... }) 显式键，无排除法判断。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

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

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

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

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

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

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无（或列出已知问题）

开源协议

本项目基于 [原始库协议](原始库 LICENSE 链接)，详见 LICENSE 文件。