1
// ===== Slate vs UMG 的核心区别 =====
2
//
3
// Slate（纯 C++ 声明式）：
4
//   - 直接操作 SWidget / SButton / STextBlock 等底层类型
5
//   - 构建 UI 用 SNew / SAssignNew + 声明式括号语法
6
//   - 不依赖 UObject —— 纯 C++ 对象，不能序列化，不可蓝图
7
//   - 优势：极致的 CPU 性能和内存控制，100% C++ 可控
8
//   - 场景：编辑器面板、引擎工具、极端性能要求的 HUD
9
//
10
// UMG（UObject 包裹层）：
11
//   - 操作 UUserWidget / UButton / UTextBlock 等反射包装类
12
//   - 构建 UI 在编辑器中拖拽、或在 C++ 中用 CreateWidget
13
//   - 完整反射支持 —— 序列化、蓝图、动画、属性绑定
14
//   - 优势：可视化开发、策划可改、设计师可做动画
15
//   - 场景：游戏 UI、菜单、HUD、背包、对话框
16
//
17
// 99% 的日常开发用 UMG。剩下 1% 是编辑器工具或对 Slate 的深度定制。

1
// ===== Slate 版本 —— 纯 C++ 声明式 =====
2
void OpenMySlateWindow()
3
{
4
    // SNew 创建 SWindow，声明式语法嵌套子控件
5
    TSharedRef<SWindow> Window = SNew(SWindow)
6
        .Title(FText::FromString(TEXT("Hello Slate")))
7
        .ClientSize(FVector2D(400, 300))
8
        [
9
            SNew(SVerticalBox)
10
            + SVerticalBox::Slot()
11
            .AutoHeight()
12
            [
13
                SNew(STextBlock)
14
                .Text(FText::FromString(TEXT("这是一段纯 Slate 文本")))
15
            ]
16
            + SVerticalBox::Slot()
17
            .FillHeight(1.0f)
18
            [
19
                SNew(SButton)
20
                .Text(FText::FromString(TEXT("点我")))
21
                .OnClicked_Lambda([]() {
22
                    return FReply::Handled();  // 已消费点击事件
23
                })
24
            ]
25
        ];
26

27
    FSlateApplication::Get().AddWindow(Window);
28
}
29

30
// ===== UMG 版本 —— C++ 创建 Widget，蓝图中搭界面 =====
31
UCLASS()
32
class UMyUserWidget : public UUserWidget
33
{
34
    GENERATED_BODY()
35

36
protected:
37
    // BindWidget —— 由蓝图中的同名控件自动绑定
38
    UPROPERTY(meta = (BindWidget))
39
    TObjectPtr<UTextBlock> TitleText;
40

41
    UPROPERTY(meta = (BindWidget))
42
    TObjectPtr<UButton> MyButton;
43

44
    virtual void NativeConstruct() override
45
    {
46
        Super::NativeConstruct();
47

48
        // 绑定按钮点击
49
        if (MyButton)
50
        {
51
            MyButton->OnClicked.AddDynamic(this, &UMyUserWidget::OnButtonClicked);
52
        }
53
    }
54

55
    UFUNCTION()
56
    void OnButtonClicked()
57
    {
58
        UE_LOG(LogTemp, Log, TEXT("按钮被点击了"));
59
    }
60
};
61

62
// 在 Controller 中显示：
63
void AMyPlayerController::ShowMyWidget()
64
{
65
    if (UMyUserWidget* Widget = CreateWidget<UMyUserWidget>(this, MyWidgetClass))
66
    {
67
        Widget->AddToViewport();
68
    }
69
}

1
// ===== 自定义一个 Slate 控件 =====
2
// Slate 使用一套"声明式构建器（Declarative Builder）"模式
3

4
// 第一步：用 SLATE_BEGIN_ARGS / SLATE_END_ARGS 定义参数
5
// 第二步：用 Construct() 函数根据参数构建子控件
6
// 第三步：用 SNew(MyWidget).Param1(x).Param2(y) 实例化
7

