目录一SingleDeclaring DelegatesBinding DelegatesExecuting DelegatesExample Usage二Multicast三Dynamic委托可理解为是一种类型安全的函数指针容器存储目标对象及其成员函数的地址委托可动态绑定到任意对象的成员函数之后在该对象上调用函数即使调用者不知对象类型委托可很安全的复制也可值传递委托但这样操作需要在堆上分配内存因此通常并不推荐请尽量通过引用传递委托UE 共支持三种类型的委托SingleMulticastDynamic (UObject, serializable)注Event Dispatcher 为蓝图原生的委托本质上是动态多播委托蓝图中的内置事件一种是已绑定到动态多播委托上的回调函数UFUNCTION会在触发时调用Broadcasst()如OnComponentHit/OnComponentBeginOverlap、InputAction/EnhancedInputAction一种是 C 虚函数如BeginPlay、Tick、EndPlay、Destroyed如BeginPlay事件对应的是ReceiveBeginPlay()蓝图中的自定义事件只是普通函数UFUNCTION一SingleDeclaring Delegates使用宏声明委托根据绑定的函数签名来选择宏每个宏都包含新委托类型的名称返回类型如不是void及其参数委托签名声明可存在于全局范围内、命名空间内、甚至类声明内可能不存在于函数体内当前支持以下委托签名返回一个值的函数声明为 const 函数最多4个payload变量最多8个函数参数// 无返回值声明 void Function() --- DECLARE_DELEGATE(DelegateName) void Function(Param1) --- DECLARE_DELEGATE_OneParam(DelegateName, Param1Type) void Function(Param1, Param2) --- DECLARE_DELEGATE_TwoParams(DelegateName, Param1Type, Param2Type) void Function(Param1, Param2, ...) --- DECLARE_DELEGATE_NumParams(DelegateName, Param1Type, Param2Type, ...)// 有返回值声明 RetValType Function() --- DECLARE_DELEGATE_RetVal(RetValType, DelegateName) RetValType Function(Param1) --- DECLARE_DELEGATE_RetVal_OneParam(RetValType, DelegateName, Param1Type) RetValType Function(Param1, Param2) --- DECLARE_DELEGATE_RetVal_TwoParams(RetValType, DelegateName, Param1Type, Param2Type) RetValType Function(Param1, Param2, ...) --- DECLARE_DELEGATE_RetVal_NumParams(RetValType, DelegateName, Param1Type, Param2Type, ...)Binding Delegates将委托绑定到UObject或共享指针类的成员 委托系统可保留对该对象的弱引用因此该对象在代理之外被销毁时可通过调用IsBound()或ExecuteIfBound()函数进行判断委托绑定“对象实例 成员函数指针”函数应为公有的注意各类受支持对象的特殊绑定语法FunctionDescriptionBind绑定到现有委托对象BindStatic绑定原始C指针全局函数委托BindRaw绑定原始C指针委托由于原始指针不使用任何类型的引用因此在删除目标对象后调用Execute或ExecuteIfBound会不安全BindLambda绑定一个functor通常用于拉姆达函数BindSP绑定基于指针的共享成员函数委托共享指针委托会保留对对象的弱引用可使用ExecuteIfBound()进行调用BindUObject绑定UObject的成员函数委托UObject委托会保留对对象UObject的弱引用可使用ExecuteIfBound()进行调用UnBind取消绑定此委托注..\Engine\Source\Runtime\Core\Public\Delegates\DelegateSignatureImpl.inl 可了解这些函数的变体、参数和实现Payload Data在绑定到委托时可传递有效负载数据可以是任意变量在绑定函数被调用时会直接传递给任何绑定函数所有委托类型除“dynamic”外都自动支持有效负载变量// 此例将两个自定义变量一个布尔一个int32传递到委托 // 调用该委托时参数将被传到绑定函数额外的变量参数必须始终在委托类型参数之后被接受 MyDelegate.BindRaw( MyFunction, true, 20 );Executing Delegates通过调用委托的Execute()函数执行绑定到委托的函数执行前须检查委托是否已绑定以使代码更安全因为有时委托可能含有未初始化且被后续访问的返回值和输出参数 执行未绑定的委托在某些情况下确实可能导致内存混乱可调用IsBound()检查是否可安全执行委托 同时对于无返回值的委托可调用ExecuteIfBound()但需注意输出参数可能未初始化Execute // 执行一个委托而不检查其绑定情况 ExecuteIfBound // 检查委托是否已绑定如是则调用Execute IsBound // 检查委托是否已绑定通常在包含Execute调用的代码之前进行Example Usage// 假定类拥有可在任何地方随意调用的方法 class FLogWriter { public: void WriteToLog(FString); };// 首先需使用宏声明委托要调用 WriteToLog 函数需创建该函数签名的委托类型 // 创建名为 FStringDelegate 的委托类型使用单个参数 FString DECLARE_DELEGATE_OneParam(FStringDelegate, FString); class FMyClass { // 在类中创建 FStringDelegate 对象 FStringDelegate WriteToLogDelegate; };// 委托时只需创建委托类的实例将拥有该方法的类作为模板参数传递 // 传递对象的实例和实际函数地址 TSharedRefFLogWriter LogWriter(new FLogWriter()); WriteToLogDelegate.BindSP(LogWriter, FLogWriter::WriteToLog);// FMyClass 即可调用 WriteToLog 方法甚至无需了解 FLogWriter 类的任何信息 WriteToLogDelegate.Execute(TEXT(Delegates are great!)); // 多数情况下建议使用以下操作 WriteToLogDelegate.ExecuteIfBound(TEXT(Only executes if a function was bound!));二Multicast多播委托具有与单播委托大多数相同的功能仅对对象具有弱引用可与结构体一起使用可轻松地复制等与常规委托一样多播委托可以被加载/保存并可以远程触发但多播委托函数不能使用返回值// 声明多播委托与声明标准委托方式上相同 DECLARE_MULTICAST_DELEGATE[_RetVal, ...]\( DelegateName \) DECLARE_DYNAMIC_MULTICAST_DELEGATE[_RetVal, ...]\( DelegateName \)FunctionDescriptionAdd()将函数添加到该多播委托的调用列表中AddStatic()添加原始C指针全局函数委托AddRaw()添加原始C指针委托原始指针不使用任何类型的引用因此如果从委托下面删除了对象则调用此函数可能不安全。调用Execute()时请小心AddLambda()添加一个 functor通常用于那些不会捕获指针的lambda函数AddSPLambda()添加一个 functor只有在对目标共享指针的弱引用有效的情况下才会被调用AddWeakLambda()添加一个 functor只有在对UObject的弱引用有效的情况下才会被调用AddSP()添加基于共享指针的快速、非线程安全成员函数委托共享指针委托保留对对象的弱引用AddUObject()添加基于UObject的成员函数委托UObject委托保留对对象的弱引用Remove()从该多播委托的调用列表中删除函数性能为O(N)请注意委托的顺序可能不会被保留RemoveAll()从该多播委托的调用列表中删除绑定的所有函数请注意委托的顺序可能不会被保留删除绑定到所提供指针的所有已注册委托未绑定到对象指针的原始委托不会被该函数所删除注..\Engine\Source\Runtime\Core\Public\Delegates\DelegateSignatureImpl.inl 可了解这些函数的变体、参数和实现// 将该委托广播给所有绑定的对象 // 调用该函数总是安全的即使没有任何绑定时也是如此 // 唯一需要注意的是如使用委托来初始化输出变量通常会带来非常不利的后果 // 调用时绑定函数的执行顺序尚未定义执行顺序可能与函数的添加顺序不相同 Broadcast()三Dynamic动态委托可序列化且支持反射的委托其函数可按名称查找但其执行速度比常规委托慢其绑定的函数需使用UFUNCTUION()标记宏声明的类型名称必须以F开头// 声明动态委托与声明标准委托方式上相同 // 动态单播委托 DECLARE_DYNAMIC_DELEGATE[_RetVal, ...]\( DelegateName \) // 动态多播委托最常用支持蓝图 DECLARE_DYNAMIC_MULTICAST_DELEGATE[_RetVal, ...]\( DelegateName \)// 委托函数支持与UFunctions相同的说明符但是使用 UDELEGATE 宏而不是 UFUNCTION UDELEGATE(BlueprintAuthorityOnly) DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FInstigatedAnyDamageSignature, float, Damage, const UDamageType*, DamageType, AActor*, DamagedActor, AActor*, DamageCauser);FunctionDescriptionBindDynamic( UserObject, FuncName )用于在动态委托上调用BindDynamic()的辅助宏自动生成函数命名字符串AddDynamic( UserObject, FuncName )用于在动态多播委托上调用AddDynamic()的辅助宏自动生成函数命名字符串RemoveDynamic( UserObject, FuncName )用于在动态多播委托上调用RemoveDynamic()的辅助宏自动生成函数命名字符串// 执行动态委托 Execute // 执行一个委托而不检查其绑定情况 ExecuteIfBound // 检查委托是否已绑定如是则调用Execute IsBound // 检查委托是否已绑定通常在包含Execute调用的代码之前进行// Button.h 源代码头文件中声明的动态多播 DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnButtonClickedEvent); DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnButtonPressedEvent); DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnButtonReleasedEvent); DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnButtonHoverEvent);// UButton 成员变量 UPROPERTY(BlueprintAssignable, CategoryButton|Event) // BlueprintAssignable允许在蓝图中绑定事件 FOnButtonClickedEvent OnClicked;// .h 文件设置属性 UPROPERTY(EditAnywhere, BlueprintReadWrite, meta (BindWidget)) TObjectPtrUButton Start; UPROPERTY(EditAnywhere, BlueprintReadWrite, meta (BindWidget)) TObjectPtrUButton Quit; // .cpp 文件 bool UMyUserWidget::Initialize() { if(!Super::Initialize()) return false; Start-OnClicked.AddDynamic(this, UMyUserWidget::StartFunc); Quit-OnClicked.AddDynamic(this, UMyUserWidget::QuitFunc); return true; }四稀疏动态多播稀疏动态多播与标准的动态多播功能基本一致但核心区别在于它是一种内存优化方案标准动态多播包含该委托的对象无论是否有人监听都会为其分配存储调用列表的内存开销较大适用于高频触发、或绝大多数实例都会被监听的事件稀疏动态多播在没有人绑定时只占用1个字节的内存仅存储一个bIsBound标志只有当第一次有人绑定时才会在全局存储中创建真正的调用列表适用于低频触发、绝大多数实例不会被监听的事件// PrimitiveComponent.h 源代码头文件内声明的稀疏动态多播 DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_FiveParams( FComponentHitSignature, UPrimitiveComponent, OnComponentHit, UPrimitiveComponent*, HitComponent, AActor*, OtherActor, UPrimitiveComponent*, OtherComp, FVector, NormalImpulse, const FHitResult, Hit ); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_SixParams( FComponentBeginOverlapSignature, UPrimitiveComponent, OnComponentBeginOverlap, UPrimitiveComponent*, OverlappedComponent, AActor*, OtherActor, UPrimitiveComponent*, OtherComp, int32, OtherBodyIndex, bool, bFromSweep, const FHitResult , SweepResult); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_FourParams( FComponentEndOverlapSignature, UPrimitiveComponent, OnComponentEndOverlap, UPrimitiveComponent*, OverlappedComponent, AActor*, OtherActor, UPrimitiveComponent*, OtherComp, int32, OtherBodyIndex); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams(FComponentWakeSignature, UPrimitiveComponent, OnComponentWake, UPrimitiveComponent*, WakingComponent, FName, BoneName); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams(FComponentSleepSignature, UPrimitiveComponent, OnComponentSleep, UPrimitiveComponent*, SleepingComponent, FName, BoneName); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_OneParam(FComponentCollisionSettingsChangedSignature, UPrimitiveComponent, OnComponentCollisionSettingsChangedEvent, UPrimitiveComponent*, ChangedComponent); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams(FComponentPhysicsStateChanged, UPrimitiveComponent, OnComponentPhysicsStateChanged, UPrimitiveComponent*, ChangedComponent, EComponentPhysicsStateChange, StateChange); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_OneParam( FComponentBeginCursorOverSignature, UPrimitiveComponent, OnBeginCursorOver, UPrimitiveComponent*, TouchedComponent ); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_OneParam( FComponentEndCursorOverSignature, UPrimitiveComponent, OnEndCursorOver, UPrimitiveComponent*, TouchedComponent ); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams( FComponentOnClickedSignature, UPrimitiveComponent, OnClicked, UPrimitiveComponent*, TouchedComponent , FKey, ButtonPressed); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams( FComponentOnReleasedSignature, UPrimitiveComponent, OnReleased, UPrimitiveComponent*, TouchedComponent, FKey, ButtonReleased); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams( FComponentOnInputTouchBeginSignature, UPrimitiveComponent, OnInputTouchBegin, ETouchIndex::Type, FingerIndex, UPrimitiveComponent*, TouchedComponent ); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams( FComponentOnInputTouchEndSignature, UPrimitiveComponent, OnInputTouchEnd, ETouchIndex::Type, FingerIndex, UPrimitiveComponent*, TouchedComponent ); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams( FComponentBeginTouchOverSignature, UPrimitiveComponent, OnInputTouchEnter, ETouchIndex::Type, FingerIndex, UPrimitiveComponent*, TouchedComponent ); DECLARE_DYNAMIC_MULTICAST_SPARSE_DELEGATE_TwoParams( FComponentEndTouchOverSignature, UPrimitiveComponent, OnInputTouchLeave, ETouchIndex::Type, FingerIndex, UPrimitiveComponent*, TouchedComponent );// UPrimitiveComponent 成员变量 FComponentBeginOverlapSignature OnComponentBeginOverlap;// 调用 AddDynamic 绑定组件的重叠事件 // 触发重叠事件还需双方都开启Generate Overlap Events碰撞预设为Overlap静态网格体要有碰撞体 // AddDynamic()辅助宏用于动态多播委托实际调用__Internal_AddDynamic myCube-OnComponentBeginOverlap.AddDynamic(this, AMyActor::OnOverlapBegin); // 回调函数必须标记UFUNCTION()且参数完全一致 UFUNCTION() void OnOverlapBegin(UPrimitiveComponent* OverlappedComponent, AActor* OtherActor, UPrimitiveComponent* OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult SweepResult);