通道 Realm 领域手册

通道

通道，是一个可以发送和接收信息的管道。它的主要用途是，批量向客户端发送信息，从而实现状态更新、消息通知等功能。

例如，在一个 2D 游戏中，服务端定时向通道中发送玩家当前所在的位置，客户端组件接收到该位置后，更新组件内容，从而达到状态同步的效果。

通道是跨脚本、跨玩家的，只要通道名称相同，就可以发送和接收信息。这就意味着，通道可以在不同环境、不同玩家之间实时传递信息。

通过 通道(通道名称) 加载一个通道。注意，由于所有玩家共享一个通道，如果你希望只向单个玩家发送信息，那么通道名称应该包含玩家的 id。

var 测试通道 = 通道('测试');

通过 xxx.发送(内容) 向通道发送一条信息。内容可以是文本、数字、对象、数组等。

服务端和客户端都可以发送信息。发送信息后，所有侦听了该通道的客户端都将收到这条信息。

var 测试通道 = 通道('测试');
测试通道.发送('测试信息！');
测试通道.发送();  // 也可以发送空信息

在客户端运行环境中，可以接收通道信息。

通过 xxx.当收到信息时(...) 接收服务端发送的通道信息。当收到来自领域服务端发送的信息时，执行传入的函数。

var 测试通道 = 通道('测试');
测试通道.当收到信息时((信息) => {
    提示('收到一条信息：' + 信息);
});

通过 xxx.当收到客户端信息时(...) 接收客户端发送的通道信息。当收到自己或其它客户端发送的信息时，执行传入的函数。有作弊意图的客户端有可能发送不正确的信息。

var 测试通道 = 通道('测试');
测试通道.当收到客户端信息时((信息) => {
    提示('收到一条客户端信息：' + 信息);
});

在服务端环境下，不能接收通道信息。但是可以通过对外接口函数，接收客户端的信息。具体请查看“客户端环境”章节。

当调用xxx.当收到信息时(...)和xxx.当收到客户端信息时(...) 时，会返回一个取消接收通道信息的函数，调用该函数后，通道将不再接收信息。

var 测试通道 = 通道('测试');
var 取消接收函数 = 测试通道.当收到信息时((信息) => {
    提示('收到一条信息：' + 信息);
});
// 执行函数后，该通道将不再接收信息
取消接收函数()

你可以设置组件的“刷新通道”。当该通道收到任意服务端发送的信息后，将会刷新该组件及其子组件。

例如，将一个组件的刷新通道设置为“测试”。当“测试”通道收到任意信息后，将会更新该组件的内容。

// 服务端环境下
var 测试通道 = 通道('测试');
测试通道.发送();  // 向该通道发送信息后，组件将自动刷新

通过这种方法，可以达到 UI 实时更新的效果。例如，为聊天室所在组件设置刷新通道，当有用户发言时，向该通道发送一条信息，其它用户的界面上就会显示新的发言。

但是，要注意性能问题。组件每次接收到通道的信息，都会被刷新一次。因此，应当避免直接刷新最外层组件，而是根据需要刷新特定的内层组件。

一个有作弊意图的客户端，可以侦听任意名称的通道。如果不希望某个通道的内容被其它客户端窃听，可以由服务端生成一段随机的文本作为通道名称，事先通过参数传值给客户端脚本组件。