UE5 - C++开发快速入门教程3（UClass的头文件定义规范、UClass宏）

作者：hangge | 2026-10-14 09:04

在 C++ 中，我们经常会将一个类的声明和实现分开在头文件和 CPP 文件中。前文我们创建了一个名为 AHelloUE 的 UC++ 类，本文我们来看看这个类的头文件是如何实现的。

三、UClass 的头文件定义规范

1，基本介绍

（1）我们知道，原生 C++ 中是没有反射信息一说的（不考虑 RTTI 的情况下），所以如果要让 UE 认得我们编写的自定义类型，就得编写一套规则来注册类的信息到 UE。

（2）UE 选择了为一个原生 C++ 类添加 UCLASS() 宏来对它做标记，并且配合其他的宏，生成类的信息。生成类的信息后，在启动游戏或者编辑器的时候，UE 就会将这些类信息搜集起来。

被 UCLASS 和其他宏包装一番之后，这个类就会成为一个“UClass”，也就是“UE Class（UE 类)”。

（3）我们打开前文创建的 HelloUE 类的头文件 HelloUE.h：

（4）可以发现，在 UC++ 中，定义一个 UClass 与定义一个原生 C++ 类相比，起有三个区别：

在定义 UClass 类体的头文件中，需要包含一些必要的特殊头文件；
在定义 UClass 类体的上一行，需要添加 UCLASS() 宏；
在 UClass 类体中，需要添加 GENERATED_BODY() 宏。

2，包含必要的特殊头文件说明

（1）第一种是“CoreMinimal.h”头文件。CoreMinimal.h 中包括了 UC++ 开发所需要的一些最基础的类。每一个定义 UClass 类体的头文件都需要直接或者间接地使用到这个头文件。其中，“Core”表示核心。如果我们去看这个头文件，会发现这个头文件其实帮我们 include 了很多其他的基础模块，下图只是显示其部分内容。

（2）第二种是“GameFramework/Actor.h”。由于我们的 AHelloUE 需要继承于父类 AActor，所以我们需要包含 AActor 的类体所定义的头文件，也就是 GameFramework/Actor.h 文件。

注意：如果我们的类是直接继承于 UObject 类的，那么这一步可以省去，因为 CoreMinimal.h 头文件已经包括了 UObject 类的定义。

（3）第三种，“HelloUE.generated.h”。这个头文件的前面一段必须是要和当前 UClass 所在的头文件同名，而后半段固定是“generated.h”。

注意：如果我们刚创建了 AHelloUE5，还没有开始编译，会发现找遍整个电脑都找不到这个文件。这是因为这个文件是在编译之前 UE5 为我们自动生成的文件。在这个头文件中，包含了各种 UClass 需要的额外信息。在声明了 UClass 和 UStruct 的头文件里面，一定要将对应名字的 generated 头文件包含进来，并且作为“最后一个”include 的头文件。

3，类体需要添加的宏说明

（1）首先，一个 UClass 必须直接或者间接地继承于 UObject。在这个例子中我们继承了 AActor，其实就是间接地继承于 UObject。至于为什么一定要 UObject 作为 UClass 的祖先类，是因为 UObject 提供了很多必要的基础功能，比如反射、GC 和网络同步等。

（2）其次，为了让 UE5 的工具链能够在处理和生成代码的时候认得这是一个 UC++ 类，还要在 C++ 类体的上一行添加 UCLASS。

（3）最后，还需要在类体中的第一行添加 GENERATED_BODY。UE5 对类的信息进行扫描后会生成一些特殊的代码，这些特殊的代码就是通过 GENERATED BODY 宏来插入到类中的。

附：UClass 宏详解

1，UCLASS 说明符

（1）UCLASS 宏的作用是向 UE5 说明该类是一个 UClass，需要搜集一些必要的信息。我们可以在 UCLASS 宏中加入一些说明符，用来描述这个类的特性。

