通知提示 · Toast

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

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

API 与上游详细参考

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

Toast

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

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

使用建议

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

主题 API

{
  "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

[
  {
    "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.