Toast 轻提示
Toast 根容器负责 placement、stack 和 inset。根容器仍然负责 placement、stack 和 inset， 但单条提示现在可以直接用Toast.Item写出接近 message 的反馈体验：类型、标题、说明、 操作区、关闭按钮、自动关闭与悬停暂停都已经补充；现在还可以像常见 message API 一样通过Toast.useMessage()拿到messageApi和contextHolder， 在业务按钮、异步流程和页面局部容器里直接按 key 推送、更新和销毁消息；默认会弹到全局页面层， 只有显式传 getContainer={false}时才会留在当前 box 里，同时仍然使用 Rue 自己更轻、更靠近页面内容的视觉语气。
何时使用
- 需要在页面局部提供轻量反馈，但不想上升成全局通知系统。
- 希望像 message 一样直接描述成功、失败、加载、警告这些状态，又想保持更贴近 Rue 的视觉风格。
- 希望在事件处理函数里直接触发反馈，而不是先把消息数组提升到页面状态。
- 既要支持基础的 alert 容器写法，也想在业务里直接拿到可关闭、可自动关闭的单条提示能力。
# Message-like items
最直接的语义用法：把内容交给 Toast.Item，根容器继续负责定位和堆叠。
# Variants and actions
soft、outline、solid 三种外观可以调整存在感，action 让单条提示具备 message 之上的轻量操作能力。
# Controlled and auto close
受控关闭适合和外部状态联动；自动关闭则提供了 message 常用的短时反馈体验，并支持 hover 暂停。
# Toast.useMessage
参考常见 message hook 的形态：把 contextHolder 放进页面即可，真正的消息默认弹到全局页面层；如果你要留在当前 box，再显式传 getContainer={false}。
# Compound composition
如果标题、说明和操作区需要更强定制，可以直接使用 compound 子组件自己拼装。
支持基础写法
基础的“Toast 只做容器、里面继续放 alert 或自定义节点”的使用方式完整提供。下面这些基础示例 都还在，只是按新的能力层次重新归组了。
# Toast with alert inside
展示基础示例，Toast 本体只包一层定位容器，内部内容完全由你决定。
# Toast placements
placement 九宫格别名和 horizontal / vertical 支持层仍然都可用，基础布局 API 不需要额外改造。
# Stacked toasts
基础的多条堆叠示例展示，同时和横向、倒序这些布局控制一起展示。
# Inset and layer control
inset 负责把提示从边缘收进来，zIndex 用于压过页面中的局部浮层，适合嵌入 mock 页面或设计稿容器。
# Custom host element
需要语义容器时，可以把根节点改成 section，并直接挂上 status / aria-live 之类的可访问性语义。
API
Toast.useMessage(options)
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
placement / inset / gap / zIndex | 复用 Toast 根容器的定位能力；默认消息层会挂到全局页面层，而不是被当前 box 裁住。 | ToastProps 子集 | placement = 'top' |
getContainer | 控制消息挂载位置；默认挂到 document.body，传 false 时退回到 contextHolder 所在的局部 box。 | string | HTMLElement | (() => HTMLElement) | false | document.body |
maxCount | 限制同时显示的消息数量；超过时会自动挤掉最早的一条。 | number | - |
duration | 给 hook 创建出来的消息设定默认自动关闭时长，单条消息可覆盖。 | number | null | 3 |
variant / closable / pauseOnHover / showIcon / type | 为整个 message 通道设定单条提示的默认外观和行为。 | ToastItemProps 子集 | - |
返回值固定为[messageApi, contextHolder]。为了保持这类 hook 的用法习惯，contextHolder仍然建议真实渲染到页面里；默认情况下它主要跟随当前组件生命周期，真正的消息层会挂到document.body，传getContainer={false}时才会回到 holder 内。
messageApi
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
open(config) | 创建一条消息；返回关闭函数，适合临时保存句柄。 | (config: ToastMessageConfig) => () => void | - |
success / info / warning / error | 带语义类型的快捷方法，等价于 open({ type, ...config })。 | (config) => () => void | - |
loading(config) | 加载态快捷方法，默认会把 duration 设为 0，便于后续按 key 更新。 | (config) => () => void | - |
destroy(key?) | 销毁指定 key 的消息；不传 key 时清空当前 holder 里的全部消息。 | (key?: string | number) => void | - |
ToastMessageConfig
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
key | 稳定标识；重复调用同一个 key 时会原位更新，而不是追加新消息。 | string | number | 自动生成 |
content | message 风格的主内容；未传 children 时会直接渲染在正文区域。 | any | - |
children | 需要 richer JSX 时可直接传 children，优先级高于 content。 | any | - |
其余字段 | type、duration、action、closable、variant、icon、onClose 等字段复用 Toast.Item。 | ToastItemProps 子集 | - |
Toast 根容器
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
as | 指定根节点标签，例如 div、section | any | 'div' |
gap | 控制多个 toast 项之间的间距，支持数字和任意 CSS 长度 | number | string | - |
horizontal | 横向位置；传入后会覆盖 placement 推导出的横轴结果 | 'start' | 'center' | 'end' | - |
inset | 容器内边距，可统一设置，也可通过 x / y 分别控制横向与纵向留白 | number | string | { x?: number | string; y?: number | string } | - |
placement | 语义化九宫格定位别名，例如 top-end、center、bottom-start | 'top-start' | 'top' | 'top-center' | 'top-end' | 'middle-start' | 'middle' | 'middle-center' | 'middle-end' | 'bottom-start' | 'bottom' | 'bottom-center' | 'bottom-end' | 'start' | 'center' | 'end' | - |
reverse | 反转容器内子项顺序，适合最新消息置顶或横向倒序布局 | boolean | false |
stack | 堆叠方向，默认维持竖向通知流，也可以切到横向条带式布局 | 'vertical' | 'horizontal' | 'vertical' |
vertical | 纵向位置；传入后会覆盖 placement 推导出的纵轴结果 | 'top' | 'middle' | 'bottom' | - |
zIndex | 调整容器层级，适合叠放在抽屉、卡片或 mock 页面之上 | number | string | - |
Toast.Item 单条提示
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
action | 右侧操作区，可放按钮、链接或状态标签 | any | - |
as | 单条提示的根节点标签，默认 div | any | 'div' |
closable | 显示内建关闭按钮，并在点击时触发 onClose / onOpenChange | boolean | false |
closeIcon | 自定义关闭按钮图标 | any | - |
defaultOpen | 非受控初始显示状态 | boolean | true |
description | 说明文案，适合放补充上下文或后续动作提示 | any | - |
duration | 自动关闭时长，单位秒；传入 0 或 null 时保持常驻 | number | null | - |
icon | 自定义图标；未传时会根据 type 渲染默认图标 | any | - |
onClose | 关闭完成时触发，meta.source 会标记 close 或 timeout | (meta) => void | - |
onOpenChange | 显示状态变化回调，适合受控关闭或外部同步状态 | (open, meta) => void | - |
open | 受控显示状态 | boolean | - |
pauseOnHover | 自动关闭时鼠标移入是否暂停剩余计时 | boolean | true |
showIcon | 关闭默认图标渲染，只保持文字和操作区 | boolean | true |
title | 标题文案，适合放主状态结论 | any | - |
type | 语义类型，会同时影响默认图标、无障碍语义和视觉配色 | 'neutral' | 'info' | 'success' | 'warning' | 'error' | 'loading' | 'neutral' |
variant | 提示外观风格，适合在页面层级里调节存在感 | 'soft' | 'solid' | 'outline' | 'soft' |
Compound 子组件包括Toast.Icon、Toast.Content、Toast.Title、Toast.Description、Toast.Action和 Toast.Close。