GlobalToast 全局提示组件

概述

GlobalToast 是基于 wot-design-uni 的 wd-toast 组件封装的全局提示组件，通过 Pinia 状态管理实现全局调用。

组件特性

基于 wd-toast 组件封装
支持多种提示类型：成功、错误、信息、警告
自动页面路径检测，确保在正确页面显示
支持自定义图标、位置、持续时间等
虚拟节点设计，不在 DOM 中创建额外层级

安装使用

1. 注册全局组件

在 App.vue 或根组件中注册：

<template>
  <div>
    <!-- 其他内容 -->
    <GlobalToast />
  </div>
</template>

2. 在组件中使用

import { useGlobalToast } from '@/composables/useGlobalToast'

const toast = useGlobalToast()

API 文档

基础用法

// 普通提示
toast.show('这是一条提示信息')

// 自定义配置
toast.show({
  msg: '自定义提示',
  duration: 3000,
  position: 'top'
})

快捷方法

success(option)

成功提示，显示绿色成功图标

toast.success('操作成功')
toast.success({
  msg: '保存成功',
  duration: 2000
})

默认配置：
- 图标：success
- 持续时间：1500ms

error(option)

错误提示，显示红色错误图标

toast.error('操作失败')
toast.error({
  msg: '网络错误，请重试',
  duration: 3000
})

默认配置：
- 图标：error
- 方向：vertical（垂直布局）

info(option)

信息提示，显示蓝色信息图标

toast.info('这是一条信息')
toast.info({
  msg: '请注意查看',
  position: 'top'
})

默认配置：
- 图标：info

warning(option)

警告提示，显示黄色警告图标

toast.warning('警告信息')
toast.warning({
  msg: '请谨慎操作',
  iconName: 'warning'
})

默认配置：
- 图标：warning

close()

手动关闭提示

toast.close()

参数说明

ToastOptions

参数	类型	默认值	说明

方法参数

所有方法都支持两种参数类型：

字符串参数：直接传入提示文本
选项对象：传入完整的 ToastOptions 配置

使用示例

基础示例

export default {
  setup() {
    const toast = useGlobalToast()

    const handleSuccess = () => {
      toast.success('操作成功！')
    }

    const handleError = () => {
      toast.error('操作失败，请重试')
    }

    const handleCustom = () => {
      toast.show({
        msg: '自定义提示',
        duration: 5000,
        position: 'top',
        iconName: 'info'
      })
    }

    return {
      handleSuccess,
      handleError,
      handleCustom
    }
  }
}

异步操作示例

async function handleSubmit() {
  const toast = useGlobalToast()

  try {
    // 提交数据
    await submitData()
    toast.success('提交成功')
  }
  catch (error) {
    toast.error(`提交失败：${error.message}`)
  }
}

长文本提示

function showLongMessage() {
  toast.info({
    msg: '这是一条很长的提示信息，可能需要更长的显示时间',
    duration: 4000,
    position: 'top'
  })
}

实现原理

状态管理

使用 Pinia 管理全局状态
状态包含：toastOptions（提示配置）、currentPage（当前页面路径）

页面检测机制

调用提示方法时记录当前页面路径
组件监听状态变化时验证页面路径
确保提示信息在正确的页面显示

组件配置

export default {
  options: {
    virtualHost: true, // 虚拟节点
    addGlobalClass: true, // 支持全局样式
    styleIsolation: 'shared' // 样式隔离共享
  }
}

最佳实践

选择合适的提示类型

成功操作使用 success()
错误信息使用 error()
一般信息使用 info()
警告信息使用 warning()

控制显示时长

简短消息：1500-2000ms
长消息：3000-4000ms
重要消息：可设置为0，用户手动关闭

位置选择

一般提示：middle（默认）
不遮挡内容：top 或 bottom
重要提示：middle + cover

避免频繁调用
```typescript
// ❌ 避免快速连续调用
toast.success('第一条')
toast.success('第二条') // 会覆盖第一条

// ✅ 推荐做法
toast.success('操作完成')
```

注意事项

组件需要在应用根组件中注册才能正常使用
提示会自动在对应页面显示，切换页面时会自动关闭
同时只能显示一个提示，新的提示会覆盖旧的提示
使用 duration: 0 时记得手动调用 close() 关闭