# useToast

## 使用方法

`useToast` 是一个在页面的任何地方都能随时呼叫的组合式函数，用来向用户弹出一句轻量、会自动消失的文字提示（Toast，又称轻提示），比如「保存成功」或「复制到剪贴板」。

它返回一个调用函数，只要传入提示内容和类型就能触发显示。所有的提示消息都统一保存在底层的全局状态里，所以在任何深层子组件里调用都管用。只需要在应用外层（或根组件）挂载一个 ``，提示就会整整齐齐地呈现在那里。

**什么时候用：**
- 用户完成某个操作后，给出短暂且不打扰人的成功反馈（如“更新成功”、“已发送”）。
- 轻微且不致命的操作错误提示。

**什么时候不要用：**
- 如果是不可逆的危险操作（如永久删除数据）或者需要用户仔细确认的报错，严禁使用 Toast，必须改用会锁屏确认的 [AlertDialog](/components/alert-dialog)。
- 如果提示需要用户驻足阅读并点击多个按钮处理，请改用对话框 [Dialog](/components/dialog) 或顶部常驻横幅。

```ts
import { useToast } from '@astryx-vue/core/Toast'
```

```vue
<script setup lang="ts">
import { ToastViewport, useToast } from '@astryx-vue/core/Toast'

const toast = useToast()
</script>

<template>
  <button type="button" @click="toast({ body: '文档已保存', type: 'success' })">
    弹出提示
  </button>
  <ToastViewport />
</template>
```

## 建议

| 指引 | 做法 |
| --- | --- |
| 推荐 | 用在不需要用户操作的短暂反馈上，例如成功和失败提示。 |
| 推荐 | 用户连点会重复弹的时候，用 `uniqueID` 去重。 |
| 推荐 | 在应用根部渲染一次 `ToastViewport`，让所有提示都有地方出现。 |
| 避免 | 需要用户确认的严重错误别用它；用 `AlertDialog`。 |

## 示例

常见配置、变体和状态。

### useToast — 弹出提示

用 useToast 主动弹出轻提示，由 toast 视口负责渲染。

```vue
<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { ToastViewport, useToast } from '@astryx-vue/core/Toast'

const toast = useToast()

function showToast(): void {
  toast({ body: 'Document saved successfully', type: 'success' })
}
</script>

<template>
  <div class="toast-preview__row">
    <Button label="Show toast" variant="secondary" @click="showToast" />
    <ToastViewport />
  </div>
</template>
```

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `show` | `(options: ToastOptions) => () => void` | 弹出一条提示。返回的函数用来关掉这一条。hook 本身可以直接调用，所以 `toast({ body })` 和 `toast.show({ body })` 是一回事。 |
| `dismiss` | `(id: string) => void` | 按 id 关掉一条提示。它挂在返回的函数上：`toast.dismiss(id)`。 |
| `clear` | `() => void` | 关掉当前所有提示，写作 `toast.clear()`。 |

## 提示配置

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `body` | `string` | — | 提示正文。必填。 |
| `type` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | 提示的类型，决定配色和图标。 |
| `isAutoHide` | `boolean` | `true` | 是否自动消失。`error` 类型的提示默认留着，等人关掉。 |
| `autoHideDuration` | `number` | `5000` | 自动消失前停留的毫秒数。 |
| `uniqueID` | `string` | — | 同一个身份的多条提示会合并成一条。 |
| `collisionBehavior` | `'ignore' \| 'overwrite'` | `'overwrite'` | `uniqueID` 撞上时怎么处理。 |
| `endContent` | `Component` | — | 正文后面的操作，例如「撤销」按钮。 |
| `onDismiss` | `(reason: 'auto' \| 'manual') => void` | — | 提示卡片自己关掉时调用：计时到了、点了关闭按钮、或者划走。 |
| `onHide` | `(reason: 'auto' \| 'manual') => void` | — | 提示被移除时调用，不管是哪种关闭方式。 |