# 通知提示 · Toast

- 页面: https://jiguang132.com/zh/resources/astryx/docs/toast
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

显示操作反馈，并支持关闭及持续时间设置。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **通知提示 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **通知提示 · 交互示例 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **通知提示 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **通知提示 · 交互示例 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **通知提示 · 交互示例 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **通知提示 · 交互示例 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Toast

Toast 显示简短的非阻塞通知，用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景，如保存、删除或状态变更。

生产环境中推荐使用 `useToast()` hook，它通过 `ToastViewport` 处理定位、堆叠、自动关闭和去重。Toast 会保持在视口和安全区域边距内，较长的消息会换行，并根据配置的顶部或底部边缘进入、退出或滑动关闭。垂直滑动与位置动效使用同一空间模型：顶部 Toast 向上离开，底部 Toast 向下离开。只有在动作明确朝向关闭边缘时才会接管原生触摸移动，滑动关闭继续报告现有的 manual 原因。触控笔属于直接接触输入，因此支持相同手势；鼠标拖动会与桌面文本选择冲突，所以不启用，关闭按钮始终可用。当操作或消息必须持续可用时，请显式设置 `isAutoHide: false`。`Toast` 组件以内联方式渲染 toast 视觉元素，适用于不需要视口生命周期的预览、文档和静态展示。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| body * | ReactNode |  | 主要消息内容。 |
| type | 'info' \| 'error' | 'info' | Toast 类型，控制背景颜色。error toast 持续显示直到关闭。 |
| isAutoHide | boolean |  | 是否自动关闭。info 默认为 true，error 默认为 false。 |
| autoHideDuration | number | 5000 | 自动关闭前的持续时间（毫秒）。定时内容必须符合 WCAG 2.2.1。 |
| endContent | ReactNode |  | 尾部渲染的内容（如撤销按钮、链接）。操作标签应保持简短。 |
| uniqueID | string |  | 用于去重的唯一标识符。 |
| collisionBehavior | 'overwrite' \| 'ignore' | 'overwrite' | 当已存在相同 uniqueID 的 toast 时的行为。 |
| onHide | (reason: "auto" \| "manual") => void |  | 当 toast 被移除时触发的回调。 |
| onDismiss * | (reason: "auto" \| "manual") => void |  | Callback fired when the toast is dismissed. |
| renderContent | (toast: ToastContentRenderProps) => ReactNode |  | 用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标、实时区域角色和自动关闭行为，并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件：请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置：应用可通过封装 useToast 并在每次调用时传入来共享同一套布局；而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss}，其中 type 为 'info' \| 'error'。 |

### 使用建议

- 保持消息简短，只需几个词告诉用户发生了什么，如"更改已保存"或"消息已发送"。
- 在 endContent 插槽中添加简短的撤销操作，用于可逆操作。当操作必须持续可用时，将 isAutoHide 设置为 false。
- 使用 uniqueID 去重重复操作触发的 toast，如多次点击保存按钮。
- 对需要关注但不需要立即操作的错误使用 error 类型，它会持续显示直到关闭。
- 避免：不要对阻塞用户的严重错误使用 toast，使用 Banner 进行持久的上下文消息传递。
- 避免：不要在 toast 中放置长内容或多行内容，它会在5秒后消失，用户可能来不及阅读。
- 避免：不要将表单验证错误显示为 toast，使用内联字段验证让用户看到具体哪个字段需要修复。

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-toast",
      "visualProps": [
        "type"
      ]
    }
  ],
  "vars": [
    {
      "name": "--_toast-slide-y",
      "description": "Private block-axis offset inherited from ToastViewport for entry and exit motion",
      "default": "var(--spacing-2)",
      "private": true
    },
    {
      "name": "--_toast-swipe-y",
      "description": "Private active swipe offset along the block axis",
      "default": "0px",
      "private": true
    },
    {
      "name": "--_toast-swipe-exit-y",
      "description": "Private completed-swipe exit offset",
      "default": "var(--_toast-swipe-y)",
      "private": true
    },
    {
      "name": "--_toast-swipe-opacity",
      "description": "Private opacity feedback during an accepted swipe",
      "default": "1",
      "private": true
    },
    {
      "name": "--_toast-swipe-scale",
      "description": "Private scale feedback during an accepted swipe",
      "default": "1",
      "private": true
    }
  ]
}
```

### 组件结构

- **正文**: 描述发生了什么或用户应该知道什么的主要消息文本。
- **尾部内容**: 正文后的尾随操作，如撤销按钮或链接。
- **关闭按钮**: 让用户在自动隐藏前手动关闭 toast 的关闭按钮。

## useToast

Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Works automatically with LayerProvider or self-mounts a fallback viewport.

### Returns

```json
[
  {
    "name": "showToast",
    "type": "(options: ToastOptions) => () => void",
    "description": "Show a toast notification. Returns a dismiss function. Options include body (ReactNode), type (\"info\" | \"error\"), isAutoHide, autoHideDuration, endContent, uniqueID, and collisionBehavior."
  }
]
```

### 使用建议

- Use for transient success/error feedback that does not require user action.
- Set uniqueID to deduplicate toasts from rapid user actions.
- 避免：Use for critical errors that require acknowledgment; use AlertDialog instead.
- 避免：Call useToast in the same component that renders LayerProvider; it must be called from a child component inside the provider.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt