MulticastSparseDelegateProperty

MulticastSparseDelegateProperty

表示 Unreal Engine 中的稀疏多播委托属性。

继承关系

Property

说明

MulticastSparseDelegateProperty 封装了 Unreal Engine 的 FMulticastSparseDelegateProperty，后者表示采用稀疏存储的多播委托。当委托经常处于未绑定状态时，这种存储方式可节省内存：对象中只存储一个 1 字节标志，实际调用列表则存放在全局存储区。

尽管存储机制不同，其 API 与 MulticastDelegateProperty 完全相同。

访问委托属性

访问 UObject 上的稀疏多播委托属性时，会返回一个属性包装器对象，该对象提供修改委托的方法（API 与内联多播委托相同）：

local PlayerPawn = GetPlayerController().Pawn

-- Access delegate property (returns property wrapper)
local delegateProp = PlayerPawn.OnEndPlay

-- The wrapper has Add, Remove, and Clear methods
delegateProp:Add(MyCustomObject, FName("OnActorEndPlay"))

方法

Add(targetObject, functionName)

向稀疏多播委托的调用列表添加一个委托绑定。

  • 参数：
    • targetObject（UObject）：要绑定委托的对象
    • functionName（FName | string）：要在目标对象上调用的函数名称
-- Access the delegate property wrapper
local prop = PlayerPawn.OnEndPlay

-- Add a delegate binding using FName
prop:Add(MyCustomObject, FName("OnActorEndPlay"))

-- Or use a string directly
prop:Add(MyCustomObject, "OnActorEndPlay")

Remove(targetObject, functionName)

从调用列表中移除指定的委托绑定。

  • 参数：
    • targetObject（UObject）：委托绑定到的对象
    • functionName（FName | string）：已绑定函数的名称
-- Remove a specific binding
prop:Remove(MyCustomObject, FName("OnActorEndPlay"))

-- Or use a string
prop:Remove(MyCustomObject, "OnActorEndPlay")

Clear()

从调用列表中移除所有委托绑定。

-- Clear all bindings
prop:Clear()

GetBindings()

返回当前所有委托绑定组成的数组。

  • 返回值： 表数组，每个表含有 Object（UObject）和 FunctionName（FName）字段；若不存在绑定则返回 nil
-- Get all current bindings
local bindings = prop:GetBindings()
if bindings then
    print("Delegate has", #bindings, "bindings")
    for i, binding in ipairs(bindings) do
        print(string.format("[%d] %s::%s",
            i,
            binding.Object:GetFullName(),
            binding.FunctionName:ToString()))
    end
end

Broadcast(...)

触发委托，并使用给定参数调用所有已绑定函数。

  • 参数： 可变参数，取决于委托的签名函数
  • 注意： 参数的类型和顺序必须与委托签名的预期一致
-- For a delegate with no parameters (e.g., Actor.OnEndPlay)
prop:Broadcast()

-- For a delegate with parameters
prop:Broadcast(25.0, CauserActor)

实现细节

引擎中的 FMulticastSparseDelegateProperty 继承自 FMulticastDelegateProperty，因此可使用相同的所有虚函数表函数（AddDelegate、RemoveDelegate、ClearDelegate），且行为一致。

注意事项

  • 访问稀疏委托属性的 Object.PropertyName 会返回属性包装器，而不是委托值
  • 容器对象已隐式存储在包装器中，因此调用方法时无需传入容器对象
  • 函数名称可使用 FName 或字符串字面量
  • 存储机制对 Lua 透明，API 与内联多播委托完全相同
  • 常见示例：Actor.OnEndPlay 是一个 MulticastSparseDelegateProperty

原文：docs/lua-api/classes/multicastsparsedelegateproperty.md · 固定提交 560411f18512 · 来源与 MIT 许可