react-native-summer-toast

English

一个轻量、可靠的 React Native Toast 提示组件，同时兼容 Expo 和纯 React Native 项目。

• ✅ 零原生依赖，纯 JS 实现
• ✅ 零外部图标库依赖，内置默认图标
• ✅ 支持自定义图标渲染
• ✅ 支持成功、失败、提示、加载中等多种类型
• ✅ 支持自定义图片和自定义内容
• ✅ 支持遮罩层（阻止用户操作）
• ✅ 淡入淡出动画

演示

安装

npm install react-native-summer-toast
# 或
yarn add react-native-summer-toast

如果你的项目包含 iOS 原生工程，还需要安装 CocoaPods 依赖：

cd ios && pod install && cd ..

无需额外安装任何图标库。如果你想使用自定义图标（如 Ionicons），可以通过 renderIcon 属性传入。

快速开始

1. 在应用根组件中放置 Toast 实例

import SummerToastInstance from 'react-native-summer-toast';

export default function App() {
    return (
        <View style={{ flex: 1 }}>
            {/* 你的页面内容 */}
            <MyScreen />

            {/* 放在根组件的最后，确保显示在最上层 */}
            <SummerToastInstance />
        </View>
    );
}

2. 在任意位置调用 Toast

import { Toast } from 'react-native-summer-toast';

// 成功提示
Toast.show({ type: 'success', message: '操作成功！' });

// 错误提示
Toast.show({ type: 'error', message: '出错了' });

// 信息提示
Toast.show({ type: 'info', message: '这是一条信息' });

// 纯文字提示（不显示图标）
Toast.show({ message: '这是纯文字提示' });

// 加载中（需要手动关闭）
Toast.show({ type: 'loading', message: '加载中...', mask: true });
// 完成后手动隐藏
Toast.hide();

// 自定义显示时长（毫秒）
Toast.show({ type: 'success', message: '我会显示 5 秒', duration: 5000 });

API

Toast.show(options)

显示一个 Toast 提示。

| 参数 | 类型 | 必填 | 默认值 | 说明 | | ---------- | --------------------- | ---- | ------- | ------------------------------------------------ | | message | string | 否 | - | 提示文字内容 | | type | ToastType | 否 | - | 提示类型，决定显示的图标 | | image | ImageSourcePropType | 否 | - | 自定义图片，传入后优先于 type 图标显示 | | content | React.ReactNode | 否 | - | 完全自定义的内容区域 | | duration | number | 否 | 2000 | 自动隐藏时间（毫秒）。loading 类型不会自动隐藏 | | mask | boolean | 否 | false | 是否显示遮罩层，阻止用户操作底部内容 |

ToastType 可选值

| 值 | 说明 | 默认图标 | | ----------- | ------ | -------------- | | 'success' | 成功 | ✓（绿色圆圈） | | 'error' | 错误 | ✕（红色圆圈） | | 'info' | 信息 | i（蓝色圆圈） | | 'loading' | 加载中 | 系统加载指示器 |

Toast.hide()

手动隐藏当前正在显示的 Toast。主要用于 loading 类型场景。

组件属性

<SummerToastInstance /> 属性

| 属性 | 类型 | 必填 | 说明 | | ------------ | --------------------------------------- | ---- | -------------------------------------------------------------------------------------------------- | | renderIcon | (type?: ToastType) => React.ReactNode | 否 | 自定义图标渲染函数。接收当前 toast 类型作为参数，返回 React 元素。不传则使用内置的纯 RN 默认图标。 |

自定义图标示例

使用 Ionicons（Expo 项目）

import { Ionicons } from '@expo/vector-icons';
import SummerToastInstance from 'react-native-summer-toast';

<SummerToastInstance
    renderIcon={type => {
        switch (type) {
            case 'success':
                return <Ionicons name="checkmark-circle-outline" size={40} color="#4ade80" />;
            case 'error':
                return <Ionicons name="close-circle-outline" size={40} color="#f87171" />;
            case 'info':
                return <Ionicons name="information-circle-outline" size={40} color="#60a5fa" />;
            default:
                return null;
        }
    }}
/>;

使用 react-native-vector-icons（纯 RN 项目）

import Icon from 'react-native-vector-icons/MaterialIcons';
import SummerToastInstance from 'react-native-summer-toast';

<SummerToastInstance
    renderIcon={type => {
        switch (type) {
            case 'success':
                return <Icon name="check-circle" size={40} color="#4ade80" />;
            case 'error':
                return <Icon name="cancel" size={40} color="#f87171" />;
            case 'info':
                return <Icon name="info" size={40} color="#60a5fa" />;
            default:
                return null;
        }
    }}
/>;

导出说明

import SummerToastInstance, { Toast } from 'react-native-summer-toast';

| 导出 | 类型 | 说明 | | --------------------------------- | --------------- | --------------------------------------------------------- | | default (SummerToastInstance) | React 组件 | Toast 容器组件，放在应用根组件中 | | Toast | 对象 | 全局调用对象，包含 show 和 hide 方法 | | ToastType | TypeScript 类型 | Toast 类型：'success' \| 'error' \| 'loading' \| 'info' | | ToastOptions | TypeScript 接口 | Toast.show() 的参数类型 | | ToastMethods | TypeScript 接口 | Toast 实例方法类型（show / hide） | | SummerToastProps | TypeScript 接口 | SummerToastInstance 组件的属性类型 |

注意事项

在 Modal 中使用

React Native 的 <Modal> 不是一个普通的 View——它在 iOS 和 Android 原生层分别创建了新的 UIWindow / Dialog Window。不同 Window 之间的层级关系由操作系统管理，应用层的 zIndex 只在单个 Window 内部生效，无法跨越 Window 边界。

因此，放在根组件的 <SummerToastInstance /> 无法显示在 Modal 之上。你需要在 Modal 内部再放置一个实例：

import { Modal, View } from 'react-native';
import SummerToastInstance, { Toast } from 'react-native-summer-toast';

<Modal visible={visible}>
    <View style={{ flex: 1 }}>
        {/* Modal 内的页面内容 */}
        <YourModalContent />

        {/* 在 Modal 内部再放一个 Toast 实例 */}
        <SummerToastInstance />
    </View>
</Modal>;

组件内部支持多实例自动管理，Toast.show() 会自动调用最后挂载的实例，所以 Modal 打开时 Toast 会正确显示在 Modal 内部，Modal 关闭后自动回退到根实例。

兼容性

| 环境 | 是否支持 | | --------------------- | -------- | | Expo | ✅ | | 纯 React Native (CLI) | ✅ | | Android | ✅ | | iOS | ✅ |

许可证

MIT