8
class SMyCompoundWidget : public SCompoundWidget
9
{
10
public:
11
    // ★ SLATE_BEGIN_ARGS —— 定义这个控件的"构造函数参数"
12
    SLATE_BEGIN_ARGS(SMyCompoundWidget)
13
        // SLATE_ARGUMENT —— 一次性传入，之后不动态更新
14
        SLATE_ARGUMENT(FString, Title)
15
        SLATE_ARGUMENT(int32, MaxItems)
16

17
        // SLATE_ATTRIBUTE —— 可动态绑定的属性（每次 Tick 重新求值）
18
        SLATE_ATTRIBUTE(int32, CurrentCount)
19

20
        // SLATE_EVENT —— 事件/委托（通常是 Lambda 或 UFUNCTION）
21
        SLATE_EVENT(FOnClicked, OnItemSelected)
22
    SLATE_END_ARGS()
23

24
    // 构建函数 —— 用传入的 Args 创建子控件
25
    void Construct(const FArguments& InArgs)
26
    {
27
        // 读取参数
28
        FString TitleString = InArgs._Title;
29
        int32 Max = InArgs._MaxItems;
30
        TAttribute<int32> CurrentAttr = InArgs._CurrentCount;
31
        FOnClicked ClickHandler = InArgs._OnItemSelected;
32

33
        ChildSlot
34
        [
35
            SNew(SVerticalBox)
36
            + SVerticalBox::Slot()
37
            .AutoHeight()
38
            [
39
                SNew(STextBlock)
40
                .Text(FText::FromString(TitleString))
41
            ]
42
            + SVerticalBox::Slot()
43
            .FillHeight(1.0f)
44
            [
45
                SNew(SButton)
46
                .OnClicked(ClickHandler)
47
                // .OnClicked_Lambda(...)  // 或直接用 Lambda
48
            ]
49
        ];
50
    }
51
};
52

53
// ===== 使用自定义 Slate Widget =====
54
TSharedRef<SMyCompoundWidget> MyWidget = SNew(SMyCompoundWidget)
55
    .Title(TEXT("背包"))
56
    .MaxItems(100)
57
    .CurrentCount_Lambda([]() { return GetInventoryCount(); })
58
    .OnItemSelected(FOnClicked::CreateLambda([]() {
59
        UE_LOG(LogTemp, Log, TEXT("物品被选中"));
60
        return FReply::Handled();
61
    }));
62

63
// ===== SAssignNew —— 获取 Slate Widget 的共享引用 =====
64
TSharedPtr<SButton> ButtonPtr;  // 拿到引用，后续可以修改
65
SAssignNew(ButtonPtr, SButton)
66
    .Text(FText::FromString(TEXT("动态按钮")));
67

68
// ... 之后
69
ButtonPtr->SetText(FText::FromString(TEXT("文本已修改")));

1
// ===== Slate 布局核心：Slot 类型 =====
2
// 不同的父容器提供不同的 Slot 类型——
3

4
// SVerticalBox → SVerticalBox::Slot()
5
//   .AutoHeight()  —— 自动高度（适应内容）
6
//   .FillHeight(1.0f) —— 弹性填充（等比例分配剩余空间）
7
//   .MaxHeight(100.0f) —— 最大高度限制
8
//   .HAlign(HAlign_Left/Center/Right)
9
//   .VAlign(VAlign_Top/Center/Bottom)
10
//   .Padding(FMargin(10, 5))
11

12
// SHorizontalBox → SHorizontalBox::Slot()
13
//   .AutoWidth()
14
//   .FillWidth(1.0f)
15
//   .HAlign(...) / .VAlign(...)
16

17
// SOverlay → SOverlay::Slot()
18
//   .HAlign(...) / .VAlign(...)
19
//   .Padding(...)
20

21
// SCanvas → SCanvas::Slot()
22
//   .Position(FVector2D(100, 200))    // 绝对定位
23
//   .Size(FVector2D(300, 50))         // 绝对尺寸
24

25
// ===== 一个完整布局示例 =====
26
SNew(SVerticalBox)
27
+ SVerticalBox::Slot()
28
    .AutoHeight()
29
    .HAlign(HAlign_Center)
30
    .Padding(FMargin(0, 10))
31
    [
32
        SNew(STextBlock).Text(LOCTEXT("Title", "主菜单"))
33
    ]
34
+ SVerticalBox::Slot()
35
    .FillHeight(0.7f)
36
    .Padding(FMargin(20, 0))
37
    [
38
        SNew(SHorizontalBox)
39
        + SHorizontalBox::Slot()
40
        .FillWidth(0.3f)
41
        .Padding(FMargin(5))
42
        [
43
            SNew(SButton).Text(LOCTEXT("NewGame", "新游戏"))
44
        ]
45
        + SHorizontalBox::Slot()
46
        .FillWidth(0.3f)
47
        .Padding(FMargin(5))
48
        [
49
            SNew(SButton).Text(LOCTEXT("Continue", "继续游戏"))
50
        ]
51
        + SHorizontalBox::Slot()
52
        .FillWidth(0.3f)
53
        .Padding(FMargin(5))
54
        [
55
            SNew(SButton).Text(LOCTEXT("Settings", "设置"))
56
        ]
57
    ]
58
+ SVerticalBox::Slot()
59
    .AutoHeight()
60
    .HAlign(HAlign_Right)
61
    .Padding(FMargin(10))
62
    [
63
        SNew(STextBlock).Text(LOCTEXT("Version", "v1.0.0"))
64
    ];

1
// Slate 的 TAttribute<T> 允许你"动态绑定"一个值的获取方式
2
// ——它本质是一个可调用的函数对象，每次被读取时重新求值。
3

4
// ===== 三种属性绑定方式 =====
5

6
// ① 静态值（一次设置，永不更新）
7
TAttribute<FText> StaticText = FText::FromString(TEXT("永不改变"));
8

