UE5 - UC++中容器类的使用详解2（TMap）

作者：hangge | 2026-11-03 08:40

TMap<K，V> 是一个保存映射关系的容器，它的元素是键值对，每个键值对里又有键（Key）和值（Value）两个子元素。在 TMap 中，键不能重复，但是值没有这个限制。下面通过样例演示在 UC++ 中，TMap<K，V> 的使用。

二、TMap 的使用

1，准备工作（创建元素的类型）

（1）我们将会创建一个继承于 UObject 的类来作为容器的元素类型。打开 VS，在 Solution Explorer 中，找到 Source 文件夹，在空白处右击，在弹出的菜单中选择“Add”→“New tem”来增加一个文件。在弹出的面板中，选择“HeaderFile（头文件)”，然后将文件命名为“MyArrayElement.h”。通过窗口底部的 Location 选项，选择所在目录下的“Source\项目名”目录，比如我这里就是“Source\demo3”。

（2）然后在 MyArrayElement.h 文件中输入如下代码，由于这个类完全是作为测试用的，没有任何静态变量或者成员函数，所以不创建对应的 CPP 源文件也行。

#pragma once

#include "CoreMinimal.h"
#include "MyArrayElement.generated.h"

UCLASS()
class UMyArrayElement : public UObject
{
	GENERATED_BODY()
};

2，TMap 的创建

创建 TMap 的时候需要指定 Key 和 Value 的类型，比如下面代码我们创建一个 Key 类型是 int32，Value 类型是 UMyArrayElement 指针类型的 TMap。

TMap<int32, UMyArrayElement*> MyMap;

3，添加键值对

（1）我们可以使用 TMap 的 Add() 函数来添加键值对。调用 Add() 函数的时候需要两个参数，分别是 Key 和 Value 的值。

（2）下面代码我们向 MyMap 中添加 Key 为 1，Value 为 UMyArrayElement 实例的键值对。

UMyArrayElement* Element = NewObject<UMyArrayElement>(this);
MyMap.Add(1, Element);

4，获取键值对

（1）我们可以使用 [] 符号来获取键值对中的 Value。当比较保险的做法是：

在访问健值对之前，保险的做法是先调用 Contains() 函数来判断键值对存不存在。Contains 函数授一个参数作为要查询的 Key，它会检查 TMap 中是否存在 Key 对应的键值对。
如果存在某个键值对，那么我们就可以使用符号来获取这个键值对。

（2）下面是一个具体的样例代码：

int32 Key = 1; 
if (MyMap.Contains(Key))
{
	UMyArrayElement* Element = MyMap[Key];
}

5，TMap 的遍历

（1）我们可以通过 GetKeys() 函数来获得 TMap 中的所有 Key。获得之后可以使用 for 循环来遍历它们。

TArray<int32> Keys;
MyMap.GetKeys(Keys);

for (int32 Key : Keys)
{
	// ...
}

（2）如果想要遍历所有键值对，则可以使用 for-each 来遍历 TMap。

for-each 的元素对象类型根据 Key 和 Value 的不同类型会有所不同，所以一般我们会用 C++11 的 auto 关键字来表示这个类型，并将键值对叫作“KVP”(也就是 Key-valuePair）。
KVP 中会有两个成员变量，一个是 Key，表示键值对中的键；一个是 Value，表示键值对中的值。

for (auto& KVP : MyMap) 
{
	int32 Key = KVP.Key;
	UMyArrayElement* Value = KVP.Value;
}

如果我们不想让使用者修改到键值对的内容，那么还可以将代码进行修改，也就是将 KVP 变成 const。

for (const auto& KVP : MyMap)
{
	int32 Key = KVP.Key;
	UMyArrayElement* Value = KVP.Value;
}

6，删除键值对

使用 TMap 的 Remove() 函数可以删除对应的键值对，Remove() 函数接受一个参数，表示要删除键值对的 Key。

int32 Key = 1;
MyMap.Remove(Key);