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 仓库。
全局配置
通过 HeroUINativeProvider 的 config 全局配置 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
| prop | type | default | description |
|---|---|---|---|
variant | 'default' | 'accent' | 'success' | 'warning' | 'danger' | 'default' | 视觉变体 |
placement | 'top' | 'bottom' | 'top' | 在屏幕上的位置 |
isSwipeable | boolean | true | 是否可滑动关闭并带橡皮筋拖拽效果 |
animation | ToastRootAnimation | - | 动画配置 |
isAnimatedStyleActive | boolean | true | 是否启用 Reanimated 动画样式 |
className | string | - | Toast 容器额外 class |
...ViewProps | ViewProps | - | 支持 React Native View 的全部属性 |
ToastRootAnimation
Toast 根动画配置,可为:
false或"disabled":仅禁用根级动画"disable-all":禁用全部动画(含子级)true或undefined:使用默认动画object:自定义动画配置
| prop | type | default | description |
|---|---|---|---|
state | 'disabled' | 'disable-all' | boolean | - | 在自定义属性时禁用动画 |
opacity.value | [number, number] | [1, 0] | Toast 移出可视堆叠时的透明度插值 |
opacity.timingConfig | WithTimingConfig | { duration: 300 } | 透明度过渡的时间配置 |
translateY.value | [number, number] | [0, 10] | 堆叠 Toast 微位移效果的 Y 插值 |
translateY.timingConfig | WithTimingConfig | { duration: 300 } | translateY 过渡的时间配置 |
scale.value | [number, number] | [1, 0.97] | 堆叠 Toast 景深缩放的插值 |
scale.timingConfig | WithTimingConfig | { duration: 300 } | 缩放过渡的时间配置 |
entering.top | EntryOrExitLayoutType | FadeInUp.springify().withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] }).mass(3) | 顶部放置时的进入动画 |
entering.bottom | EntryOrExitLayoutType | FadeInDown.springify().withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] }).mass(3) | 底部放置时的进入动画 |
exiting.top | EntryOrExitLayoutType | 关键帧动画translateY: -100, scale: 0.97, opacity: 0.5 | 顶部放置时的退出动画 |
exiting.bottom | EntryOrExitLayoutType | 关键帧动画translateY: 100, scale: 0.97, opacity: 0.5 | 底部放置时的退出动画 |
Toast.Title
| prop | type | default | description |
|---|---|---|---|
children | React.ReactNode | - | 标题内容 |
className | string | - | 额外的 class |
...TextProps | TextProps | - | 支持 React Native Text 的全部属性 |
Toast.Description
| prop | type | default | description |
|---|---|---|---|
children | React.ReactNode | - | 描述内容 |
className | string | - | 额外的 class |
...TextProps | TextProps | - | 支持 React Native Text 的全部属性 |
Toast.Action
Toast.Action 继承 Button 的全部属性。按钮变体默认由 Toast 变体推断,也可覆盖。
| prop | type | default | description |
|---|---|---|---|
children | React.ReactNode | - | 操作按钮文字 |
variant | ButtonVariant | - | 按钮变体;未提供时由 Toast 变体自动决定 |
size | 'sm' | 'md' | 'lg' | 'sm' | 操作按钮尺寸 |
className | string | - | 额外的 class |
onPress、isDisabled 等其余属性见 Button API 参考。
Toast.Close
Toast.Close 继承 Button 的全部属性。
| prop | type | default | description |
|---|---|---|---|
children | React.ReactNode | - | 自定义关闭图标;默认使用 CloseIcon |
iconProps | { size?: number; color?: string } | - | 默认关闭图标的属性 |
size | 'sm' | 'md' | 'lg' | 'sm' | 关闭按钮尺寸 |
className | string | - | 额外的 class |
onPress | (event: any) => void | - | 自定义按下处理;默认隐藏 Toast |
其余继承属性见 Button API 参考。
ToastProviderProps
通过 HeroUINativeProvider 的 config.toast 进行全局配置时可用的属性。
| prop | type | default | description |
|---|---|---|---|
defaultProps | ToastGlobalConfig | - | 全局默认配置,可被单次调用覆盖 |
disableFullWindowOverlay | boolean | false | iOS 上为 true 时使用普通 View 替代 FullWindowOverlay,便于元素检查器;Toast 将不再叠在原生模态之上 |
unstable_accessibilityContainerViewIsModal | boolean | false | 是否将覆盖窗口视为模态容器(VoiceOver)。为 true 时焦点限制在覆盖层内。仅 iOS;可能随 react-native-screens 变化 |
insets | ToastInsets | - | 相对屏幕边缘的内边距(与安全区内边距相加) |
maxVisibleToasts | number | 3 | 最大可见条数,超过后开始降低透明度 |
contentWrapper | (children: React.ReactNode) => React.ReactElement | - | 自定义包裹 Toast 内容的函数 |
children | React.ReactNode | - | 子节点 |
ToastGlobalConfig
全局默认,可被单次调用覆盖。
| prop | type | description |
|---|---|---|
variant | 'default' | 'accent' | 'success' | 'warning' | 'danger' | 视觉变体 |
placement | 'top' | 'bottom' | 位置 |
isSwipeable | boolean | 是否可滑动关闭并带橡皮筋效果 |
animation | ToastRootAnimation | Toast 动画配置 |
ToastInsets
相对屏幕边缘的间距,会与安全区内边距相加。
| prop | type | default | description |
|---|---|---|---|
top | number | - | 距顶部像素(叠加安全区)。平台默认:iOS 0,Android 12 |
bottom | number | - | 距底部像素(叠加安全区)。平台默认:iOS 6,Android 12 |
left | number | - | 距左侧像素(叠加安全区)。默认 12 |
right | number | - | 距右侧像素(叠加安全区)。默认 12 |
Hooks
useToast
访问 Toast 能力,必须在 ToastProvider 内使用(由 HeroUINativeProvider 提供)。
| 返回值 | type | description |
|---|---|---|
toast | ToastManager | 含 show、hide 等方法的 Toast 管理器 |
isToastVisible | boolean | 当前是否有 Toast 可见 |
ToastManager
| method | type | description |
|---|---|---|
show | (options: string | ToastShowOptions) => string | 显示 Toast,返回 ID。支持字符串、配置对象或自定义组件三种形式 |
hide | (ids?: string | string[] | 'all') => void | 隐藏一条或多条。无参隐藏最后一条;'all' 隐藏全部;传入 ID 或 ID 数组隐藏指定项 |
ToastShowOptions
展示选项:默认样式的配置对象,或自定义组件。
使用配置对象(无 component)时:
| prop | type | default | description |
|---|---|---|---|
variant | 'default' | 'accent' | 'success' | 'warning' | 'danger' | - | 视觉变体 |
placement | 'top' | 'bottom' | - | 位置 |
isSwipeable | boolean | - | 是否可滑动关闭 |
animation | ToastRootAnimation | false | "disabled" | "disable-all" | - | 动画配置 |
duration | number | 'persistent' | 4000 | 自动隐藏毫秒数;'persistent' 表示不自动隐藏 |
id | string | - | 可选 ID;未提供则自动生成 |
label | string | - | 标题文字 |
description | string | - | 描述文字 |
actionLabel | string | - | 操作按钮文案 |
onActionPress | (helpers: { show: (options: string | ToastShowOptions) => string; hide: (ids?: string | string[] | 'all') => void }) => void | - | 操作按钮按下回调 |
icon | React.ReactNode | - | 左侧图标 |
onShow | () => void | - | 显示时回调 |
onHide | () => void | - | 隐藏时回调 |
使用自定义组件时:
| prop | type | default | description |
|---|---|---|---|
id | string | - | 可选 ID;未提供则自动生成 |
component | (props: ToastComponentProps) => React.ReactElement | - | 接收 Toast props 并返回 React 元素的函数 |
duration | number | 'persistent' | 4000 | 自动隐藏毫秒数;'persistent' 表示不自动隐藏 |
onShow | () => void | - | 显示时回调 |
onHide | () => void | - | 隐藏时回调 |
特别说明
元素检查器(iOS)
Toast 在 iOS 上使用 FullWindowOverlay。开发时若需使用 React Native 元素检查器,可在 HeroUINativeProvider 的 config.toast 中设置 disableFullWindowOverlay={true}。代价:Toast 将无法叠在原生系统模态之上。