ProComponents, templates & AI tooling
2.3k

Toast 轻提示更新

在屏幕顶部或底部展示的临时通知消息。

导入

import { Toast, useToast } from 'heroui-native';

结构

<Toast>
  <Toast.Title>...</Toast.Title>
  <Toast.Description>...</Toast.Description>
  <Toast.Action>...</Toast.Action>
  <Toast.Close />
</Toast>
  • Toast:主容器,负责定位、动画与滑动手势。
  • Toast.Title:标题文字,继承父级 Toast 的变体样式。
  • Toast.Description:标题下方的描述文字。
  • Toast.Action:操作按钮;按钮变体默认随 Toast 变体推断,也可覆盖。
  • Toast.Close:关闭按钮,图标按钮样式,按下时调用隐藏。

用法

用法一:简单字符串

使用纯字符串快速展示 Toast。

const { toast } = useToast();

toast.show('这是一条 Toast 消息');

用法二:配置对象

通过配置对象传入标题、描述、变体与操作按钮等。

const { toast } = useToast();

toast.show({
  variant: 'success',
  label: '套餐已升级',
  description: '可继续使用 HeroUI Chat',
  icon: <Icon name="check" />,
  actionLabel: '关闭',
  onActionPress: ({ hide }) => hide(),
});

用法三:自定义组件

使用完全自定义的组件以自由控制样式与布局。

const { toast } = useToast();

toast.show({
  component: (props) => (
    <Toast variant="accent" placement="top" {...props}>
      <Toast.Title>自定义 Toast</Toast.Title>
      <Toast.Description>这是一个自定义 Toast 组件</Toast.Description>
      <Toast.Close />
    </Toast>
  ),
});

说明:Toast 条目会做性能相关的 memo。若需把外部状态(如加载中)传入自定义 Toast,不会自动随状态重渲染。请使用 React Context、全局状态或 ref 等方式让状态能传递到 Toast 内。

禁用全部动画

使用 "disable-all" 可禁用自身及子级(如 Toast.Action 内的 Button)的全部动画。

const { toast } = useToast();

toast.show({
  variant: 'success',
  label: '操作完成',
  description: '已禁用全部动画',
  animation: 'disable-all',
});

自定义组件示例:

const { toast } = useToast();

toast.show({
  component: (props) => (
    <Toast variant="accent" animation="disable-all" {...props}>
      <Toast.Title>无动画</Toast.Title>
      <Toast.Description>
        此 Toast 已禁用全部动画
      </Toast.Description>
      <Toast.Action>操作</Toast.Action>
    </Toast>
  ),
});

示例

import { Button, Toast, useToast, useThemeColor } from 'heroui-native';
import { View } from 'react-native';

export default function ToastExample() {
  const { toast } = useToast();
  const themeColorForeground = useThemeColor('foreground');

  return (
    <View className="gap-4 p-4">
      <Button
        onPress={() =>
          toast.show({
            variant: 'success',
            label: '套餐已升级',
            description: '可继续使用 HeroUI Chat',
            actionLabel: '关闭',
            onActionPress: ({ hide }) => hide(),
          })
        }
      >
        显示成功 Toast
      </Button>

      <Button
        onPress={() =>
          toast.show({
            component: (props) => (
              <Toast variant="accent" {...props}>
                <Toast.Title>自定义 Toast</Toast.Title>
                <Toast.Description>
                  使用自定义组件渲染
                </Toast.Description>
                <Toast.Action onPress={() => props.hide()}>撤销</Toast.Action>
                <Toast.Close className="absolute top-0 right-0" />
              </Toast>
            ),
          })
        }
      >
        显示自定义 Toast
      </Button>
    </View>
  );
}

更多示例见 GitHub 仓库

全局配置

通过 HeroUINativeProviderconfig 全局配置 Toast;本地调用可覆盖默认值。

说明:Provider 的完整配置见 Provider 文档

边距(Insets)

控制 Toast 与屏幕边缘的距离,会在安全区内边距基础上叠加。例如四边距屏幕 20px:

<HeroUINativeProvider
  config={{
    toast: {
      insets: {
        top: 20,
        bottom: 20,
        left: 20,
        right: 20,
      },
    },
  }}
>
  {children}