9
// ② Lambda 动态绑定（每次 Get() 都重新执行）
10
TAttribute<FText> DynamicText = TAttribute<FText>::Create_Lambda([]() {
11
    return FText::FromString(FString::Printf(TEXT("当前帧: %d"), GFrameCounter));
12
});
13

14
// ③ 绑定到成员变量或函数
15
TAttribute<FSlateColor> HealthColor = TAttribute<FSlateColor>::Create(
16
    TAttribute<FSlateColor>::FGetter::CreateUObject(this, &UMyWidget::GetHealthColor));
17

18
// ===== 在 Slate 控件中使用属性 =====
19
SNew(STextBlock)
20
    .Text(DynamicText)  // ← 每次渲染前自动调用 Lambda 获取最新值
21
    .ColorAndOpacity(HealthColor);
22

23
// ===== UMG 层面的等价物：BindWidget + UPROPERTY 绑定 =====
24
// UMG 的属性绑定系统（在编辑器中把"Health"绑到"Text"上）
25
// 底层就是通过 TAttribute 实现的——它们用的是同一套机制。

1
UCLASS()
2
class UMyHUDWidget : public UUserWidget
3
{
4
    GENERATED_BODY()
5

6
public:
7
    // ===== UUserWidget 生命周期（按调用顺序） =====
8

9
    // ① NativePreConstruct —— 在编辑器中预览时 / 编译时调用
10
    virtual void NativePreConstruct() override
11
    {
12
        Super::NativePreConstruct();
13
        // ✗ 这里没有 World！不能访问 GameMode / PlayerController
14
        // ✓ 适合：根据编辑器预览数据设置控件的初始外观
15
    }
16

17
    // ② NativeConstruct —— Widget 被创建后调用（有 World 了）
18
    virtual void NativeConstruct() override
19
    {
20
        Super::NativeConstruct();
21
        // ✓✓✓ 初始化入口！等价于 Actor 的 BeginPlay
22
        // ✓ 可以访问 World、GameMode、PlayerController
23
        // ✓ 绑定事件、设置初始状态、启动动画
24
        // ⚠️ 每次 AddToViewport() 都会触发——不仅一次！
25

26
        BindDelegates();
27
        CachePlayerController();
28
        PlayIntroAnimation();
29
    }
30

31
    // ③ NativeTick —— 每帧调用（需要设置 bCanEverTick = true）
32
    virtual void NativeTick(const FGeometry& MyGeometry, float InDeltaTime) override
33
    {
34
        Super::NativeTick(MyGeometry, InDeltaTime);
35

36
        // ⚠️ 只在确实需要时启用！默认关闭
37
        // ✓ 适合：每帧更新的 HUD（血量条、雷达、计时器）
38
        // ✗ 不适合：菜单、对话框——用蓝图事件/委托替代
39
    }
40

41
    // ④ NativeDestruct —— 底层 Slate Widget 从 Slate 树中被移除时调用
42
    //   （如 RemoveFromParent()），不等同于 UObject 被 GC 销毁！
43
    //    如果再次 AddToViewport()，NativeConstruct 会重新触发
44
    virtual void NativeDestruct() override
45
    {
46
        // ✓ 清理可恢复的状态：解绑委托、取消 Timer
47
        UnbindDelegates();
48
        Super::NativeDestruct();
49
        // ✗ 不要在这里释放"永久资源"——Widget 可能稍后被重新 AddToViewport
50
    }
51

52
    // ===== 设置 Tick =====
53
    // 在 NativeConstruct 中或蓝图类默认选项中：
54
    // SetTickableWhenPaused(true);   // 暂停时仍 Tick
55

56
    // ===== 蓝图暴露的可重写事件 =====
57
    // BlueprintNativeEvent  —— C++ 有默认实现，蓝图可重写
58
    // BlueprintImplementableEvent —— C++ 不实现，蓝图必须实现
59

60
    UFUNCTION(BlueprintNativeEvent, Category = "HUD")
61
    void OnHealthChanged(float Current, float Max);
62
    void OnHealthChanged_Implementation(float Current, float Max)
63
    {
64
        // C++ 默认实现——更新血条
65
        if (HealthBar)
66
        {
67
            HealthBar->SetPercent(Current / Max);
68
        }
69
    }
70

71
    UFUNCTION(BlueprintImplementableEvent, Category = "HUD")
72
    void OnPlayerDied();  // 纯蓝图实现——播放死亡动画
73
};
74

75
// ===== NativeConstruct 多次触发的问题 =====
76
// 场景：一个 Widget 被 RemoveFromParent() 再 AddToViewport()
77
// → NativeConstruct 会再次调用！
78
// 如果你的初始化代码不应该重复执行：
79
void UMyHUDWidget::NativeConstruct()
80
{
81
    Super::NativeConstruct();
82

83
    if (bIsInitialized) return;  // 防止重复初始化
84
    bIsInitialized = true;
85

86
    // 真正只执行一次的初始化……
87
}

