Signal

概览

字段	值
Kind	Data · 数据 Data
Realm	common

Signal 是同端事件信号，可通过 Connect 持续监听、Once 单次监听，并用 Fire 传递一个可选参数。跨客户端与服务端的通信使用 RemoteEvent。

适用场景

常用于在模块间传递事件通知，例如在游戏逻辑中当某个状态变化时通知其他模块执行相应处理。

使用要点

通过 Signal.New() 或 Signal() 创建实例，调用 Connect 或 Once 注册监听函数，在需要时调用 Fire 触发事件并传递参数。监听不再需要时，应调用返回的 Connection 对象的 Disconnect 方法断开连接。

注意事项

Signal 仅限同端通信，不可跨客户端或服务器。Connect/Once 返回 Connection；持续监听不再需要时必须 Disconnect。公开 Meta 的 Fire 只声明一个可选 args 参数，需要传多项数据时请打包成单个 Table。

代码示例

创建 Signal 并持续监听

-- @runtime client
local signal = Signal.New()
local conn = signal:Connect(function(payload)
    print('收到触发:', payload)
end)
signal:Fire({ name = 'Eggy', score = 100 })
conn:Disconnect()

函数 (4)

New

签名：New() -> Signal (新创建的 Signal 实例)

创建一个新的 Signal 实例。

返回值 Signal (新创建的 Signal 实例)

示例代码

创建信号并连接/触发

-- @runtime client
local sig = Signal.New()
local conn = sig:Connect(function(msg)
    print('收到信号:', msg)
end)
sig:Fire('hello')  -- 触发，回调打印 '收到信号: hello'
conn:Disconnect()

Connect

签名：Connect(func: Function) -> Connection (可用于断开监听的连接句柄)

为信号连接一个监听函数，当信号被触发时该函数会被调用。

参数	类型	说明
func	Function	事件触发时调用的监听函数

返回值 Connection (可用于断开监听的连接句柄)

示例代码

持续监听并传递单个事件参数

-- @runtime client
local sig = Signal.New()
local conn = sig:Connect(function(payload)
    print('收到触发:', payload)
end)
sig:Fire({ name = 'Eggy', score = 100 })
conn:Disconnect()

Once

签名：Once(func: Function) -> Connection (可用于提前断开监听的连接句柄)

为信号连接一个只触发一次的监听函数，当信号第一次被触发时该函数会被调用，之后自动断开连接。

参数	类型	说明
func	Function	第一次事件触发时调用的监听函数

返回值 Connection (可用于提前断开监听的连接句柄)

示例代码

单次监听信号

-- @runtime client
-- 构造 Signal 实例
local signal = Signal()
-- 使用 Once 连接只触发一次的监听函数
signal:Once(function(msg)
    print("单次收到:", msg)
end)
-- 第一次触发，监听函数执行
signal:Fire("第一次触发")
-- 第二次触发，监听函数不再执行
signal:Fire("第二次触发")

Fire

签名：Fire(args?: Any) -> void

触发信号，所有通过 Connect 或 Once 连接的监听函数将被调用，并接收传入的参数。

参数	类型	说明
args?	Any	可选的单个事件参数，会转发给监听函数；需要多项数据时请传一个 Table。

返回值 void

示例代码

触发信号并在结束后释放持续监听

-- @runtime client
local sig = Signal.New()
local conn = sig:Connect(function(payload)
    print('收到参数:', payload)
end)
sig:Fire({ message = 'hello', count = 123 })
conn:Disconnect()