</HeroUINativeProvider>

使用 KeyboardAvoidingView 包裹内容

KeyboardAvoidingView 包裹 Toast 内容,键盘弹出时自动避让:

import {
  KeyboardAvoidingView,
  KeyboardProvider,
} from 'react-native-keyboard-controller';
import { HeroUINativeProvider } from 'heroui-native';
import { useCallback } from 'react';

function AppContent() {
  const contentWrapper = useCallback(
    (children: React.ReactNode) => (
      <KeyboardAvoidingView
        pointerEvents="box-none"
        behavior="padding"
        keyboardVerticalOffset={12}
        className="flex-1"
      >
        {children}
      </KeyboardAvoidingView>
    ),
    []
  );

  return (
    <KeyboardProvider>
      <HeroUINativeProvider
        config={{
          toast: {
            contentWrapper,
          },
        }}
      >
        {children}
      </HeroUINativeProvider>
    </KeyboardProvider>
  );
}

默认属性

全局设置变体、位置、动画与滑动等默认值:

<HeroUINativeProvider
  config={{
    toast: {
      defaultProps: {
        variant: 'accent',
        placement: 'bottom',
        isSwipeable: false,
      },
    },
  }}
>
  {children}
</HeroUINativeProvider>

API 参考

Toast

proptypedefaultdescription
variant'default' | 'accent' | 'success' | 'warning' | 'danger''default'视觉变体
placement'top' | 'bottom''top'在屏幕上的位置
isSwipeablebooleantrue是否可滑动关闭并带橡皮筋拖拽效果
animationToastRootAnimation-动画配置
isAnimatedStyleActivebooleantrue是否启用 Reanimated 动画样式
classNamestring-Toast 容器额外 class
...ViewPropsViewProps-支持 React Native View 的全部属性

ToastRootAnimation

Toast 根动画配置,可为:

  • false"disabled":仅禁用根级动画
  • "disable-all":禁用全部动画(含子级)
  • trueundefined:使用默认动画
  • object:自定义动画配置
proptypedefaultdescription
state'disabled' | 'disable-all' | boolean-在自定义属性时禁用动画
opacity.value[number, number][1, 0]Toast 移出可视堆叠时的透明度插值
opacity.timingConfigWithTimingConfig{ duration: 300 }透明度过渡的时间配置
translateY.value[number, number][0, 10]堆叠 Toast 微位移效果的 Y 插值
translateY.timingConfigWithTimingConfig{ duration: 300 }translateY 过渡的时间配置
scale.value[number, number][1, 0.97]堆叠 Toast 景深缩放的插值
scale.timingConfigWithTimingConfig{ duration: 300 }缩放过渡的时间配置
entering.topEntryOrExitLayoutTypeFadeInUp
.springify()
.withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] })
.mass(3)
顶部放置时的进入动画
entering.bottomEntryOrExitLayoutTypeFadeInDown
.springify()
.withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] })
.mass(3)
底部放置时的进入动画
exiting.topEntryOrExitLayoutType关键帧动画
translateY: -100, scale: 0.97, opacity: 0.5
顶部放置时的退出动画
exiting.bottomEntryOrExitLayoutType关键帧动画
translateY: 100, scale: 0.97, opacity: 0.5
底部放置时的退出动画

Toast.Title

proptypedefaultdescription
childrenReact.ReactNode-标题内容
classNamestring-额外的 class
...TextPropsTextProps-支持 React Native Text 的全部属性

Toast.Description

proptypedefaultdescription
childrenReact.ReactNode-描述内容
classNamestring-额外的 class
...TextPropsTextProps-支持 React Native Text 的全部属性

Toast.Action

Toast.Action 继承 Button 的全部属性。按钮变体默认由 Toast 变体推断,也可覆盖。

proptypedefaultdescription
childrenReact.ReactNode-操作按钮文字
variantButtonVariant-按钮变体;未提供时由 Toast 变体自动决定
size'sm' | 'md' | 'lg''sm'操作按钮尺寸
classNamestring-额外的 class

onPressisDisabled 等其余属性见 Button API 参考

Toast.Close

Toast.Close 继承 Button 的全部属性。

