$toast 提示

Hidden Title

基础用法：$toast('保存成功')

基础用法

通常用法

说明

$toast 用于触发 Element Plus 的全局消息提示，适合保存成功、接口失败、普通反馈等场景。它在 ElMessage 的基础上增加了类型简写、默认样式和可选的关闭全部旧消息能力。

应用入口可通过 configureUtils({ theme: 'shijingshan' }) 设置全局默认主题。单次调用的 theme 会覆盖全局配置。

调用形式

$toast(message)
$toast(message, type)
$toast(message, type, options)
$toast(options)
$toast.success(message, options)
$toast.info(message, options)
$toast.error(message, options)
$toast.warning(message, options)

$toast(message)
$toast(message, type)
$toast(message, type, options)
$toast(options)
$toast.success(message, options)
$toast.info(message, options)
$toast.error(message, options)
$toast.warning(message, options)

参数说明

参数	类型	必填	默认值	说明
`message`	`string \| VNode \| () => VNode \| ToastOptions`	是	-	提示内容。传对象时会被当成完整的 Element Plus `MessageOptions` 使用。
`type`	`'success' \| 'info' \| 'error' \| 'warning' \| 's' \| 'i' \| 'e' \| 'w' \| ToastOptions`	否	`'success'`	提示类型。`s/i/e/w` 分别是 `success/info/error/warning` 的简写；传对象时表示第二参数直接作为配置项。
`otherParams`	`ToastOptions`	否	`{}`	额外配置，会透传给 `ElMessage`。

ToastOptions 在 Element Plus MessageOptions 基础上额外支持：

字段	类型	默认值	说明
`theme`	`'default' \| 'chenghua' \| 'shijingshan'`	全局主题或 `default`	消息主题；单次设置会覆盖 `configureUtils` 的全局主题。
`closeAll`	`boolean`	`false`	显示当前消息前是否先关闭页面上已有的全部消息。
`customClass`	`string`	`'s-antd-message'`	自定义消息类名。传 `'el'` 时使用 Element Plus 原生样式，不追加默认类名。

返回值

$toast 无返回值，内部直接调用 ElMessage 展示提示。

常用场景

$toast('保存成功')
$toast('删除失败', 'e')
$toast('请检查表单', 'warning', { duration: 5000 })
$toast({ message: '自定义提示', type: 'info', closeAll: true })
$toast.error('接口请求失败', { showClose: true })
$toast({ message: '单次使用成华主题', theme: 'chenghua' })

$toast('保存成功')
$toast('删除失败', 'e')
$toast('请检查表单', 'warning', { duration: 5000 })
$toast({ message: '自定义提示', type: 'info', closeAll: true })
$toast.error('接口请求失败', { showClose: true })
$toast({ message: '单次使用成华主题', theme: 'chenghua' })

注意事项

$toast 依赖 Element Plus 的 ElMessage，需要在浏览器端且项目已正确引入 Element Plus 样式。需要渲染 HTML 字符串时，可通过配置项传 dangerouslyUseHTMLString: true。

函数源码

$toast

来源：packages/utils/src/base.ts

/**
 * @description 显示消息提示。默认展示成功状态，并支持类型简写、完整配置和快捷调用。
 *
 * 支持三种常见写法：
 * 1. `$toast('保存成功')`
 * 2. `$toast('保存失败', 'e')`
 * 3. `$toast({ message: '自定义', type: 'warning' })`
 *
 * @param message 提示内容，支持纯文本、VNode、渲染函数，或完整配置对象。
 * @param type 提示类型，支持 `success/info/error/warning` 和简写 `s/i/e/w`，也支持直接传配置对象。
 * @param otherParams 额外配置，例如 `duration`、`customClass`、`closeAll`。
 * @returns 无返回值。
 *
 * @example
 * ```ts
 * import { $toast } from '@sybz-components/utils'
 *
 * $toast('保存成功')
 * $toast('保存失败', 'e')
 * $toast({
 *   message: '自定义提示',
 *   type: 'warning',
 *   duration: 1000,
 *   closeAll: true,
 * })
 * $toast.error('接口请求失败', { showClose: true })
 * ```
 *
 * @see {@link https://liulihao88.github.io/sybz-components/components/utils/$toast/home.html 详细文档}
 */
export function $toast(
  message: string | ToastOptions | VNode | (() => VNode),
  type: ToastType | ToastOptions = 'success',
  otherParams: ToastOptions = {},
): void {
  const typeMap: Record<ShortType, MessageType> = {
    s: 'success',
    i: 'info',
    e: 'error',
    w: 'warning',
  }

  function isShortType(t: any): t is ShortType {
    return ['s', 'i', 'e', 'w'].includes(t)
  }

  function isToastOptions(obj: any): obj is ToastOptions {
    return typeof obj === 'object' && obj !== null
  }

  function showToast(options: ToastOptions) {
    const { theme = utilsConfig.theme, customClass, ...messageOptions } = options

    if (options.closeAll) {
      ElMessage.closeAll()
    }

    const resolvedCustomClass =
      customClass === 'el'
        ? ''
        : _mergeClassNames('s-antd-message', theme !== 'default' && `s-antd-message--${theme}`, customClass)

    ElMessage({
      ...messageOptions,
      customClass: resolvedCustomClass,
    })
  }

  // Case 1: message is options object
  if (isToastOptions(message)) {
    showToast(message)
    return
  }

  // Case 2: type is options object
  if (isToastOptions(type)) {
    showToast({
      message,
      type: 'success',
      ...type,
    })
    return
  }

  // Case 3: regular message with type and options
  const resolvedType = isShortType(type) ? typeMap[type] : type

  showToast({
    message,
    type: resolvedType,
    ...otherParams,
  })
}

/**
 * `$toast.success(...)` 的快捷调用。
 */
$toast.success = (message: string | ToastOptions | VNode | (() => VNode), otherParams: ToastOptions = {}) =>
  $toast(message, 'success', otherParams)
/**
 * `$toast.info(...)` 的快捷调用。
 */
$toast.info = (message: string | ToastOptions | VNode | (() => VNode), otherParams: ToastOptions = {}) =>
  $toast(message, 'info', otherParams)
/**
 * `$toast.error(...)` 的快捷调用。
 */
$toast.error = (message: string | ToastOptions | VNode | (() => VNode), otherParams: ToastOptions = {}) =>
  $toast(message, 'error', otherParams)
/**
 * `$toast.warning(...)` 的快捷调用。
 */
$toast.warning = (message: string | ToastOptions | VNode | (() => VNode), otherParams: ToastOptions = {}) =>
  $toast(message, 'warning', otherParams)

$toast 提示 ​

Hidden Title ​

基础用法 ​

通常用法 ​

说明 ​

调用形式 ​

参数说明 ​

返回值 ​

常用场景 ​

注意事项 ​