1
// BindWidget 是 UMG 最优雅的 C++/蓝图桥接机制——
2
// 只要 C++ 中成员变量名 == 蓝图中控件名，引擎自动赋值！
3

4
UCLASS()
5
class UMainMenuWidget : public UUserWidget
6
{
7
    GENERATED_BODY()
8

9
public:
10
    // ===== BindWidget —— 必须存在，蓝图中的同名控件自动注入 =====
11
    UPROPERTY(meta = (BindWidget))
12
    TObjectPtr<UButton> StartGameButton;
13

14
    UPROPERTY(meta = (BindWidget))
15
    TObjectPtr<UButton> QuitButton;
16

17
    UPROPERTY(meta = (BindWidget))
18
    TObjectPtr<UTextBlock> TitleText;
19

20
    // ===== BindWidgetOptional —— 可选存在，不存在不报错 =====
21
    UPROPERTY(meta = (BindWidgetOptional))
22
    TObjectPtr<UImage> BackgroundImage;  // 不是所有蓝图子类都有背景图
23

24
    // ===== BindWidgetAnim —— 自动绑定同名的 UWidgetAnimation =====
25
    UPROPERTY(meta = (BindWidgetAnim), Transient)
26
    TObjectPtr<UWidgetAnimation> FadeInAnimation;
27

28
    // ===== 不用 meta 的普通成员 —— 需要通过 Editor Properties 手动赋值 =====
29
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly)
30
    TObjectPtr<USoundBase> HoverSound;
31

32
protected:
33
    virtual void NativeConstruct() override
34
    {
35
        Super::NativeConstruct();
36

37
        // BindWidget 的控件在 NativeConstruct 中已经自动赋值完成
38
        if (StartGameButton)
39
        {
40
            StartGameButton->OnClicked.AddDynamic(this, &UMainMenuWidget::OnStartGame);
41
        }
42
        if (QuitButton)
43
        {
44
            QuitButton->OnClicked.AddDynamic(this, &UMainMenuWidget::OnQuit);
45
        }
46
    }
47

48
    UFUNCTION()
49
    void OnStartGame() { /* ... */ }
50

51
    UFUNCTION()
52
    void OnQuit()
53
    {
54
        if (APlayerController* PC = GetOwningPlayer())
55
        {
56
            UKismetSystemLibrary::QuitGame(GetWorld(), PC,
57
                EQuitPreference::Quit, false);
58
        }
59
    }
60
};
61
// ★ 关键规则：C++ 变量名必须与蓝图中控件的名字完全一致！
62
//   蓝图中的"StartGameButton" → C++ 中必须是 StartGameButton
63
//   大小写敏感——它是通过 FName 匹配的，不是字符串搜索

1
void UMyHUDWidget::UpdateAmmoDisplay(int32 CurrentAmmo, int32 MaxAmmo)
2
{
3
    // ===== UTextBlock —— 设置文本 =====
4
    if (AmmoText)
5
    {
6
        AmmoText->SetText(FText::Format(
7
            LOCTEXT("AmmoFormat", "{0} / {1}"),
8
            FText::AsNumber(CurrentAmmo),
9
            FText::AsNumber(MaxAmmo)
10
        ));
11
    }
12

13
    // ===== UProgressBar —— 设置百分比 =====
14
    if (HealthBar)
15
    {
16
        HealthBar->SetPercent(static_cast<float>(CurrentAmmo) / MaxAmmo);
17
    }
18

19
    // ===== UImage —— 更换纹理 =====
20
    if (WeaponIcon)
21
    {
22
        WeaponIcon->SetBrushFromTexture(WeaponTexture);
23
        // 或从材质
24
        // WeaponIcon->SetBrushFromMaterial(WeaponMaterial);
25
    }
26

27
    // ===== UWidget —— 显示/隐藏 =====
28
    if (LowAmmoWarning)
29
    {
30
        // ESlateVisibility::Visible / Collapsed / Hidden / HitTestInvisible
31
        LowAmmoWarning->SetVisibility(
32
            CurrentAmmo <= 5 ? ESlateVisibility::Visible : ESlateVisibility::Collapsed);
33
        // Collapsed → 不渲染，不占布局空间
34
        // Hidden    → 不渲染，但占布局空间（保留位置）
35
    }
36

37
    // ===== UBorder —— 设置颜色 =====
38
    if (DamageBorder)
39
    {
40
        DamageBorder->SetBrushColor(
41
            CurrentAmmo <= 0 ? FLinearColor::Red : FLinearColor::Transparent);
42
    }
43

44
    // ===== UButton —— 设置交互 =====
45
    if (FireButton)
46
    {
47
        FireButton->SetIsEnabled(CurrentAmmo > 0);
48
    }
49
}

