API 参考

本文档详细说明 cToast 类的所有公共方法、属性和事件。

目录

• 枚举定义
• 公共方法
  • 链式调用方法
  • 管理方法
• 属性
• 事件

---

枚举定义

EnumPos - 显示位置枚举

Public Enum EnumPos
    LeftTop = 10      ' 左上（堆叠）
    LeftCenter = 12   ' 左中（覆盖）
    LeftBottom = 14   ' 左下（堆叠）
    CenterTop = 20    ' 居上（顺序堆叠）
    Center = 22       ' 居中（覆盖）
    CenterBottom = 24 ' 居下（倒序堆叠）
    RightTop = 30     ' 右上（堆叠）
    RightCenter = 32  ' 右中（覆盖）
    RightBottom = 34  ' 右下（堆叠）
End Enum

说明：

• 堆叠位置：支持多个弹窗依次堆叠显示（LeftTop/LeftBottom/CenterTop/CenterBottom/RightTop/RightBottom）
• 覆盖位置：新弹窗会覆盖旧弹窗（Center/LeftCenter/RightCenter）

---

EnumTheme - 颜色主题枚举

Public Enum EnumTheme
    Light = 1  ' 浅色主题（默认）
    Dark = 2   ' 深色主题
End Enum

说明：

• Light：系统背景色 + 深色文字
• Dark：深灰色背景（RGB(45, 45, 48)） + 浅色文字

---

EnumState - 状态主题枚举

Public Enum EnumState
    Info = 1    ' 信息（蓝色）
    Success = 2 ' 成功（绿色）
    Warning = 3 ' 警告（黄色）
    Danger = 4  ' 危险（红色）
End Enum

颜色值：

• Info：&HC58B36（蓝色）
• Success：&HC000&（绿色）
• Warning：&HC0C0&（黄色）
• Danger：&HC0&（红色）

---

公共方法

链式调用方法

Pos(p As EnumPos) As cToast

设置弹窗显示位置。

参数：

• p - 显示位置枚举值

返回： cToast 对象本身，支持链式调用

示例：

Toast.Pos(RightTop).Show "右上角显示"

注意事项：

• 必须在 Show 之前调用
• 默认值为 Center

---

State(s As EnumState) As cToast

设置弹窗状态主题。

参数：

• s - 状态枚举值（Info/Success/Warning/Danger）

返回： cToast 对象本身，支持链式调用

示例：

Toast.State(Success).Show "操作成功！"

注意事项：

• 必须在 Show 之前调用
• 默认值为 Info

---

Theme(t As EnumTheme) As cToast

设置弹窗颜色主题。

参数：

• t - 主题枚举值（Light/Dark）

返回： cToast 对象本身，支持链式调用

示例：

Toast.Theme(Dark).Show "深色主题提示"

注意事项：

• 必须在 Show 之前调用
• 默认值为 Light

---

InstIndex(i As Long) As cToast

设置堆叠索引，用于手动控制堆叠顺序。

参数：

• i - 堆叠索引（从0开始）

返回： cToast 对象本身，支持链式调用

堆叠规则：

位置类型	堆叠规则	说明
顶部位置（LeftTop/RightTop/CenterTop）	顺序堆叠	i=0 在最上方，依次向下
底部位置（LeftBottom/RightBottom/CenterBottom）	倒序堆叠	i=1 在最下方，依次向上
居中/覆盖位置（Center/LeftCenter/RightCenter）	不支持	调用无效，直接返回

示例：

' 手动指定堆叠位置
Toast.Pos(RightTop).InstIndex(2).Show "第3条消息", 0

' 倒序堆叠（底部）
Toast.Pos(RightBottom).InstIndex(1).Show "最底部消息", 0
Toast.Pos(RightBottom).InstIndex(2).Show "倒数第二条", 0

注意事项：

• 必须在 Pos 之后、Show 之前调用
• 居中/覆盖位置调用无效
• 如果用户未手动调用此方法，系统会自动堆叠

---

Tag(Name As String) As cToast

为弹窗指定标识名称，用于后续管理。

参数：

• Name - 标识名称字符串

返回： cToast 对象本身，支持链式调用

说明：

• 如果不调用此方法，显示时将自动生成8位随机名称
• 相同名称的弹窗不会重复创建，第二次调用会直接退出
• 名称用于 CloseMe、Exists 等方法的参数

示例：

Toast.Tag("msg1").Pos(RightTop).Show "第一条消息", 0
Toast.Tag("msg2").Pos(RightTop).Show "第二条消息", 0

' 单独关闭
Toast.CloseMe "msg1"

注意事项：

• 必须在 Show 之前调用
• 建议使用有意义的名称便于管理

---

Show(Content As String, [Delay As Long = 3000], [Title As String = "提示"]) As cToast