proptypedefaultdescription
childrenReact.ReactNode-自定义关闭图标;默认使用 CloseIcon
iconProps{ size?: number; color?: string }-默认关闭图标的属性
size'sm' | 'md' | 'lg''sm'关闭按钮尺寸
classNamestring-额外的 class
onPress(event: any) => void-自定义按下处理;默认隐藏 Toast

其余继承属性见 Button API 参考

ToastProviderProps

通过 HeroUINativeProviderconfig.toast 进行全局配置时可用的属性。

proptypedefaultdescription
defaultPropsToastGlobalConfig-全局默认配置,可被单次调用覆盖
disableFullWindowOverlaybooleanfalseiOS 上为 true 时使用普通 View 替代 FullWindowOverlay,便于元素检查器;Toast 将不再叠在原生模态之上
unstable_accessibilityContainerViewIsModalbooleanfalse是否将覆盖窗口视为模态容器(VoiceOver)。为 true 时焦点限制在覆盖层内。仅 iOS;可能随 react-native-screens 变化
insetsToastInsets-相对屏幕边缘的内边距(与安全区内边距相加)
maxVisibleToastsnumber3最大可见条数,超过后开始降低透明度
contentWrapper(children: React.ReactNode) => React.ReactElement-自定义包裹 Toast 内容的函数
childrenReact.ReactNode-子节点

ToastGlobalConfig

全局默认,可被单次调用覆盖。

proptypedescription
variant'default' | 'accent' | 'success' | 'warning' | 'danger'视觉变体
placement'top' | 'bottom'位置
isSwipeableboolean是否可滑动关闭并带橡皮筋效果
animationToastRootAnimationToast 动画配置

ToastInsets

相对屏幕边缘的间距,会与安全区内边距相加。

proptypedefaultdescription
topnumber-距顶部像素(叠加安全区)。平台默认:iOS 0,Android 12
bottomnumber-距底部像素(叠加安全区)。平台默认:iOS 6,Android 12
leftnumber-距左侧像素(叠加安全区)。默认 12
rightnumber-距右侧像素(叠加安全区)。默认 12

Hooks

useToast

访问 Toast 能力,必须在 ToastProvider 内使用(由 HeroUINativeProvider 提供)。

返回值typedescription
toastToastManagershowhide 等方法的 Toast 管理器
isToastVisibleboolean当前是否有 Toast 可见

ToastManager

methodtypedescription
show(options: string | ToastShowOptions) => string显示 Toast,返回 ID。支持字符串、配置对象或自定义组件三种形式
hide(ids?: string | string[] | 'all') => void隐藏一条或多条。无参隐藏最后一条;'all' 隐藏全部;传入 ID 或 ID 数组隐藏指定项

ToastShowOptions

展示选项:默认样式的配置对象,或自定义组件。

使用配置对象(无 component)时:

proptypedefaultdescription
variant'default' | 'accent' | 'success' | 'warning' | 'danger'-视觉变体
placement'top' | 'bottom'-位置
isSwipeableboolean-是否可滑动关闭
animationToastRootAnimation | false | "disabled" | "disable-all"-动画配置
durationnumber | 'persistent'4000自动隐藏毫秒数;'persistent' 表示不自动隐藏
idstring-可选 ID;未提供则自动生成
labelstring-标题文字
descriptionstring-描述文字
actionLabelstring-操作按钮文案
onActionPress(helpers: { show: (options: string | ToastShowOptions) => string; hide: (ids?: string | string[] | 'all') => void }) => void-操作按钮按下回调
iconReact.ReactNode-左侧图标
onShow() => void-显示时回调
onHide() => void-隐藏时回调

使用自定义组件时:

proptypedefaultdescription
idstring-可选 ID;未提供则自动生成
component(props: ToastComponentProps) => React.ReactElement-接收 Toast props 并返回 React 元素的函数
durationnumber | 'persistent'4000自动隐藏毫秒数;'persistent' 表示不自动隐藏
onShow() => void-显示时回调
onHide() => void-隐藏时回调

特别说明

元素检查器(iOS)

Toast 在 iOS 上使用 FullWindowOverlay。开发时若需使用 React Native 元素检查器,可在 HeroUINativeProviderconfig.toast 中设置 disableFullWindowOverlay={true}。代价:Toast 将无法叠在原生系统模态之上。

本页目录