toast-example.md 7.21 KB

Raw Blame History Permalink



Toast 工具使用指南


📦 导入

<script setup>
// 根据需要导入对应的函数
import {
  showError,
  showSuccess,
  showInfo,
  showConfirm,
  showLoading,
  hideLoading
} from '@/utils/toast'
</script>


🔧 API 文档


1. showError - 错误提示

显示错误提示，默认显示 3 秒。

参数:


title (string): 提示内容

duration (number, 可选): 显示时长，默认 3000ms


示例:

// 基础用法
showError('操作失败')

// 自定义时长
showError('网络异常，请重试', 2000)

// 在 try-catch 中使用
try {
  await someAPI()
} catch (err) {
  console.error(err)
  showError('请求失败，请重试')
}


2. showSuccess - 成功提示

显示成功提示，默认显示 2 秒。

参数:


title (string): 提示内容

duration (number, 可选): 显示时长，默认 2000ms


示例:

// 基础用法
showSuccess('保存成功')

// 自定义时长
showSuccess('提交成功', 1500)

// 在 API 调用成功后使用
const res = await submitAPI()
if (res.code === 1) {
  showSuccess('提交成功')
}


3. showInfo - 信息提示

显示普通信息提示，默认显示 2 秒。

参数:


title (string): 提示内容

duration (number, 可选): 显示时长，默认 2000ms


示例:

// 基础用法
showInfo('请先登录')
showInfo('请选择日期')
showInfo('请勾选同意须知')


4. showConfirm - 确认对话框

显示确认对话框，用户可以点击确定或取消。

参数:


content (string): 对话框内容

title (string, 可选): 对话框标题，默认 '提示'

options (object, 可选): 其他配置项


confirmText (string): 确认按钮文字，默认 '确定'

cancelText (string): 取消按钮文字，默认 '取消'

showCancel (boolean): 是否显示取消按钮，默认 true


返回: Promise<{ confirm: boolean, cancel: boolean }>

示例:

// 基础用法
const { confirm } = await showConfirm('确定删除吗？')
if (confirm) {
  // 用户点击了确定
  await deleteItem()
}

// 自定义标题
const { confirm } = await showConfirm('确定退出登录吗？', '警告')
if (confirm) {
  await logout()
}

// 自定义按钮文字
const { confirm } = await showConfirm('此操作不可恢复', '警告', {
  confirmText: '删除',
  cancelText: '再想想'
})

// 不显示取消按钮
const { confirm } = await showConfirm('授权失败，请稍后再试', '提示', {
  showCancel: false,
  confirmText: '我知道了'
})


5. showLoading / hideLoading - 加载提示

显示和隐藏加载中提示。

参数:


title (string, 可选): 提示内容，默认 '加载中...'

mask (boolean, 可选): 是否显示透明蒙层，默认 true


示例:

// 基础用法
showLoading('提交中...')
// 操作完成后
hideLoading()

// 自定义提示内容
showLoading('保存中...')
try {
  await saveData()
} finally {
  hideLoading()
}

// 不显示蒙层
showLoading('加载中...', false)


🎯 常见使用场景


场景 1: API 调用

const handleSubmit = async () => {
  showLoading('提交中...')
  try {
    const res = await submitAPI(formData)
    if (res.code === 1) {
      showSuccess('提交成功')
      // 跳转到其他页面
      go('/pages/list/index')
    } else {
      showError(res.msg || '提交失败')
    }
  } catch (err) {
    console.error(err)
    showError('网络异常，请重试')
  } finally {
    hideLoading()
  }
}


场景 2: 表单验证

const validateForm = () => {
  if (!form.value.name) {
    showError('请输入姓名')
    return false
  }

  if (!form.value.idCard) {
    showError('请输入身份证号')
    return false
  }

  if (!/^\d{15}$|^\d{18}$|^\d{17}[\dXx]$/.test(form.value.idCard)) {
    showError('请输入正确的身份证号')
    return false
  }

  return true
}

const submit = () => {
  if (!validateForm()) {
    return
  }

  // 验证通过，提交表单
  doSubmit()
}


场景 3: 删除操作

const handleDelete = async item => {
  const { confirm } = await showConfirm(`确定删除「${item.name}」吗？`)
  if (!confirm) {
    return
  }

  showLoading('删除中...')
  try {
    const res = await deleteAPI({ id: item.id })
    if (res.code === 1) {
      showSuccess('删除成功')
      // 刷新列表
      loadList()
    } else {
      showError(res.msg || '删除失败')
    }
  } catch (err) {
    console.error(err)
    showError('删除出错，请重试')
  } finally {
    hideLoading()
  }
}


场景 4: 权限检查

const checkPermission = async () => {
  try {
    const res = await checkPermissionAPI()
    if (res.code === 1) {
      // 有权限，继续操作
      return true
    } else {
      // 无权限，提示用户
      showError('暂无权限访问此功能')
      return false
    }
  } catch (err) {
    console.error(err)
    showError('权限检查失败')
    return false
  }
}


场景 5: 用户引导

const showFirstTimeGuide = async () => {
  const { confirm } = await showConfirm('首次使用需要完善个人信息', '温馨提示', {
    confirmText: '去完善',
    cancelText: '稍后再说'
  })

  if (confirm) {
    go('/pages/profile/edit')
  }
}


💡 最佳实践


1. 错误提示要具体

// ❌ 不好
showError('操作失败')

// ✅ 好
showError('网络连接失败，请检查网络设置')
showError('身份证号格式不正确')


2. 成功提示要简洁

// ❌ 不好
showSuccess('您的预约已经成功提交，我们会尽快处理，请耐心等待')

// ✅ 好
showSuccess('预约成功')


3. Loading 必须成对出现

// ❌ 不好：忘记 hideLoading
const loadData = async () => {
  showLoading('加载中...')
  const res = await getDataAPI()
  // 缺少 hideLoading()
}

// ✅ 好：使用 try-finally
const loadData = async () => {
  showLoading('加载中...')
  try {
    const res = await getDataAPI()
    // 处理数据
  } finally {
    hideLoading()
  }
}


4. 确认对话框内容要清晰

// ❌ 不好
showConfirm('确定？')

// ✅ 好
showConfirm('确定删除「张三」的预约记录吗？此操作不可恢复')


🔍 类型说明


类型
函数
时长
适用场景


错误
showError
3秒
操作失败、网络异常、验证失败


成功
showSuccess
2秒
操作成功、保存成功


信息
showInfo
2秒
友好提示、操作指引


加载
showLoading
持续显示
等待异步操作完成


确认
showConfirm
等待用户
删除、退出等危险操作


📚 相关文档


Toast 工具源码
Taro.showToast 官方文档
Taro.showModal 官方文档


最后更新: 2026-02-10
维护者: Claude Code