（2）UCLASS 宏支持的说明符有很多，下面介绍几种常用的说明符。

Abstract（抽象）：标记为抽象后，在蓝图中无法直接将该类实例化。如果该类是一个继承于 AActor 的子类，那么无法被放置到场景中。注意，这只是对该类的限制，它的派生类不受此限制。
Blueprintable（可蓝图化）：添加该标记后，可以将该类作为蓝图类的父类。
BlueprintType（蓝图类型）：使用该标记，可以让该类作为蓝图中的变量类型，也可以作为蓝图类的父类。
Const（常量）:该类的所有属性和函数都会被标记为 const。这个标记会被子类继承。
Deprecated（丢弃）：表示该类是被丢弃的，并且该类实例将不会被序列化。这个标记会被子类继承。
Transient（瞬态）：该类和它所持有的对象都不会被保存到磁盘上。

（3）让我们来实践一下。我们希望上面创建的 AHelloUE 类可以作为蓝图类的父类，那么就需要在 UCLASS 宏中使用说明符 BlueprintType，这个说明符能够将 UClass 变成一个蓝图类型，可以作为蓝图类的父类，也可以成为蓝图类的变量。

首先我们在 UCLASS() 中加入 BlueprintType，然启动 UE5 编辑器。

提示：如果你的 UE5 编辑器正处于打开状态，那么单击 VS 的重新启动按钮就可以触发编译并且重新启动 UE5 编辑器。

接着让我们来继承于 AHelloUE 创建一个新的蓝图类，在选择父类的窗口中，我们在所有类型的列表里，搜索不带前缀的 C++ 类名“HelloUE”，并选择它作为父类。将创建出来的蓝图类命名为“BP_HelloUE”

双击 BP_HelloUE 打开蓝图类编辑器，注意观察左上角的“组件”视图，可以发现对比原生的 HelloUE 类，子类 BP_HelloUE 多了个 DefaultSceneRoot。意味着如果它被拖动到场景中，我们可以改变它的位置。

最后试一下。我们将类 BP_HelloUE 从“内容浏览器”中拖动到场景里。单击场景中的实例，我们会发现它是可以被移动的，在细节面板中可以直接修改它的坐标。

2，类元数据说明符

（1）UCLASS 宏除了上面提到的说明符之外，还支持指定元数据（meta data）。元数据指的是一组额外需要保存的数据，它在 UCLASS 宏中的使用方法如下：

UCLASS(meta=(key=value, key=value))

（2）meta 其实是一个 Map，其中的配置都是以键值对形式存在，配置方式是 key=value。

注意：如果需要在元数据中将某个条目的值设置为中文，那我们必须保证代码的编码是 UTF-8，最终看到的效果才不会是乱码。

（3）元数据支持的类元标签包括了：

DisplayName="Blueprint Node Name" 我们可以通过 DisplayName 来设置类在 UE5 编辑器中显示的名字。有时候我们在 C++ 编程中给类起的名字可能让蓝图使用者理解起来可能会有些困难，这个时候我们就可以通过 DisplayName 来给类添加别名。
ShortToolTip="Short tooltip" 和 ToolTip="Hand-written tooltip" 这两个都是对该类的提示。你可以在这两个配置中添加对类的解释，当使用者在编辑器中把光标移动到该类的选项上时，就会显示这些提示。

（4）实践一下，在这里我们将 UCLASS 宏进行如下修改，给 Class 设置一个别名和提示。

UCLASS(BlueprintType, meta=(DisplayName="你好虚幻引擎", ShortToolTip="这是一个提示信息"))

（5）编译之后打开 UE5 编辑器。我们再尝试创建一个蓝图类，打开父类选择面板后，在“所有类”下方的搜索框中搜索“HelloUE”。可以看到在 HelloUE 类的后面出现了一个括号，写着 DisplayName 对应的名字。把光标放到这个类的菜单上，可以看到浮现出了一个提示框。