# Toast 轻提示
**Category**: native
**URL**: https://www.heroui.com/cn/docs/native/components/toast
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/native/components/(overlays)/toast.mdx
> 在屏幕顶部或底部展示的临时通知消息。
***
## 导入
```tsx
import { Toast, useToast } from 'heroui-native';
```
## 结构
```tsx
...
...
...
```
- **Toast**：主容器，负责定位、动画与滑动手势。
- **Toast.Title**：标题文字，继承父级 Toast 的变体样式。
- **Toast.Description**：标题下方的描述文字。
- **Toast.Action**：操作按钮；按钮变体默认随 Toast 变体推断，也可覆盖。
- **Toast.Close**：关闭按钮，图标按钮样式，按下时调用隐藏。
## 用法
### 用法一：简单字符串
使用纯字符串快速展示 Toast。
```tsx
const { toast } = useToast();
toast.show('这是一条 Toast 消息');
```
### 用法二：配置对象
通过配置对象传入标题、描述、变体与操作按钮等。
```tsx
const { toast } = useToast();
toast.show({
variant: 'success',
label: '套餐已升级',
description: '可继续使用 HeroUI Chat',
icon: ,
actionLabel: '关闭',
onActionPress: ({ hide }) => hide(),
});
```
### 用法三：自定义组件
使用完全自定义的组件以自由控制样式与布局。
```tsx
const { toast } = useToast();
toast.show({
component: (props) => (
自定义 Toast
这是一个自定义 Toast 组件
),
});
```
**说明**：Toast 条目会做性能相关的 memo。若需把外部状态（如加载中）传入自定义 Toast，不会自动随状态重渲染。请使用 React Context、全局状态或 ref 等方式让状态能传递到 Toast 内。
### 禁用全部动画
使用 `"disable-all"` 可禁用自身及子级（如 `Toast.Action` 内的 `Button`）的全部动画。
```tsx
const { toast } = useToast();
toast.show({
variant: 'success',
label: '操作完成',
description: '已禁用全部动画',
animation: 'disable-all',
});
```
自定义组件示例：
```tsx
const { toast } = useToast();
toast.show({
component: (props) => (
无动画
此 Toast 已禁用全部动画
操作
),
});
```
## 示例
```tsx
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 (
);
}
```
更多示例见 [GitHub 仓库]()。
## 全局配置
通过 `HeroUINativeProvider` 的 `config` 全局配置 Toast；本地调用可覆盖默认值。
> **说明**：Provider 的完整配置见 [Provider 文档](/docs/native/getting-started/handbook/provider#toast-configuration)。
### 边距（Insets）
控制 Toast 与屏幕边缘的距离，会在安全区内边距基础上叠加。例如四边距屏幕 20px：
```tsx
{children}
```
### 使用 KeyboardAvoidingView 包裹内容
用 `KeyboardAvoidingView` 包裹 Toast 内容，键盘弹出时自动避让：
```tsx
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) => (
{children}
),
[]
);
return (
{children}
);
}
```
### 默认属性
全局设置变体、位置、动画与滑动等默认值：
```tsx
{children}
```
## 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](button) 的全部属性。按钮变体默认由 Toast 变体推断，也可覆盖。
| prop | type | default | description |
| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | 操作按钮文字 |
| `variant` | `ButtonVariant` | - | 按钮变体；未提供时由 Toast 变体自动决定 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | 操作按钮尺寸 |
| `className` | `string` | - | 额外的 class |
`onPress`、`isDisabled` 等其余属性见 [Button API 参考](button#api-reference)。
### Toast.Close
`Toast.Close` 继承 [Button](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 参考](button#api-reference)。
### 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 将无法叠在原生系统模态之上。