反馈类 · Toast
提示
Toast 提示是对用户的操作做出及时反馈,由用户的操作触发,反馈信息可以是操作的结果状态,如成功、失败、出错、警告等。

代码演示

如何引入

普通提示

信息提醒反馈
如果你在请求拦截器等场景中,使用 Toast 来做请求状态结果提示,你可能会在短时间内弹出多个 Toast ,该类场景我们更推荐使用你开启堆叠功能,防止同一时间展示过多元素对用户造成干扰

堆叠样式

可以通过 stack 属性应用堆叠样式到同屏多个 Toast,Hover 展开,该 API在 v2.42.0 后支持

其他提示类型

包括成功、失败、警告

多色样式

可以使用 theme 设置浅色填充样式提高与界面的对比,默认为 'normal' 的白色模式。

链接文本

配合 Typography 可以自定义链接文本,用来配合更复杂的场景的使用。

修改延时

自定义时长 10s,默认时长为 3s

手动关闭

duration 设置为 0 时,toast 不会自动关闭,此时必须通过手动关闭。

更新消息内容

可以通过唯一的 id 来更新内容。

销毁所有

全局销毁 ( >= 0.25.0 ):
  • Toast.destroyAll()

消费 Context

通过 Toast.useToast 创建支持读取 context 的 contextHolder。此时的 toast 会渲染在 contextHolder 所在的节点处。

创建不同配置 Toast

常用于覆盖全局配置
  • ToastFactory.create(config) => Toast
    如果您的应用中需要使用不同 config 的 Toast,可以使用 ToastFactory.create(config)创建新的 Toast (>= 1.23):
全局销毁 ( >= 0.25.0 ):
  • Toast.destroyAll()
消费 Context ( >= 1.2.0 ):
  • Toast.useToast()
    当你需要使用 Context 时,可以通过 Toast.useToast 创建一个 contextHolder 插入相应的节点中。此时通过 hooks 创建的 Toast 将会得到 contextHolder 所在位置的所有上下文。创建的 toast 对象拥有与以下方法:info, success, warning, error, close

API 参考

组件提供的静态方法,使用方式和参数如下:展示:可以直接传入 options 对象或 string
全局配置, 在调用前提前配置,全局一次生效 ( >= 0.25.0 )
  • Toast.config(config)
直接展示 Toast
  • Toast.info(options || string)
  • Toast.error(options || string)
  • Toast.warning(options || string)
  • Toast.success(options || string)
info error warning success 返回值为toastId, 可用于手动关闭
const toastId = Toast.info({ /*...options*/ })
  • Toast.close(toastId) 手动关闭

Options

Toast Options 支持以下 API 及 Config 中的 API
属性说明类型默认值版本
content提示内容ReactNode''
icon自定义图标ReactNode0.25.0
showClose是否展示关闭按钮booleantrue0.25.0
textMaxWidth内容的最大宽度number | string4500.25.0
onClosetoast 关闭的回调函数() => void
stack是否堆叠 Toastbooleanfalse2.42.0
id自定义 ToastIdnumber

Config

以下 API 支持全局配置,用于更改当前 Toast 的默认配置
属性说明类型默认值版本
bottom弹出位置 bottomnumber | string-0.25.0
left弹出位置 leftnumber | string-0.25.0
right弹出位置 rightnumber | string-0.25.0
top弹出位置 topnumber | string-0.25.0
zIndex弹层 z-index 值number1010
theme填充样式,支持 light, normalstringnormal2.54.0
duration自动关闭的延时,单位 s,设为 0 时不自动关闭number3
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 container 和 内部的 .semi-toast-wrapper position: relative, 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。() => HTMLElement | null() => document.body0.34.0

Accessibility

ARIA

  • Toast 的 role 为 alert

文案规范

  • 保持简洁
  • 句尾不使用句号
  • 使用 名词 + 动词 的格式进行说明
✅ 推荐用法❌ 不推荐用法
Language addedNew language has been added successfully
Ticket transfer failedCan't transfer ticket
  • 提供动作的提示消息
    • 只提供一个动作
    • 不使用类似于「已读」类的动作,例如 OK, Got it, Dismiss, Cancel
✅ 推荐用法❌ 不推荐用法

设计变量