显示弹窗，这是核心方法。

参数：

• Content - 弹窗内容（必填）
• Delay - 延时自动关闭时间，毫秒（可选，默认3000ms，设为0表示持久显示）
• Title - 弹窗标题（可选，默认"提示"）

返回： cToast 对象本身，支持链式调用

自动堆叠管理：

• 如果用户未手动调用 InstIndex，且当前方位集合已有实例，则自动调用 InstIndex(CollX.Count) 实现自动堆叠

示例：

' 基础用法
Toast.Show "操作成功", 3000, "提示"

' 链式调用
Toast.Pos(Center).State(Success).Show "保存成功", 2000

' 持久显示（不自动关闭）
Toast.Tag("notification").Pos(RightBottom).Show "重要通知", 0

' 空标题（不显示标题）
Toast.Show "无标题提示", 3000, ""

注意事项：

• Delay 参数在 FToastCenter 中是必填的，在 cToast 中有默认值3000
• Delay = 0 表示持久显示，不会自动关闭
• 每次调用 Show 后，m_State、m_Theme、m_Index、m_Tag 会重置为默认值，但 m_Pos 会保留

---

管理方法

CloseMe(Name As String) As Boolean

关闭指定名称的弹窗。

参数：

• Name - 要关闭的弹窗名称

返回： 成功返回 True，失败返回 False

说明：

• 遍历所有9个方位集合查找指定名称的弹窗
• 找到后调用窗体的 CloseMe 方法并从集合中移除
• 触发 OnToastCountChange 事件

示例：

Dim result As Boolean
result = Toast.CloseMe("msg1")
If result Then
    Debug.Print "弹窗已关闭"
Else
    Debug.Print "弹窗不存在或已关闭"
End If

注意事项：

• 如果弹窗已经自动关闭（Timer到期），返回 False
• 如果弹窗不存在，返回 False

---

CloseAll() As Boolean

关闭所有当前弹窗。

返回： 成功返回 True

说明：

• 遍历所有9个方位集合，逐个关闭所有弹窗
• 清空所有集合
• 触发一次 OnCloseAll 事件（而不是多次 OnToastCountChange）

示例：

' 关闭所有弹窗
Toast.CloseAll

' 检查关闭数量
If Toast.CloseAll Then
    Debug.Print "所有弹窗已关闭"
End If

注意事项：

• 如果没有弹窗，也会返回 True
• 会触发 OnCloseAll 事件，参数为关闭前的弹窗数量

---

Exists(Name As String) As Boolean

检查指定名称的弹窗是否存在。

参数：

• Name - 要检查的弹窗名称

返回： 存在返回 True，否则返回 False

说明：

• 遍历所有9个方位集合查找指定名称的弹窗
• 用于判断弹窗是否还在显示

示例：

If Toast.Exists("msg1") Then
    Debug.Print "弹窗正在显示"
Else
    Debug.Print "弹窗不存在或已关闭"
End If

' 重复创建检查
If Not Toast.Exists("msg1") Then
    Toast.Tag("msg1").Pos(RightTop).Show "新消息", 0
End If

注意事项：

• 如果弹窗自动关闭（Timer到期），返回 False
• 此方法不会触发任何事件

---

属性

Count As Long（只读属性）

返回所有活动弹窗的总数（9个方位集合的合计）。

返回值： 当前活动弹窗数量

说明：

• 统计所有9个方位集合的实例数量总和
• 实时反映当前显示的弹窗数量

示例：

Debug.Print "当前活动弹窗数量: " & Toast.Count

' 检查是否还有弹窗
If Toast.Count > 0 Then
    Debug.Print "还有 " & Toast.Count & " 个弹窗未关闭"
End If

---

ActiveKeys As Collection（只读属性）

返回包含所有活动弹窗名称（TagName）的集合。

返回值： 包含所有 TagName 的 Collection 对象

说明：

• 返回的集合可用于遍历或显示列表
• 集合中的元素类型为 String，即每个弹窗的 TagName
• 集合内容是只读的，不应直接修改

示例：

Dim Keys As Collection
Dim Key As Variant

Set Keys = Toast.ActiveKeys

' 遍历所有弹窗
For Each Key In Keys
    Debug.Print "活动弹窗: " & Key
Next Key

' 获取弹窗数量
Debug.Print "活动弹窗数: " & Keys.Count

' 添加到列表框
lstToasts.Clear
For Each Key In Keys
    lstToasts.AddItem CStr(Key)
Next Key

注意事项：

• 集合元素是 TagName，不是弹窗对象本身
• 如果弹窗被关闭，集合会自动更新

---

事件

OnToastCountChange 事件

当单个弹窗数量发生变化时触发（新增或删除）。

事件签名：

