属性绑定¶

Markup UI 原生支持将可观察对象绑定到 UI，在属性或集合发生变化时更新界面，具体用法见可观察对象与集合。

对于 Unreal Engine，还支持将原生 UObject 作为页面的数据上下文，绑定其反射属性，包括数值、字符串、对象引用、USTRUCT 以及 TArray、TMap、TSet 等原生集合。数据上下文的基本概念见数据上下文。

属性绑定的支持范围¶

数据上下文可以是已有的 UObject、Actor 或其他 UObject 派生对象，也可以是蓝图对象。Markup UI 通过 Unreal Engine 的反射系统读取属性；C++ 字段需要声明为 UPROPERTY，蓝图中则可使用对象的变量。

UPROPERTY¶

例如，对象中声明以下属性：

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Player")
int32 Health = 100;

HTML 使用属性名读取其值：

<p>Health: {{ Health }}</p>

使用属性的实际名称编写绑定。需要从蓝图访问时，使用适当的蓝图可见性设置；双向绑定要求属性可写，BlueprintReadOnly 和只读属性不能作为写回目标。

Get/Set UFUNCTION¶

除变量外，也可以通过公开的 Unreal 反射函数提供属性。GetHealth() 对应绑定名称 Health；可选的 SetHealth(...) 允许写回：

UFUNCTION(BlueprintCallable, Category = "Player")
int32 GetHealth() const;

UFUNCTION(BlueprintCallable, Category = "Player")
void SetHealth(int32 Value);

• Getter：不接收参数，返回一个受支持类型的值。
• Setter：接收一个参数，其类型必须与 Getter 的返回类型相同；不返回值。

只有 Getter 时，属性为只读；只有 Setter、没有 Getter 时，无法通过这组函数绑定属性。如果存在同名 UPROPERTY，绑定优先使用该属性。

UPROPERTY 也可以通过 BlueprintGetter 和 BlueprintSetter 指定访问函数。绑定使用属性名，并通过指定的函数读取或写入：

UFUNCTION(BlueprintGetter)
int32 GetHealth() const;

UFUNCTION(BlueprintSetter)
void SetHealth(int32 Value);

UPROPERTY(BlueprintGetter = GetHealth, BlueprintSetter = SetHealth)
int32 Health = 100;

支持的数据类型¶

标量写回仍受属性可写性和 Getter／Setter 配置限制。TOptional<T> 的内部类型不能是集合或结构体。软对象引用和委托不支持属性绑定。

USTRUCT¶

USTRUCT 是值类型，不是独立的 UObject。绑定时需要注意：

• 成员读取：使用 Profile.Level 这样的路径；自定义结构体需要声明为 USTRUCT，供绑定读取的成员需要声明为 UPROPERTY。
• 只读访问：结构体及其成员不支持双向写回，即使成员声明了 BlueprintReadWrite。
• 变更通知：修改成员后，通知所属 UObject 的整个结构属性，例如 Profile，而不是发送 Profile.Level 通知。
• 集合元素：修改数组或字典中的结构体元素时，发送该元素的替换通知。
• 内置结构体：FVector、FColor、FLinearColor 等也按结构体读取，适用相同的只读和通知规则。

例如，定义一个包含等级的结构体，并将其作为数据对象的属性：

USTRUCT(BlueprintType)
struct FPlayerProfile
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Player")
    int32 Level = 1;
};

在数据对象类中声明：

UCLASS(BlueprintType)
class UPlayerData : public UObject
{
    GENERATED_BODY()

public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Player")
    FPlayerProfile Profile;
};

HTML 按成员路径读取：

<p>等级：{{ Profile.Level }}</p>

游戏代码修改成员后，为 Profile 发送通知：

#include "Binding/UObjectBinding.h"
#include "PlayerData.h"

PlayerData->Profile.Level = 2;
MarkupUI::Binding::NotifyPropertyChanged(
    PlayerData, GET_MEMBER_NAME_CHECKED(UPlayerData, Profile));

蓝图中修改结构成员后，同样调用 Notify Property Changed，将 Object 连接到数据对象，将 Property Name 设为 Profile。

下方示例中的 PlayerData 代表已有的数据对象，假设它具有 Health、Items、Scores 和 Tags 属性。

设置数据上下文¶

#include "UMG/MarkupUIWidget.h"
#include "PlayerData.h"

// Widget 和 PlayerData 分别指向已有的 MarkupUIWidget 和数据对象。
Widget->SetDataContext(PlayerData);

对象生命周期¶

Reference Mode 支持以下引用方式：

• Weak（默认）：MarkupUIWidget 不会阻止数据对象被 GC。请由游戏中的其他对象通过有效的 Unreal 引用持有数据对象，确保页面使用期间对象仍然有效。
• Strong：MarkupUIWidget 持有数据对象的强引用，阻止对象被 GC。清除上下文或替换为其他对象时，对该上下文的持有随之更新。

命名数据上下文¶

使用 Set Named Data Context 或 C++ 的 SetNamedDataContext 设置带名称的上下文：

Widget->SetNamedDataContext(TEXT("player"), PlayerData);

在页面中通过 @context="player" 选择它。使用 Reset Data Context 清除默认上下文，使用 Reset Named Data Context 清除指定名称的上下文；名称和页面中的写法必须一致。

原生集合¶