1
// ===== Controller 中管理 HUD =====
2
UCLASS()
3
class AMyPlayerController : public APlayerController
4
{
5
    GENERATED_BODY()
6

7
public:
8
    // Widget 类引用——在蓝图中设置
9
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "UI")
10
    TSubclassOf<UMyHUDWidget> HUDWidgetClass;
11

12
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "UI")
13
    TSubclassOf<UPauseMenuWidget> PauseMenuClass;
14

15
protected:
16
    virtual void BeginPlay() override
17
    {
18
        Super::BeginPlay();
19

20
        if (IsLocalPlayerController())
21
        {
22
            CreateHUD();
23
        }
24
    }
25

26
    void CreateHUD()
27
    {
28
        if (!HUDWidgetClass) return;
29

30
        HUDWidget = CreateWidget<UMyHUDWidget>(this, HUDWidgetClass);
31
        if (HUDWidget)
32
        {
33
            HUDWidget->AddToViewport();
34
            // AddToViewport(10) —— 参数是 ZOrder，越大越上层
35
        }
36
    }
37

38
    void TogglePauseMenu()
39
    {
40
        if (PauseMenuWidget && PauseMenuWidget->IsInViewport())
41
        {
42
            PauseMenuWidget->RemoveFromParent();  // 从视口移除
43
            // RemoveFromParent() 不销毁 UObject——Widget 仍然存在！
44
            // 可以稍后 AddToViewport() 重新显示
45
        }
46
        else
47
        {
48
            if (!PauseMenuWidget)
49
            {
50
                PauseMenuWidget = CreateWidget<UPauseMenuWidget>(this, PauseMenuClass);
51
            }
52
            PauseMenuWidget->AddToViewport(100);  // ZOrder=100，覆盖一切
53
        }
54

55
        bShowMouseCursor = PauseMenuWidget && PauseMenuWidget->IsInViewport();
56
        SetInputMode(bShowMouseCursor ?
57
            FInputModeGameAndUI() : FInputModeGameOnly());
58
    }
59

60
private:
61
    UPROPERTY()
62
    TObjectPtr<UMyHUDWidget> HUDWidget;
63

64
    UPROPERTY()
65
    TObjectPtr<UPauseMenuWidget> PauseMenuWidget;
66
};

1
控制台命令：
2

3
WidgetReflector
4
  → 打开 Slate Widget Reflector 窗口
5

6
快捷键：Ctrl+Shift+W（默认绑定）
7

8
Reflector 功能：
9
  ① Hit Test Grid —— 点击任意 UI 元素，在 Reflector 中高亮其 Slate 层级
10
  ② Draw Pick —— 鼠标悬停显示控件边界、名称、源文件
11
  ③ Visualizers —— 绘制每个控件的边界框、Padding 区域、HitTest 区域
12
  ④ Snapshot —— 截取当前 UI 树，导出为文本分析
13
  ⑤ Focus Debugging —— 查看当前焦点路径（哪个控件有键盘焦点？为什么？）
14
  ⑥ Performance —— 每个控件的绘制成本（Draw Cost）和 Invalidation 状态
15

16
WidgetReflector 本质是一个 Slate Widget 自身——它工作在整个 Slate 应用层的顶部。

1
// Reflector 中看到：
2
//   SOverlay
3
//     └─ SVerticalBox
4
//          ├─ STextBlock("主菜单")    ← Source: UMG_Generated::MainMenu_C
5
//          ├─ SButton("新游戏")       ← Source: UMG_Generated::MainMenu_C
6
//          └─ SButton("退出")         ← Source: UMG_Generated::MainMenu_C
7
//
8
// → 这是一个 UUserWidget 的蓝图子类（MainMenu_C）
9
// → 顶层是 SOverlay（对应 UMG 的 Canvas Panel）
10
// → VerticalBox 中有三个子控件
11
//
12
// 这告诉你：如果你看到某个 UI 元素行为不对——
13
// ① 在 Reflector 中 Pick 它
14
// ② 看它的 HitTest 是否被父控件拦截（Draw Pick 红色边框 = HitTestable）
15
// ③ 看它的 Visibility（Collapsed 的控件在树中不出现）
16
// ④ 追踪 Source 字段——反向定位到蓝图 Assets

1
// ===== 第一步：定义数据对象（UObject） =====
2
UCLASS(BlueprintType)
3
class UInventoryItemData : public UObject
4
{
5
    GENERATED_BODY()
6

7
public:
8
    UPROPERTY(BlueprintReadOnly)
9
    FText ItemName;
10

11
    UPROPERTY(BlueprintReadOnly)
12
    int32 Quantity;
13

14
    UPROPERTY(BlueprintReadOnly)
15
    TObjectPtr<UTexture2D> Icon;
16

17
    UPROPERTY(BlueprintReadOnly)
18
    int32 ItemId;
19
};
20

