# Toast 轻提示 操作后显示的简短反馈,几秒后自动消失。 ## 基础用法 - 默认 3 秒后消失,带操作时 6 秒;`duration: 0` 则一直保留,直到关闭。 - 指针停在提示上或焦点在其中时,倒计时暂停,离开后按剩余时间继续。 ## 堆叠 同一位置有多条提示时,它们叠在一起:最新的一条在最前面,后面的露出一道边,每往后一层略小一些,最多露出三层。指针移到提示上,或者用 Tab 把焦点移进去,整叠提示会展开成一列;移开后收回。展开期间所有提示都暂停倒计时,不会在阅读时消失。 在触屏上轻点提示即可展开,轻点别处收回。新增、关闭、展开和收起都从各自当前的位置过渡到新位置,动画进行中再次变化也不会跳动;开启减少动态效果后,提示直接换到新位置,只保留淡入淡出。 不需要堆叠时,把 `DouToastViewport` 的 `stacked` 设为 `false`,提示会始终排成一列。可以在安装时设成全局默认值,`toast()` 自动挂载的容器也会沿用: ```ts app.use(DouUI, { defaults: { DouToastViewport: { stacked: false }, }, }) ``` 也可以自己放一个容器: ```vue ``` ## 带操作 `action` 放一个按钮,例如撤销。按下后执行 `onClick` 并关闭提示。 ## 位置 `placement` 可选 `top`(默认)、`top-left`、`top-right`、`bottom`、`bottom-left`、`bottom-right`。同一位置的提示叠在一起(见 [堆叠](#堆叠)),最新的一条离屏幕边缘最近;同一位置最多显示 5 条,更早的先关闭。 ## 关闭 每次调用返回 `{ id, close, update }`。`toast.close(id)` 关闭指定的一条,`toast.closeAll()` 关闭全部。`onClose` 在提示消失后调用,无论它是怎么关闭的。 ```ts const { close } = toast('正在上传…', { duration: 0 }) await upload() close() ``` ## 进行中的任务 `toast.loading()` 显示一条带加载图标的提示,它会一直显示,直到被更新或关闭。用返回的 `update()` 原地改写这条提示,比如从“保存中…”改为“已保存”;改写后加载状态结束,重新按 `duration` 倒计时。 `toast.promise()` 把这一步合在一起:Promise 进行中显示 `loading`,完成后显示 `success` 的内容(`tone` 为 `success`),失败后显示 `error` 的内容(`tone` 为 `danger`)。`success` 与 `error` 也可以是函数,参数是结果或错误。第一个参数可以是 Promise,也可以是返回 Promise 的函数;它返回这个 Promise,调用方仍可以 `await`。 ```ts const { update } = toast.loading('正在上传…') await upload() update({ message: '上传完成', tone: 'success' }) await toast.promise(save(), { loading: '保存中…', success: '已保存', error: (error) => `保存失败:${(error as Error).message}`, }) ``` ## 语言与层级 `toast()` 第一次调用时会自动挂载一个容器。用 `app.use(DouUI)` 或 `provideGlobalConfig(config, app)` 配置时,容器沿用应用的全局配置(语言包、`zIndex`)。 如果要让提示使用某个 [ConfigProvider](./config-provider) 的配置,把 `DouToastViewport` 放进去即可;最后挂载的容器负责显示提示。 ```vue ``` ## 键盘与读屏 每个位置是一个带标签(“通知”)的区域;每条提示带 `role="status"`,警告与错误为 `role="alert"`,读屏会读出新出现的提示。关闭按钮带有语言包里的“关闭”标签。叠在后面的提示仍然可以用 Tab 聚焦,焦点一进入,整叠提示就会展开。 ## API ### toast(message, options?) / toast(options) | 选项 | 说明 | 类型 | 默认值 | | ----------- | ------------------------------------ | ---------------------------------------- | ----------------------- | | `message` | 正文 | `string` | — | | `title` | 正文上方的粗体标题 | `string` | — | | `tone` | 语气 | `Tone` | `'neutral'` | | `duration` | 显示多久,毫秒;`0` 为一直显示 | `number` | `3000`(带操作 `6000`) | | `closable` | 显示关闭按钮 | `boolean` | `false` | | `placement` | 位置 | `ToastPlacement` | `'top'` | | `action` | 一个按钮 | `{ label: string; onClick: () => void }` | — | | `loading` | 显示加载图标,一直显示到被更新或关闭 | `boolean` | `false` | | `onClose` | 消失后调用 | `() => void` | — | ### 其他方法 | 名称 | 说明 | | -------------------------------------------- | ------------------------------------------------------------------- | | `toast.success(...)` | `tone: 'success'` | | `toast.warning(...)` | `tone: 'warning'` | | `toast.danger(...)` | `tone: 'danger'` | | `toast.loading(...)` | `loading: true` | | `toast.promise(promise, messages, options?)` | 随 Promise 的状态显示 `loading`、`success`、`error`,返回该 Promise | | `toast.update(id, input)` | 原地改写一条;`input` 为文字或部分选项 | | `toast.close(id)` | 关闭一条 | | `toast.closeAll()` | 关闭全部 | ### ToastViewport Props | 名称 | 说明 | 类型 | 默认值 | | --------- | ---------------------------------------------------------------- | --------- | ------ | | `max` | 同一位置最多显示几条 | `number` | `5` | | `stacked` | 同一位置的提示叠在一起,悬停或聚焦时展开;`false` 时始终排成一列 | `boolean` | `true` |