• Vant React

Toast 轻提示

介绍

在页面中间弹出黑色半透明提示,用于消息通知、加载提示、操作结果提示等场景。

函数调用

版本 >= v0.6.0-alpha.0可以直接调用。低版本需要手动在页面(page)里挂载一个 Toast 组件并指定 id 为 toast

import { Cell, Toast } from "@taroify/core"

function ImperativeToast() {
  return (
    <>
      {/* <Toast id="toast" /> */}
      <Cell title="函数调用" clickable isLink onClick={() => Toast.open("文字提示")} />
    </>
  )
}

组件调用

import { Cell, Toast } from "@taroify/core"

function BasicToast() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Toast open={open} onClose={setOpen}>
        文字提示
      </Toast>
      <Cell title="基础用法" clickable onClick={() => setOpen(true)} />
    </>
  )
}

代码演示

加载提示

使用 type="loading" 方法展示加载提示。

Toast.open({ type: "loading", message: "加载中..." })}
<Toast open type="loading">
  加载中...
</Toast>

成功/失败提示

使用 type="success" 展示成功提示,使用 type="fail" 展示失败提示。

Toast.open({ type: "success", message: "成功文案" })
Toast.open({ type: "fail", message: "失败文案" })
<Toast open type="success">成功文案</Toast>
<Toast open type="fail">失败文案</Toast>

自定义图标

通过 icon 选项可以自定义图标,支持传入图标名称或图片链接。

Toast.open({ message: "自定义图标", icon: <LikeOutlined /> })
Toast.open({
  message: "自定义图片",
  icon: (
    <Image
      style={{
        width: "40px",
        height: "40px",
      }}
      src="https://img01.yzcdn.cn/vant/logo.png"
    />
  ),
})
<Toast open icon={<LikeOutlined />}>自定义图标</Toast>
<Toast
  open
  icon={<Image style={{ width: "1em", height: "1em" }}
  src="https://img01.yzcdn.cn/vant/logo.png" />}
>
  自定义图片
</Toast>
<Toast open icon={<Loading />}>加载中...</Toast>

自定义位置

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

Toast.open({
  position: "top",
  message: "顶部展示",
})
Toast.open({
  position: "bottom",
  message: "顶部展示",
})
<Toast open position="top">顶部展示</Toast>
<Toast open position="bottom">底部展示</Toast>

多例模式

Toast 默认采用单例模式,即同一时间只会存在一个 Toast。通过调用 Toast.allowMultiple(true) 可以在页面中同时存在多个 Toast 实例。

import { Cell, Toast } from "@taroify/core"

function MultipleToast() {
  return (
    <>
      <Cell 
        title="允许多个实例" 
        clickable 
        isLink 
        onClick={() => {
          Toast.allowMultiple(true)
          // 同时展示多个 Toast
          Toast.success("成功提示")
          setTimeout(() => {
            Toast.fail("失败提示")
          }, 1000)
        }} 
      />
    </>
  )
}

关闭特定 Toast 实例

在多例模式下,Toast.open()Toast.success()Toast.fail()Toast.loading() 方法会返回一个唯一标识符,可以使用该标识符来关闭特定的 Toast 实例。

import { Cell, Toast } from "@taroify/core"

function MultipleToastClose() {
  return (
    <>
      <Cell 
        title="关闭特定 Toast 实例" 
        clickable 
        isLink 
        onClick={() => {
          // 启用多例模式
          Toast.allowMultiple(true)
          
          // 创建并保存 Toast 实例标识符
          const toast1 = Toast.success("成功提示")
          const toast2 = Toast.loading("加载中...")
          
          // 3秒后只关闭成功提示,保留加载提示
          setTimeout(() => {
            // 直接使用 close 方法关闭特定的 Toast
            if (toast1) {
              Toast.close(toast1)
            }
          }, 3000)
        }} 
      />
    </>
  )
}

API

Props

参数说明类型默认值
defaultOpen默认是否显示弹出层booleanfalse
open是否显示弹出层booleanfalse
type提示类型,可选值为 loading success
fail html
stringtext
icon自定义图标,支持传入图标名称或图片链接ReactNode-
position弹出位置,可选值为 top bottomstringcenter
duration
v0.4.0-alpha.0
动画时长,单位毫秒,值为 0 时,toast 不会消失number | string3000
backdrop是否显示遮罩层booleanfalse
children文本内容ReactNode-
onClose关闭时的回调函数(open : boolean) => void-

Options

参数说明类型默认值
selector自定义节点选择器stringtoast
type提示类型,可选值为 loading success
fail html
stringtext
icon自定义图标,支持传入图标图片ReactNode-
position弹出位置,可选值为 top bottomstringcenter
duration
v0.4.0-alpha.0
动画时长,单位毫秒,值为 0 时,toast 不会消失number | string3000
backdrop是否显示遮罩层booleanfalse
message文本内容ReactNode-
onClose关闭时的回调函数(open : boolean) => void-

方法

方法名参数返回值介绍
Toast.openoptions | messagestring | undefined展示提示,返回 Toast 实例标识符
Toast.loadingoptions | messagestring | undefined展示加载提示,返回 Toast 实例标识符
Toast.successoptions | messagestring | undefined展示成功提示,返回 Toast 实例标识符
Toast.failoptions | messagestring | undefined展示失败提示,返回 Toast 实例标识符
Toast.closeselector? | id?-关闭提示,不传参时关闭所有提示,传入实例标识符时关闭指定提示
Toast.allowMultiple v0.7.0boolean-允许同时存在多个 Toast 提示,默认为 false

主题定制

样式变量

组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件。

名称默认值描述
—toast-width88px * $hd-
—toast-width88px * $hd-
—toast-min-height88px * $hd-
—toast-max-width70%-
—toast-paddingvar(—padding-md)-
—toast-font-sizevar(—font-size-md)-
—toast-line-heightvar(—line-height-md)-
—toast-colorvar(—white)-
—toast-background-colorrgba(var(—black-rgb), $alpha: 0.7)-
—toast-border-radiusvar(—border-radius-lg)-
—toast-transition-durationvar(—animation-duration-fast)-
—toast-icon-font-size36px * $hd-
—toast-icon-colorvar(—white)-
—toast-loading-padding3px * $hd-
—toast-loading-colorvar(—white)-
—toast-text-min-width96px * $hd-
—toast-text-paddingvar(—padding-xs) var(—padding-sm)-
—toast-position-distance20%-
—toast-position-top-distancevar(—toast-position-distance)-
—toast-position-bottom-distancevar(—toast-position-distance)-