作为 UObject 属性声明的集合可以直接用于绑定：

集合元素必须是绑定支持的类型，不能直接嵌套原生集合。TMap 的键支持字符串和整数类型；集合绑定语法见集合绑定。

属性更改通知¶

游戏代码或蓝图修改数据对象后，需要发送属性更改通知，页面绑定才能重新读取该属性。首次绑定时读取当前值，不要求为初始赋值预先发送通知。

FieldNotify¶

支持 FieldNotify 的对象发出字段广播后，插件会自动更新对应绑定，无需重复发送手动通知。接入步骤及 C++ / 蓝图示例见UMG Viewmodel。

手动通知¶

#include "MarkupUISdk.h" // Markup UI 的 SDK 和 Unreal Engine 绑定接口。
#include "PlayerData.h"

// PlayerData 指向页面正在使用的数据对象。
PlayerData->Health = 80;
MarkupUI::Binding::NotifyPropertyChanged(
    PlayerData, GET_MEMBER_NAME_CHECKED(UPlayerData, Health));

集合更改通知¶

直接对 TArray、TMap 或 TSet 调用普通修改操作不会自动通知页面。修改已绑定的集合时，使用插件提供的集合操作，或在修改时发送相应通知。

集合通知分为以下类型：

• 新增（Add）：创建并显示新增元素，保留其他元素。
• 删除（Remove）：移除对应元素的 UI，保留其他元素。
• 替换（Replace）：更新被替换元素对应的 UI，保留其他元素。
• 移动（Move）：调整对应元素的显示位置。
• 重置（Reset）：重新读取整个集合并刷新列表。

C++¶

#include "CoreMinimal.h"
// 必须引入 UE 专用 SDK 头文件，提供 UE 类型适配并支持编译期类型检查。
#include "MarkupUISdk.h"

// 将可观察集合保存在页面使用的 C++ 数据模型中。
TArray<int32> InitialNumbers{10, 20};
MarkupUI::Binding::Modeling::ObservableArray<int32> Numbers =
    MarkupUI::Binding::Modeling::ObservableArray<int32>::From(
        MoveTemp(InitialNumbers));
Numbers.Add(30);
Numbers.Set(0, 15);
Numbers.RemoveAt(1);

#include "MarkupUISdk.h"
#include "PlayerData.h"

// PlayerData->Items: TArray<FString>
// PlayerData->Scores: TMap<FString, int32>
// PlayerData->Tags: TSet<FString>
// These are the original collection properties on PlayerData.

MarkupUI::NotifyCollection::From(PlayerData->Items).Add(TEXT("Potion"));
MarkupUI::NotifyCollection::From(PlayerData->Scores).Add(TEXT("Level"), 2);
MarkupUI::NotifyCollection::From(PlayerData->Tags).Add(TEXT("Ready"));

#include "Binding/UObjectCollectionNotifications.h"
#include "PlayerData.h"

// PlayerData->Items: TArray<FString>
// PlayerData->Scores: TMap<FString, int32>
// PlayerData->Tags: TSet<FString>
// These are the original collection properties on PlayerData.

MarkupUI::BeginArrayAdd(PlayerData->Items);
PlayerData->Items.Add(TEXT("Potion"));
MarkupUI::EndArrayAdd(PlayerData->Items);

if (PlayerData->Items.IsValidIndex(0))
{
    MarkupUI::BeginArrayRemove(PlayerData->Items, 0);
    PlayerData->Items.RemoveAt(0);
    MarkupUI::EndArrayRemove(PlayerData->Items);
}

const FString Key = TEXT("Level");
MarkupUI::BeginMapAdd(PlayerData->Scores, Key);
PlayerData->Scores.Add(Key, 2);
MarkupUI::EndMapAdd(PlayerData->Scores);

PlayerData->Tags.Add(TEXT("Ready"));
MarkupUI::NotifySetChanged(PlayerData->Tags);

对 Unreal Engine 原生集合的修改和通知应在游戏线程进行，并始终操作被绑定的原始集合。

蓝图¶

在蓝图中选择带 (Markup UI) 后缀的集合修改节点，例如数组的 Add (Markup UI)，并将目标连接到数据对象的集合属性。节点执行集合修改并发送通知。

具体节点与选择方式见下方“Markup UI 蓝图扩展节点”。

Markup UI 蓝图扩展节点¶

从数组属性引脚拖出连线，可在 Markup UI → Array 中选择带 (Markup UI) 后缀的操作：

对 TMap、TSet 使用相应带 (Markup UI) 后缀的节点。节点需要操作对象上的原始集合属性，不要使用返回副本的函数结果。

Markup UI 节点的右上角带有蓝色标记，用于与 Unreal Engine 原生集合节点区分。下图中，上方节点会在修改集合时发送通知；下方原生节点只修改集合，不会自动发送 Markup UI 通知。

1. 从数据对象取得 Items 属性，并连接到数组节点的 Target Array。
2. 为 Add (Markup UI) 提供要添加的元素。
3. 执行该节点后，绑定的列表会收到集合变化通知。

Array 节点

Map 节点

Set 节点

Array 和 Set 节点由当前 Unreal Engine 版本提供的集合函数生成，具体可用节点可能随引擎版本变化。上述名称以 Unreal Engine 5.8 为参考；读取集合时可使用 Unreal Engine 原生查询节点。