cCollection 方法参考

📋 方法列表

方法	说明
Add	添加元素（自动覆盖重复 Key）
Remove	删除元素（通过 Key 或 Index）
RemoveAll	清空集合
Update	更新已存在的元素
Exists	检查 Key 是否存在
Count	获取元素数量
KeyByIndex	通过索引获取 Key
Keys	获取所有 Key 数组
Items	获取所有 Value 数组
RenameKey	重命名 Key
SortByKey	按 Key 排序集合
SortByValue	按 Value 排序集合
GetSortedKeys	获取排序后的 Key 数组（不修改集合）
GetSortedValuesByKey	获取排序后的 Value 数组（不修改集合）

---

➕ Add 方法

说明

添加元素到集合。如果提供了 Key 且已存在，则自动删除旧元素后添加新元素（覆盖更新）。

语法

Public Sub Add(ByVal Item As Variant, Optional ByVal Key As String = "")

参数

参数	类型	说明
Item	Variant	要添加的元素（可以是任意类型）
Key	String	可选，元素的键名

使用示例

Dim col As New cCollection

' 添加不带 Key 的元素
col.Add "普通元素"

' 添加带 Key 的字符串
col.Add "张三", "user1"

' 添加数字
col.Add 100, "count"

' 添加对象
Dim obj As New MyClass
col.Add obj, "myObject"

' 覆盖已存在的 Key（自动删除旧值）
col.Add "张三-更新", "user1"  ' 自动覆盖

---

➖ Remove 方法

说明

删除指定元素（通过 Key 或 Index）。

语法

Public Sub Remove(ByVal KeyOrIndex As Variant)

参数

参数	类型	说明
KeyOrIndex	Variant	Key（字符串）或 Index（数字，从1开始）

使用示例

' 通过 Key 删除
col.Remove "user1"

' 通过 Index 删除（删除第一个元素）
col.Remove 1

---

🧹 RemoveAll 方法

说明

清空集合，删除所有元素。

语法

Public Sub RemoveAll()

使用示例

' 清空集合
col.RemoveAll
Debug.Print col.Count  ' 输出: 0

---

🔄 Update 方法

说明

更新已存在的元素。如果 Key 不存在，则返回 False。

语法

Public Function Update(ByVal Item As Variant, ByVal Key As String) As Boolean

参数

参数	类型	说明
Item	Variant	新的元素值
Key	String	要更新的 Key

返回值

Boolean - 更新成功返回 True，Key 不存在返回 False

使用示例

' 更新已存在的元素
If col.Update("新值", "user1") Then
    Debug.Print "更新成功"
Else
    Debug.Print "Key 不存在"
End If

---

🔍 Exists 方法

说明

检查指定的 Key 是否存在于集合中。

语法

Public Function Exists(ByVal Key As String, Optional CompareCase As Boolean) As Boolean

参数

参数	类型	说明
Key	String	要检查的 Key
CompareCase	Boolean	可选，是否区分大小写（默认 False）

使用示例

' 默认不区分大小写
col.Add "Value", "Key"
Debug.Print col.Exists("key")      ' True
Debug.Print col.Exists("KEY")      ' True

' 区分大小写
col.Add "Value", "Key"
Debug.Print col.Exists("key", True)   ' False
Debug.Print col.Exists("Key", True)   ' True

---

🔢 Count 方法

说明

获取集合中元素的数量。

语法

Public Function Count() As Long

使用示例

Debug.Print "元素数量: " & col.Count

' 检查是否为空
If col.Count = 0 Then
    Debug.Print "集合为空"
End If

---

🔑 KeyByIndex 方法

说明

通过索引获取对应的 Key。如果索引无效或该元素无 Key，返回空字符串。

语法

Public Function KeyByIndex(ByVal Index As Long) As String

参数

参数	类型	说明
Index	Long	索引（从1开始）

使用示例

' 获取第1个元素的 Key
Dim key As String
key = col.KeyByIndex(1)
If key <> "" Then
    Debug.Print "第1个元素的 Key: " & key
End If

---

📋 Keys 方法

说明

获取包含所有 Key 的字符串数组。无 Key 的元素对应空字符串。

语法

Public Function Keys() As String()

返回值

String() - Key 数组（基于0）

使用示例