21
// ===== 第二步：定义条目 Widget（UUserWidget + IUserObjectListEntry） =====
22
UCLASS()
23
class UInventoryItemWidget : public UUserWidget
24
{
25
    GENERATED_BODY()
26

27
public:
28
    UPROPERTY(meta = (BindWidget))
29
    TObjectPtr<UTextBlock> NameText;
30

31
    UPROPERTY(meta = (BindWidget))
32
    TObjectPtr<UTextBlock> QuantityText;
33

34
    UPROPERTY(meta = (BindWidget))
35
    TObjectPtr<UImage> IconImage;
36

37
    // IUserObjectListEntry 的核心回调——必须覆写此虚函数，引擎在复用 Widget 时自动调用
38
    // 对应蓝图事件：OnListItemObjectSet
39
    virtual void NativeOnListItemObjectSet(UObject* ListItemObject) override
40
    {
41
        IUserObjectListEntry::NativeOnListItemObjectSet(ListItemObject);
42

43
        UInventoryItemData* ItemData = Cast<UInventoryItemData>(ListItemObject);
44
        if (!ItemData) return;
45

46
        NameText->SetText(ItemData->ItemName);
47
        QuantityText->SetText(FText::AsNumber(ItemData->Quantity));
48
        IconImage->SetBrushFromTexture(ItemData->Icon);
49
    }
50
};
51

52
// ===== 第三步：在 C++ 中使用 UListView =====
53
UCLASS()
54
class UInventoryWidget : public UUserWidget
55
{
56
    GENERATED_BODY()
57

58
public:
59
    UPROPERTY(meta = (BindWidget))
60
    TObjectPtr<UListView> ItemListView;
61

62
    virtual void NativeConstruct() override
63
    {
64
        Super::NativeConstruct();
65

66
        // 方式一：直接灌入数据对象数组
67
        TArray<UInventoryItemData*> Items;
68
        for (int32 i = 0; i < 100; i++)
69
        {
70
            UInventoryItemData* Item = NewObject<UInventoryItemData>(this);
71
            Item->ItemName = FText::Format(LOCTEXT("ItemFmt", "物品 {0}"), FText::AsNumber(i));
72
            Item->Quantity = FMath::RandRange(1, 99);
73
            Item->ItemId = i;
74
            Items.Add(Item);
75
        }
76
        ItemListView->SetListItems(Items);  // ← 只创建可见的 Widget，其余在池中
77

78
        // 监听选择变化
79
        ItemListView->OnItemSelectionChanged().AddUObject(
80
            this, &UInventoryWidget::OnItemSelected);
81
    }
82

83
    void OnItemSelected(UObject* SelectedItem)
84
    {
85
        if (UInventoryItemData* Item = Cast<UInventoryItemData>(SelectedItem))
86
        {
87
            UE_LOG(LogTemp, Log, TEXT("选中了物品: %s (ID: %d)"),
88
                *Item->ItemName.ToString(), Item->ItemId);
89
        }
90
    }
91
};
92

93
// ===== ListView 的条目复用生命周期 =====
94
// 当一个条目滚出屏幕：
95
//   1. NativeOnListItemObjectSet(nullptr) —— 通知条数据已清空
96
//   2. Widget 回到 Entry Widget Pool 中
97
// 当一个条目滚入屏幕：
98
//   1. 从 Pool 取出一个空闲 Widget（或创建新的）
99
//   2. NativeOnListItemObjectSet(NewData)  —— 设置新数据
100
//   3. NativeOnEntryReleased()  —— 条目已就绪并显示

1
// TreeView 在 ListView 的基础上增加了"展开/折叠"层级结构
2

3
UCLASS(BlueprintType)
4
class UInventoryCategory : public UObject
5
{
6
    GENERATED_BODY()
7

8
public:
9
    UPROPERTY(BlueprintReadOnly)
10
    FText CategoryName;
11

12
    UPROPERTY(BlueprintReadOnly)
13
    TArray<UInventoryCategory*> Children;  // ← 子级数据
14

15
    UPROPERTY(BlueprintReadOnly)
16
    TArray<UInventoryItemData*> Items;      // ← 该分类下的物品
17
};
18

19
// ===== TreeView 的条目 Widget 需要实现 OnGetChildren =====
20
// 蓝图步骤：
21
// 1. 设置 TreeView 的 ListItems（根节点数据）
22
// 2. 在蓝图条目 Widget 中重写 OnGetChildren 事件——
23
//    引擎调用它来获取"这个条目有没有子节点？子节点数据是什么？"
24
// 3. TreeView 自动管理展开/折叠动画和子节点的可见性
25

26
// C++ 核心：设置 TreeView 条目类
27
// TreeView->SetItemClass(UMyTreeItemWidget::StaticClass());
28
// 条目的 NativeOnListItemObjectSet 与 ListView 完全一样
29

30
// ⚠️ TreeView 的性能注意事项：
31
// - 展开一个节点 = 一次性创建其所有直接子节点的 Widget（如果它们在屏幕内）
32
// - 深层嵌套（>5 层）+ 大量子节点 → 考虑 VR（Virtualized Rendering / 延迟加载）
33
// - 每个条目本质仍是 Slate Widget——不要在一个节点下挂 10000 个子节点

