UE5 - C++开发快速入门教程5（添加自定义的UE属性：UProperty、UProperty支持的类型）

作者：hangge | 2026-10-19 08:47

对于一个类的组成来说，除了函数之外，另一个重要的部分就是成员变量了。在 UClass 中，成员变量如果想要被 UE5 识别到并纳入 UE5 的管理体系中，须得将它表示为 UProperty，也就是 UE 属性。同样的，想要把成员变量变成 UProperty，必须在成员变量的前一行加上 UPROPERTY() 宏来进行标记。下面我将通过样例演示如何添加 UE 属性。

五、添加自定义的 UE 属性（UProperty）

1，属性说明符

（1）单单使用 UPROPERTY 这个宏而不带任何参数的话，只能是将变量纳入 UE5 管理，在蓝图中还是会访问不到被标记的成员变量。如果想让蓝图能够操作指定的成员变量，可以在 UPROPERTY 宏选择加入下面这两个说明符：

BlueprintReadOnly（蓝图只读），也就是在蓝图中只能够读取这个变量，而不能写入它。具体表现为在节点搜索框中只能找到这个属性的 Get 方法，搜不到 Set 方法。
BlueprintReadWrite（蓝图读写）。使用这个说明符进行标记后，可以在蓝图中自由地读取和写入该变量。

（2）我们在 HelloUE.h 中添加如下代码，创建一个变量“MyValue”，类型为整型 int32。

UPROPERTY(BlueprintReadwrite)
int32 MyValue;

（3）编译代码后打开编辑器，在 BP_HelloUE 中的“事件图表”中，就可以搜索并选中 MyValue 的 Get 和 Set 节点。

（4）上面两个说明符只能够让我们在蓝图中访问到属性，但是如果我们在游戏中选中了实例，想要在细节面板中看到属性的值，还需要用到如下两个说明符：

VisibleAnywhere 被标记的属性能够在细节面板中显示，但是不能被修改。
EditAnywhere 被标记的属性能够在细节面板中显示，并且它的值可以在细节面板中被修改。

（5）我们来试试给 MyValue 加上 EditAnywhere 说明符。修改 AHelloUE 中 MyValue 成员变量上的 UPROPERTY 宏。

UPROPERTY(BlueprintReadwrite, EditAnywhere)
int32 MyValue;

（6）编译项目后，打开编辑器，并在场景编辑器中运行游戏。由于我们将 MyValue 标记为 EditAnywhere，所以选中场景中的 BP_HelloUE，在细节面板中就可以找到 MyValue 了。MyValue 当前的值是默认值 0。我们可以直接修改它的值并按回车键确定，确定之后，它的值就会被修改到。

2，属性元数据说明符

（1）与 UFUNCTION 类似，UPROPERTY 也可以添加元数据说明符。常用的属性元标签包括了：

DisplayName="Property Name" 属性在蓝图中显示的名称；
Category="Categor" 给属性设置分类。

（2）我们试试通过 DisplayName 和 Category 元标签分别将 MyValue 的名字改为“我的值”，目录名字设置为“我的目录”。

UPROPERTY(BlueprintReadwrite, EditAnywhere, meta=(DisplayName="我的值", Category = "我的目录"))

（3）打开蓝图编辑器，再打开节点编辑器。使用属性在 C++ 层原来的名字“MyValue”已经无法在节点搜索框中找到对应的 Get 和 Set 节点了。这个时候就得使用它的新名字“我的值”来进行搜索，并且可以看到它的分类变成了“我的目录”

（4）回到场景编辑器并运行游戏。在场景中选中 BP_HelloUE，可以在细节面板中看到“我的值”被归类到了目录“我的目录”中。

附：UPROPERTY 支持的类型

在 UC++ 中，一个成员变量只有被标记为了 UProperty，才能被 UE5 识别到。但是 UProperty 不是支持所有类型的成员变量，目前 UPROPRERTY 支持的官方类型包括了：int32 和 int64 整型；bool 布尔型；float 和 double 浮点型；FString 字符串型；FVector，FRotator 等表示 Transform 的结构体。除此之外，UProperty 还支持如下三种类型，下面分别进行介绍。

1，UClass 实例的指针

（1）我们知道一个类可以被标记为 UClass 类，标记为 UClass 类之后，UE5 就可以认得这个类。而 UClass 类的实例我们可以叫它 UObject，UProperty 支持 UObject 指针类型的变量。

（2）例如下面样例，我们假定已经创建了一个 UClass，名为“UNewClass”，然后我们将 UNewClass 指针作为成员变量的类型。

注意：在原生 C++ 中，指针类型的成员变量必须有初始值，一般我们会设置它的初始值为 nullptr。但是将 UObject 指针设置为 UProperty 之后，UE 将（没有设置初始值的）指针初始化为 nullptr。

UPROPERTY()
UNewClass* MyData;

2，自定义的 UStruct

（1）与定义 UClass 相似，我们还可以自定义一个 UStruct，也就是 UC++ 中的结构体。UStruct 类型也是被 UProperty 宏支持的。

（2）例如下面代码，我们创建了一个 UStruct，名为“FMyData”，并创建了一个 FMyData 类型的成员变量，标记为了 UProperty。

UPROPERTY()
FMyData MyData;

3，元素类型为目前 UPROPERTY 支持的官方类型的容器类

（1）比如 TArray <int32>，TArray<UNewClass*>，TArray。这里要注意的是，如果想要容器类能够作为 UProperty，须得满足：

对于 UObject 来说，容器类的元素类型只支持 UObject 对象的指针，不支持 UObject 对象。比如 TArray<UNewClass*> 是支持的，但 TArray<UNewClass> 不支持。
对于 FStruct 来说，容器类的元素类型只支持 FStruct 对象，不支持 FStruct 对象指针。比如 TArray<FMyData> 是支持的，但 TArray<FMyData*> 不支持。

（2）当然不是说容器类的元素只能是上面提到的类型，容器类的元素支持各种类型，只不过如果想要让容器类成为 UProperty，才需要遵循以上规则。下面是一个容器类作为 UProperty 的例子

UPROPERTY()
TArray<float> MyArray;