Public Event OnToastCountChange(ByVal TagName As String, ByVal IsDelete As Boolean, ByVal CurrentCount As Long)

参数：

• TagName - 变化的弹窗名称
• IsDelete - True 表示弹窗被删除，False 表示新增
• CurrentCount - 当前活动弹窗总数

触发时机：

• 调用 Show 创建新弹窗时
• 调用 CloseMe 关闭弹窗时
• 窗体自然关闭（Timer到期）时
• 窗体卸载时

不触发时机：

• 调用 CloseAll 时（触发 OnCloseAll 事件）

使用示例：

Private WithEvents Toast As cToast

Private Sub Form_Load()
    Set Toast = New cToast
End Sub

Private Sub Toast_OnToastCountChange(ByVal TagName As String, ByVal IsDelete As Boolean, ByVal CurrentCount As Long)
    ' 更新UI显示
    lblCount.Caption = "当前活动弹窗: " & CurrentCount
    
    ' 记录日志
    If IsDelete Then
        Debug.Print "弹窗 [" & TagName & "] 已关闭"
    Else
        Debug.Print "弹窗 [" & TagName & "] 已创建"
    End If
    
    ' 刷新列表
    RefreshList
End Sub

注意事项：

• 需要使用 WithEvents 声明变量
• 每次单个弹窗创建或关闭都会触发
• 不适用于批量操作（如 CloseAll）

---

OnCloseAll 事件

当调用 CloseAll() 批量关闭所有弹窗后触发（只触发一次）。

事件签名：

Public Event OnCloseAll(ByVal ClosedCount As Long)

参数：

• ClosedCount - 本次批量关闭的弹窗数量

触发时机：

• 调用 CloseAll() 方法后
• 类的 Class_Terminate 时调用 CloseAll

不触发时机：

• 调用 CloseMe 单独关闭弹窗时
• 窗体自然关闭时

使用示例：

Private WithEvents Toast As cToast

Private Sub Form_Load()
    Set Toast = New cToast
End Sub

Private Sub btnCloseAll_Click()
    Toast.CloseAll
End Sub

Private Sub Toast_OnCloseAll(ByVal ClosedCount As Long)
    ' 批量关闭完成后刷新UI（只触发一次）
    RefreshList
    
    ' 显示提示
    MsgBox "已关闭 " & ClosedCount & " 个弹窗", vbInformation
    
    ' 记录日志
    Debug.Print "批量关闭了 " & ClosedCount & " 个弹窗"
End Sub

注意事项：

• 需要使用 WithEvents 声明变量
• 只触发一次，不会为每个弹窗触发 OnToastCountChange
• 如果没有弹窗，也会触发，参数为0

---

事件对比

事件	触发时机	触发频率	使用场景
OnToastCountChange	单个弹窗新增/删除	每次变化一次	实时更新UI状态
OnCloseAll	CloseAll() 完成后	批量操作一次	批量操作后一次性刷新

---

方法调用顺序建议

创建弹窗的推荐顺序

1. 创建 cToast 实例
   Set Toast = New cToast

2. 设置位置（可选，默认 Center）
   Toast.Pos(RightTop)

3. 设置状态（可选，默认 Info）
   Toast.State(Success)

4. 设置主题（可选，默认 Light）
   Toast.Theme(Dark)

5. 设置标签（可选，自动生成随机名）
   Toast.Tag("msg1")

6. 设置堆叠索引（可选，自动堆叠）
   Toast.InstIndex(0)

7. 显示弹窗
   Toast.Show "消息内容", 3000, "标题"

简化写法（链式调用）

With New cToast
    .Pos(RightTop).State(Success).Theme(Dark).Tag("msg1").InstIndex(0).Show "消息", 3000
End With

更简洁的写法（使用默认值）

With New cToast
    .Show "消息"
End With

---

错误处理

cToast 类本身不会抛出异常，但以下情况需要注意：

1. 重复的 TagName：不会报错，但第二次调用不会创建新弹窗
2. 不存在的弹窗：CloseMe 和 Exists 返回 False，不会报错
3. 无效的 InstIndex：居中/覆盖位置调用无效，但不会报错
4. 空的 Content：允许，但显示为空提示

---

相关方法索引

按功能分类

显示控制：

• Show - 显示弹窗
• CloseMe - 关闭指定弹窗
• CloseAll - 关闭所有弹窗

外观设置：

• Pos - 设置位置
• State - 设置状态
• Theme - 设置主题

高级设置：

• InstIndex - 设置堆叠索引
• Tag - 设置标签

查询统计：

• Exists - 检查弹窗是否存在
• Count - 获取弹窗总数
• ActiveKeys - 获取所有弹窗名称

事件：

• OnToastCountChange - 数量变化事件
• OnCloseAll - 批量关闭事件