1
UCLASS()
2
class UAnimatedWidget : public UUserWidget
3
{
4
    GENERATED_BODY()
5

6
public:
7
    // BindWidgetAnim —— 自动绑定蓝图中的同名动画
8
    UPROPERTY(meta = (BindWidgetAnim), Transient)
9
    TObjectPtr<UWidgetAnimation> FadeIn;
10

11
    UPROPERTY(meta = (BindWidgetAnim), Transient)
12
    TObjectPtr<UWidgetAnimation> ShakeEffect;
13

14
    virtual void NativeConstruct() override
15
    {
16
        Super::NativeConstruct();
17

18
        if (FadeIn)
19
        {
20
            // 播放动画（正向播放）
21
            PlayAnimation(FadeIn);
22

23
            // 带回调的播放：
24
            // PlayAnimationForward(FadeIn);
25
            // PlayAnimationReverse(FadeIn);
26
            // PlayAnimationTimeRange(FadeIn, 0.0f, 1.0f, 1, EUMGSequencePlayMode::Forward);
27
        }
28
    }
29

30
    void PlayDamageShake()
31
    {
32
        if (ShakeEffect)
33
        {
34
            // 循环播放 3 次
35
            PlayAnimation(ShakeEffect, 0.0f, 3, EUMGSequencePlayMode::PingPong);
36
        }
37
    }
38

39
    void StopShake()
40
    {
41
        if (ShakeEffect && IsAnimationPlaying(ShakeEffect))
42
        {
43
            StopAnimation(ShakeEffect);
44
        }
45
    }
46
};
47

48
// ===== 监听动画事件 =====
49
// UWidgetAnimation 没有直接的 OnFinished 委托绑定——
50
// 使用 FWidgetAnimationDynamicEvent（UE5.1+）：
51
//
52
// FWidgetAnimationDynamicEvent FinishedDelegate;
53
// FinishedDelegate.BindDynamic(this, &UAnimatedWidget::OnFadeInFinished);
54
// BindToAnimationFinished(FadeIn, FinishedDelegate);
55

56
// 或在蓝图中绑定 Animation Finished 事件（更常用）

1
// UImage 可以设置一个 Material Instance ——
2
// 这个材质的输入是 UI 纹理，但可以叠加材质节点的效果：
3
//    · 圆形遮罩（Radial Mask）→ 技能冷却转圈
4
//    · 溶解（Dissolve）→ 过渡动画
5
//    · 模糊（Blur）→ 背景虚化
6
//    · 变色（Hue Shift）→ 受击闪红
7

8
void UMyHUDWidget::UpdateSkillCooldown(float Percent)
9
{
10
    if (CooldownMaterialInstance)
11
    {
12
        // 设置 Material Instance 的 Scalar Parameter
13
        CooldownMaterialInstance->SetScalarParameterValue(
14
            TEXT("CooldownPercent"), Percent);
15
        // ↑ UI 材质中的 RadialMask 读取这个参数，画出冷却转圈效果
16

17
        // 设置 Vector Parameter
18
        CooldownMaterialInstance->SetVectorParameterValue(
19
            TEXT("TintColor"), FLinearColor::Red);
20
    }
21
}
22

23
// ===== 创建 UI 材质实例 =====
24
void UMyHUDWidget::NativeConstruct()
25
{
26
    Super::NativeConstruct();
27

28
    if (CooldownImage)
29
    {
30
        // 从基础 Material 创建动态实例
31
        if (UMaterialInterface* BaseMat = LoadObject<UMaterialInterface>(
32
            nullptr, TEXT("/Game/UI/Materials/M_UICooldown")))
33
        {
34
            CooldownMaterialInstance = CooldownImage->GetDynamicMaterial();
35
            if (!CooldownMaterialInstance)
36
            {
37
                CooldownMaterialInstance = UMaterialInstanceDynamic::Create(
38
                    BaseMat, this);
39
                CooldownImage->SetBrushFromMaterial(CooldownMaterialInstance);
40
            }
41
        }
42
    }
43
}

1
// ===== UI 文本的黄金规则 =====
2
//
3
// 任何最终显示在屏幕上的文本 → FText
4
// 任何内部处理、调试、日志的文本 → FString
5
// 任何用作标识符/哈希键的文本     → FName
6

7
// ✗ 常见错误：
8
FString Name = TEXT("玩家名称");
9
UTextBlock->SetText(FText::FromString(Name));  // ← 不允许本地化！
10
// 这个"玩家名称"在中文版显示"玩家名称"，但英文版也会显示"玩家名称"——无法翻译
11

12
// ✓ 正确写法：
13
// 方式一：LOCTEXT —— 编码时指定源语言和翻译
14
UTextBlock->SetText(LOCTEXT("PlayerNameLabel", "Player Name"));
15
// 编译后生成 .po 文件 → 翻译团队翻译 → 打包时合并 → 运行时根据区域显示翻译
16