Dim keyArray() As String
keyArray = col.Keys()

Dim i As Long
For i = LBound(keyArray) To UBound(keyArray)
    Debug.Print "Key[" & i & "] = " & keyArray(i)
Next i

---

📦 Items 方法

说明

获取包含所有 Value 的 Variant 数组。

语法

Public Function Items() As Variant()

返回值

Variant() - Value 数组（基于0）

使用示例

Dim itemArray() As Variant
itemArray = col.Items()

Dim i As Long
For i = LBound(itemArray) To UBound(itemArray)
    Debug.Print "Value[" & i & "] = " & itemArray(i)
Next i

---

✏️ RenameKey 方法

说明

修改指定 Key 的名称（Dictionary 兼容方法）。

语法

Public Function RenameKey(ByVal OldKey As String, ByVal NewKey As String) As Boolean

参数

参数	类型	说明
OldKey	String	原 Key 名称
NewKey	String	新 Key 名称

返回值

Boolean - 成功返回 True，失败（原 Key 不存在或新 Key 已存在）返回 False

使用示例

' 重命名 Key
If col.RenameKey("oldName", "newName") Then
    Debug.Print "重命名成功"
Else
    Debug.Print "重命名失败（Key 不存在或新 Key 已存在）"
End If

---

🔤 SortByKey 方法

说明

按 Key 的字典序升序排序整个集合（会重新组织集合顺序）。

语法

Public Sub SortByKey()

使用示例

' 添加元素（乱序）
col.Add "Value-C", "Key-C"
col.Add "Value-A", "Key-A"
col.Add "Value-B", "Key-B"

' 按 Key 排序
col.SortByKey

' 现在遍历将按 Key-A, Key-B, Key-C 顺序
Dim key As Variant
For Each key In col.Keys()
    Debug.Print key
Next

---

🔠 SortByValue 方法

说明

按 Value 的字典序升序排序整个集合（Value 应为字符串类型）。

语法

Public Sub SortByValue()

使用示例

' 添加元素
col.Add "Charlie", "C"
col.Add "Alpha", "A"
col.Add "Bravo", "B"

' 按 Value 排序
col.SortByValue

' 现在顺序为: Alpha, Bravo, Charlie

---

📊 GetSortedKeys 方法

说明

获取按 Key 排序后的 Key 数组（不修改原集合）。

语法

Public Function GetSortedKeys() As String()

返回值

String() - 排序后的 Key 数组

使用示例

' 获取排序后的 Keys（不改变原集合顺序）
Dim sortedKeys() As String
sortedKeys = col.GetSortedKeys()

' 使用排序后的 Keys 遍历
Dim i As Long
For i = LBound(sortedKeys) To UBound(sortedKeys)
    Debug.Print sortedKeys(i) & " = " & col(sortedKeys(i))
Next i

---

📈 GetSortedValuesByKey 方法

说明

获取按 Key 排序后的 Value 数组（不修改原集合）。

语法

Public Function GetSortedValuesByKey() As Variant()

返回值

Variant() - 按 Key 排序后的 Value 数组

使用示例

' 获取按 Key 排序后的 Values
Dim sortedValues() As Variant
sortedValues = col.GetSortedValuesByKey()

Dim i As Long
For i = LBound(sortedValues) To UBound(sortedValues)
    Debug.Print "Value[" & i & "] = " & sortedValues(i)
Next i

---

📌 方法使用场景总结

基础增删改查

Dim col As New cCollection

' 添加
col.Add "Value", "Key"

' 检查存在
If col.Exists("Key") Then
    ' 更新
    col.Update("NewValue", "Key")
End If

' 删除
col.Remove "Key"

批量操作

' 清空
col.RemoveAll

' 获取所有 Keys 和 Values
Dim keys() As String
Dim values() As Variant
keys = col.Keys()
values = col.Items()

排序场景

' 需要排序后遍历但不改变原集合
Dim sortedKeys() As String
sortedKeys = col.GetSortedKeys()

Dim i As Long
For i = LBound(sortedKeys) To UBound(sortedKeys)
    ProcessItem sortedKeys(i), col(sortedKeys(i))
Next i

' 直接排序集合（后续遍历都是有序）
col.SortByKey

---

最后更新: 2026-05-17