sard-uniapp/components/toast/README.md

sard-uniapp 是一套基于 Uniapp + Vue3 框架开发的兼容多端的 UI 组件库

---
title: Toast
subtitle: 轻提示
group: 反馈组件
---

## 介绍

在页面中间弹出黑色半透明提示，表示提示、结果、加载中状态。

## 引入

```js
import Toast from 'sard-uniapp/components/toast/toast.vue'
import ToastAgent from 'sard-uniapp/components/toast-agent/toast-agent.vue'
import { toast } from 'sard-uniapp'
```

## 代码演示

### 基础使用

先在页面放置代理组件。

```tsx
<sar-toast-agent />
```

接着便可以使用 `toast` 等方法显示提示。

<<< @demo/toast/demo/Basic.vue

### 自定义位置

`Toast` 默认渲染在屏幕正中位置，通过 `position` 属性可以控制提示展示的位置。

<<< @demo/toast/demo/Placement.vue

### 加载中的背景

默认显示加载类型的提示不会显示遮罩背景，设置 `overlay: true` 会显示黑色遮罩， 设置 `transparent: true` 会让背景变透明。

<<< @demo/toast/demo/Mask.vue

### 自定义图标 <sup>1.30.3+</sup>

可以使用 `icon` 插槽或者 `icon` 和 `icon-family` 属性自定义图标。

<<< @demo/toast/demo/Icon.vue

### 插槽 <sup>1.30.3+</sup>

可以使用 `toast` 组件的插槽自定义内容，如果喜欢命令式来使用 `toast` 组件，可以使用 `toast-agent` 组件 + `toast` 函数，只要给 `toast-agent` 组件设置对应的 `id`，在调用 `toast` 函数时传入相同的 `id`，就可以使用对应的 `toast-agent` 组件的插槽内容了。

<<< @demo/toast/demo/Slot.vue

## API

### ToastProps

| 属性                           | 描述                     | 类型                                       | 默认值   |
| ------------------------------ | ------------------------ | ------------------------------------------ | -------- |
| type                           | 提示框类型               | 'text' \| 'loading' \| 'success' \| 'fail' | 'text'   |
| title                          | 标题                     | string \| number                           | -        |
| icon <sup>1.30.3+</sup>        | 图标名称                 | string                                     | -        |
| icon-family <sup>1.30.3+</sup> | 图标字体名称             | string                                     | -        |
| visible                        | 是否可见                 | boolean                                    | -        |
| position                       | 提示框垂直方向放置的位置 | 'top' \| 'center' \| 'bottom'              | 'center' |
| overlay                        | 是否显示背景遮罩         | boolean                                    | false    |
| transparent                    | 使背景透明               | boolean                                    | false    |
| timeout                        | 提示的延迟时间，单位 ms  | number                                     | 1500     |
| duration                       | 显隐动画时长，单位 ms    | number                                     | 300      |

### ToastSlots <sup>1.30.3+</sup>

| 插槽    | 描述           | 属性 |
| ------- | -------------- | ---- |
| default | 自定义默认内容 | -    |
| icon    | 自定义图标     | -    |

### ToastEmits

| 事件                               | 描述                        | 类型                                 |
| ---------------------------------- | --------------------------- | ------------------------------------ |
| update:visible                     | 提示框显隐时触发            | `(visible: boolean) => void`         |
| visible-hook <sup>1.20.2+</sup>    | 入场/退场动画状态改变时触发 | `(name: TransitionHookName) => void` |
| before-enter <sup>1.20.2+</sup>    | 入场动画开始前触发          | `() => void`                         |
| enter <sup>1.20.2+</sup>           | 入场动画开始时触发          | `() => void`                         |
| after-enter <sup>1.20.2+</sup>     | 入场动画结束时触发          | `() => void`                         |
| enter-cancelled <sup>1.20.2+</sup> | 入场动画取消时触发          | `() => void`                         |
| before-leave <sup>1.20.2+</sup>    | 退场动画开始前触发          | `() => void`                         |
| leave <sup>1.20.2+</sup>           | 退场动画开始时触发          | `() => void`                         |
| after-leave <sup>1.20.2+</sup>     | 退场动画结束时触发          | `() => void`                         |
| leave-cancelled <sup>1.20.2+</sup> | 退场动画取消时触发          | `() => void`                         |

### ToastAgentProps / ToastOptions

继承 [`ToastProps`](#ToastProps) 并有以下额外属性。

| 属性                                | 描述                        | 类型                                 | 默认值  |
| ----------------------------------- | --------------------------- | ------------------------------------ | ------- |
| id                                  | 提示组件的 id               | string                               | 'toast' |
| onVisibleHook <sup>1.20.2+</sup>    | 入场/退场动画状态改变时调用 | `(name: TransitionHookName) => void` |
| onBeforeEnter <sup>1.20.2+</sup>    | 入场动画开始前调用          | `() => void`                         |
| onEnter <sup>1.20.2+</sup>          | 入场动画开始时调用          | `() => void`                         |
| onAfterEnter <sup>1.20.2+</sup>     | 入场动画结束时调用          | `() => void`                         |
| onEnterCancelled <sup>1.20.2+</sup> | 入场动画取消时调用          | `() => void`                         |
| onBeforeLeave <sup>1.20.2+</sup>    | 退场动画开始前调用          | `() => void`                         |
| onLeave <sup>1.20.2+</sup>          | 退场动画开始时调用          | `() => void`                         |
| onAfterLeave <sup>1.20.2+</sup>     | 退场动画结束时调用          | `() => void`                         |
| onLeaveCancelled <sup>1.20.2+</sup> | 退场动画取消时调用          | `() => void`                         |

### ToastAgentSlots <sup>1.30.3+</sup>

继承 [`ToastSlots`](#ToastSlots)。

### ToastAgentEmits <sup>1.20.2+</sup>

继承 [`ToastEmits`](#ToastEmits)。

### 命令式方法

| 名称          | 描述                       | 类型                     |
| ------------- | -------------------------- | ------------------------ |
| toast         | 显示提示                   | ToastFunction            |
| toast.success | 显示成功类型提示           | ToastSimpleShowFunction  |
| toast.fail    | 显示失败类型提示           | ToastSimpleShowFunction  |
| toast.loading | 显示加载类型提示           | ToastSimpleShowFunction  |
| toast.hide    | 隐藏指定 `id` 的命令式提示 | `(id = 'toast') => void` |
| toast.hideAll | 隐藏所有命令式提示         | `() => void`             |

### ToastFunction

```ts
type ToastFunction = ToastSimpleShowFunction & {
  success: ToastSimpleShowFunction
  fail: ToastSimpleShowFunction
  loading: ToastSimpleShowFunction
  hide: (id?: string) => void
  hideAll: () => void
}
```

### ToastSimpleShowFunction

```ts
interface ToastSimpleShowFunction {
  (options: ToastOptions): void
  (title?: string | number, options?: ToastOptions): void
}
```

## 主题定制

### CSS 变量

<<< @comp/toast/variables.scss#variables