17
// 方式二：NSLOCTEXT —— 带命名空间的版本（推荐大型项目）
18
UTextBlock->SetText(NSLOCTEXT("HUD", "PlayerNameLabel", "Player Name"));
19
//       命名空间 ↑          键 ↑             源文本 ↑
20

21
// 方式三：FText::Format —— 带参数的动态文本
22
int32 Score = 1000;
23
UTextBlock->SetText(FText::Format(
24
    LOCTEXT("ScoreFormat", "Score: {0}"),
25
    FText::AsNumber(Score)
26
));
27
// 输出：中文"得分：1000"，英文"Score: 1000"

1
// StringTable 是一个 CSV 或 JSON 文件，存储 Key → 多语言文本的映射
2
// 策划/翻译团队可以直接编辑 CSV，不需要打开 UE
3

4
// ===== StringTable 的使用流程 =====
5
//
6
// ① 创建 StringTable 资产（CSV 格式）：
7
//    Key,                SourceString,       zh-Hans,            ja
8
//    "Game_Title",       "Dragon Slayer",    "屠龙勇士",         "ドラゴンスレイヤー"
9
//    "Btn_Start",        "Start Game",       "开始游戏",         "ゲーム開始"
10
//    "Tip_NoAmmo",       "No Ammo!",         "没子弹了！",       "弾切れ！"
11
//
12
// ② 在 C++ 中从 StringTable 获取文本：
13

14
void UMyHUDWidget::LocalizeUI()
15
{
16
    // FText::FromStringTable —— 从 StringTable 中读取
17
    // 参数①：FName TableId（注册表中的表名，非磁盘路径！）
18
    // 参数②：FName Key（CSV 中的 Key 列）
19
    if (TitleText)
20
    {
21
        TitleText->SetText(FText::FromStringTable(
22
            FName(TEXT("/Game/StringTables/ST_UI")), TEXT("Game_Title")));
23
    }
24
    if (StartButtonText)
25
    {
26
        StartButtonText->SetText(FText::FromStringTable(
27
            FName(TEXT("/Game/StringTables/ST_UI")), TEXT("Btn_Start")));
28
    }
29
    // ⚠️ 第一参数是 StringTable 注册 ID（FName）。
30
    //    如果你是在 Content Browser 中右键创建的 StringTable **资产**（.uasset），
31
    //    引擎默认自动生成的注册 ID 就是其**磁盘全量长路径**！
32
    //    例如：FName(TEXT("/Game/StringTables/ST_UI"))
33
    //    传入短名 FName(TEXT("ST_UI")) 反而会查无此名导致本地化文本全线崩溃！
34
    //    只有在 C++ 中通过 LOCTEXT_FROM_STRING_TABLE 显式手动注册，
35
    //    或通过 CSV 硬编码注册时，ID 才是你指定的纯短名。
36
}
37

38
// ③ 在编辑器中切换预览语言：
39
//    编辑器右上角 → Editor Preferences → Region & Language →
40
//    Preview Game Language → 选择日语 → 所有 FText 立即切换到日语
41

42
// ===== StringTable 的工程优势 =====
43
// - CSV 可直接在 Excel / Google Sheets 中编辑
44
// - 本地化团队不需要安装 UE
45
// - 支持增量更新（只改一行，不影响其他）
46
// - 多个 Widget 共享同一个 Key → 修改一处，全局生效

1
// ===== UE 本地化的编译管线 =====
2
//
3
// ① 编译 C++ → UHT 发现所有 LOCTEXT/NSLOCTEXT 宏
4
// ② 生成 .manifest 文件 —— 列出所有需要翻译的文本
5
// ③ Gather 命令 → 合并已有翻译到 .po（Portable Object）文件
6
//    每个语言一个 .po 文件：
7
//      zh-Hans/Game.po, ja/Game.po, fr/Game.po ...
8
// ④ 翻译团队编辑 .po 文件
9
// ⑤ Compile 命令 → 将 .po 编译为 .locres 二进制文件
10
// ⑥ 打包时 .locres 被包含在构建中
11
// ⑦ 运行时：引擎根据当前 Culture 加载对应的 .locres
12

13
// ===== FInternationalization —— 运行时切换语言 =====
14
#include "Internationalization/Internationalization.h"
15

16
void SwitchToJapanese()
17
{
18
    FInternationalization::Get().SetCurrentCulture(TEXT("ja"));
19
}
20

21
void SwitchToChineseSimplified()
22
{
23
    FInternationalization::Get().SetCurrentCulture(TEXT("zh-Hans"));
24
}
25

26
// ⚠️ 切换语言后，之前已 SetText 的 FText 不会自动更新！
27
//   → 需要关闭并重新打开所有 Widget，或者手动重新 SetText
28
//   引擎内建的 UTextBlock / STextBlock 在语言切换时会自动刷新——
29
//   前提是你用的是 FText（不是 FString！）