监听聊天室事件

聊天室业务为客户端 App 提供三种类型的事件监听器：聊天室状态监听器、聊天室成员变化监听器、聊天室事件通知监听器。

通过 IMLib SDK 提供的以上委托，您可以从融云服务端获取聊天室销毁状态、用户在当前及其他客户端加入退出聊天室的状态、聊天室中成员进出的事件通知、以及聊天室中成员禁言、封禁相关的信息。

监听器	名称	说明
ChatroomStatusListener*	聊天室状态监听器	接收在当前客户端登录的用户加入、退出聊天室的事件与聊天室销毁状态的信息。
ChatroomMemberActionListener	聊天室成员变化监听器	接收当前用户所在聊天室中其他用户加入、退出聊天室的信息。
ChatroomNotifyEventListener	聊天室事件通知监听器	接收当前所在聊天室中成员禁言、封禁相关的信息；接收当前用户在其他端加入、退出聊天室相关的信息。

监听聊天室状态

您可以使用 setChatroomStatusListener 设置聊天室状态监听器来监听当前用户加入、退出聊天室的事件与已加入的聊天室销毁状态。。

接口原型

TypeScript

interface ChatroomStatusListener {
    /**
     * 开始加入聊天室的回调
     * @param roomId 聊天室 id
     */
    onChatroomJoining(roomId: string): void;
    /**
     * 加入聊天室成功的回调
     * @param roomId 聊天室 id
     * @param info 加入的聊天室信息
     */
    onChatroomJoined(roomId: string, info: ChatroomJoinedInfo): any;
    /**
     * 加入聊天室失败的回调
     * @param roomId 聊天室 id
     * @param code 加入失败的错误码
     * @discussion 如果 code 是 ChatroomKicked 或 ChatroomNotExist，则不会自动重新加入聊天室，App 需要按照自己的逻辑处理
     */
    onChatroomJoinFailed(roomId: string, code: EngineError): any;
    /**
     * 退出聊天室成功的回调
     * @param roomId 聊天室 id
     */
    onChatroomQuited(roomId: string): any;
    /**
     * 聊天室被销毁的回调，用户在线的时候房间被销毁才会收到此回调
     * @param roomId 聊天室 id
     * @param type 聊天室销毁原因
     */
    onChatroomDestroyed(roomId: string, type: ChatroomDestroyType): any;
}

示例代码

TypeScript

let listener: ChatroomStatusListener = {
        onChatroomJoining(roomId: string): void {
        },

        onChatroomJoined(roomId: string, info: ChatroomJoinedInfo): void {
        },

        onChatroomJoinFailed(roomId: string, code: EngineError): void {
        },

        onChatroomQuited(roomId: string): void {
        },

        onChatroomDestroyed(roomId: string, type: ChatroomDestroyType): void {
        },
      }
      IMEngine.getInstance().setChatroomStatusListener(listener);

监听聊天室成员变化

提示

SDK 从 1.1.0 版本开始支持监听聊天室成员变化。

从 1.1.0 版本，SDK 开始新增 ChatroomMemberActionListener，支持当前登录用户监听所在聊天室中其它成员的加入、退出行为。

开通服务

您可以在融云控制台 IM 服务的服务配置页面，通过 聊天室>聊天室成员变化监听 开启此功能。开启后，用户加入、退出聊天室后，系统会使用消息的方式向聊天室中的其他成员发送回调通知，消息量会因此增加。

设置聊天室成员变化监听器

示例代码

TypeScript

let listener: ChatroomMemberActionListener = {

  onMemberChange: (actionModel: ChatRoomMemberActionModel): void => {
  }

}
IMEngine.getInstance().setChatroomMemberListener(listener);

如果当前用户由于网络原因和聊天室断开连接，则无法监听到断开连接期间的其他成员的加入、退出行为。

监听聊天室事件通知

提示

SDK 从 1.1.0 开始支持监听聊天室事件通知。

应用程序可以监听当前聊天室中成员禁言、封禁相关的通知，以及当前用户在其他端加入、退出聊天室相关的通知。

示例代码

TypeScript

let listener: ChatroomNotifyEventListener = {

  onChatroomNotifyMultiLoginSync: (syncEvent: ChatroomSyncEvent): void => {
  },

  onChatroomNotifyBlock: (blockEvent: ChatroomMemberBlockEvent): void => {
  },

  onChatRoomNotifyBan: (banEvent: ChatroomMemberBanEvent): void => {
  }
}
IMEngine.getInstance().setChatroomNotifyEventListener(listener);

方法说明

回调方法	触发时机	说明
onChatroomNotifyMultiLoginSync	在用户在多端登录情况下，在其他客户端加入、退出聊天室	接收在当前客户端上用户加入、退出聊天室的事件
onChatroomNotifyBlock	用户所在聊天室中发生了禁言、解除禁言相关的事件	是否接收通知取决于调用服务端封禁、解封的相关 API 时是否指定了 needNotify 为 true。
onChatRoomNotifyBan	用户所在聊天室发生了封禁用户、解除封禁相关的事件	是否接收通知取决于调用服务端封禁、解封的相关 API 时是否指定了 needNotify 为 true。

多端登录事件通知

在用户在多端登录情况下，在其他客户端加入、退出聊天室时，触发 onChatroomNotifyMultiLoginSync 方法。

触发场景	通知范围	说明
用户多端登录，在一台设备上加入聊天室	当前加入的用户	当前用户在一端加入聊天室时，其他端的在线设备上会接收通知，不在线的设备不会通知。返回数据包括：聊天室 ID、加入时间。
用户多端登录，在一台设备上退出聊天室	当前退出的用户	当前用户在一端退出聊天室时，其他端的在线设备上会接收通知，不在线的设备不会通知。 返回数据包括：聊天室 ID、退出时间。
用户多端登录且已在聊天室中，加入一个新的聊天室导致被踢出上一个聊天室	当前用户，和被踢出的聊天室所有成员	如果在控制台开通了单个用户加入多个聊天室，则不会通知。返回数据包括：聊天室 ID、被踢出的时间。

ChatRoomSyncEvent 具体属性定义如下：

TypeScript

/**
 * 聊天室同步事件，事件发生时，当前用户在线时能收到该事件
 * @discussion 事件发生时，当前用户不在线，那么用户上线后，不会收到该事件。
 * @version 1.1.0
 */
class ChatroomSyncEvent {
  /**
   * 聊天室 ID
   */
  chatroomId: string = "";
  /**
   * 同步通知的变更状态
   */
  status: ChatroomSyncStatus;
  /**
   * status 是 Quit 的情况， reason 区分离开类型： LeaveOnMyOwn，自己主动离开， OtherDeviceLogin，多端加入互踢导致离开
   *
   * status 是 Join 的情况，无需关心 reason 值
   */
  reason: ChatroomSyncStatusReason;
  /**
   * 用户加入/退出/被踢的时间戳，精确到毫秒
   */
  time: number;

  /**
   * 附加信息
   */
  extra: string = "";
}

封禁相关事件通知

用户所在聊天室发生了封禁、解封的事件，且调用相关 Server API 时指定了需要通知（指定 needNotify 为 true），SDK 会触发 onChatroomNotifyBlock 方法。

触发场景	通知范围	说明
封禁聊天室用户	聊天室中所有成员	返回数据包括：聊天室 ID、被封禁成员用户 ID 列表、封禁时间与持续时长、附加信息。
解除封禁聊天室用户	被解除封禁的成员	返回数据包括：聊天室 ID、当前用户 ID、附加信息。

ChatroomMemberBlockEvent 具体属性定义如下：

TypeScript

/**
 * 聊天室成员封禁事件
 * ```
 * 本事件只能通过 ServerApi 触发，端上只能被动接收到该事件
 * 事件发生时，当前用户在线时能收到该事件
 * 事件发生时，当前用户不在线，那么用户上线后，不会收到该事件。
 * ```
 * @version 1.1.0
 */
class ChatroomMemberBlockEvent {
  /**
   *  聊天室 Id
   */
  chatroomId: string = "";
  /**
   * 封禁类型
   */
  operateType: ChatroomBlockOperateType;
  /**
   *  封禁时长，单位为毫秒，最大值为43200分钟（1个月）, 最小值1分钟。 operateType 为 Blocked 时，该字段有效
   */
  durationTime: number;
  /**
   * 操作时间(毫秒时间戳)
   */
  operateTime: number;
  /**
   * 被封禁/解封的用户 ID 列表
   */
  userIdList: List<string>;
  /**
   * 附加信息
   */
  extra: string = "";
}

/**
 * 聊天室封禁类型
 */
enum ChatroomBlockOperateType {
  /**
   * 解封
   */
  Unblock = 0,
  /**
   * 封禁
   */
  Blocked = 1,
}

禁言相关事件通知

用户所在聊天室发生了禁言、解除禁言相关的事件，且调用相关 Server API 时指定了需要通知（指定 needNotify 为 true），SDK 会触发 onChatRoomNotifyBan 方法。

触发场景	通知范围	说明
禁言指定聊天室用户	聊天室中所有成员	返回数据包括：聊天室 ID、被封禁成员用户 ID 列表、禁言时间与持续时长、附加信息。
取消禁言指定聊天室用户	聊天室中所有成员	返回数据包括：聊天室 ID、被封禁成员用户 ID 列表、解除禁言时间、附加信息。
设置聊天室全体禁言	聊天室中所有成员	返回数据包括：聊天室 ID、禁言时间、附加信息。
取消聊天室全体禁言	聊天室中所有成员	返回数据包括：聊天室 ID、解除禁言时间、附加信息。
加入聊天室全体禁言白名单	聊天室中所有成员	返回数据包括：聊天室 ID、被添加白名单的用户 ID 列表、设置白名单时间、附加信息。
移出聊天室全体禁言白名单	聊天室中所有成员	返回数据包括：聊天室 ID、被移出白名单的用户 ID 列表、移出白名单时间、附加信息。
全局禁言用户	被全局禁言的用户	返回数据包括：聊天室 ID、禁言时间与持续时长、附加信息。
取消全局禁言用户	被解除全局禁言的用户	返回数据包括：聊天室 ID、解除禁言时间、附加信息。

ChatroomMemberBanEvent 具体属性定义如下：

TypeScript

/**
 * 聊天室禁言事件
 * ```
 * 本事件只能通过 ServerApi 触发，端上只能被动接收到该事件
 * 事件发生时，当前用户在线时能收到该事件
 * 事件发生时，当前用户不在线，那么用户上线后，不会收到该事件
 * ```
 * @version 1.1.0
 */
class ChatroomMemberBanEvent {
  /**
   * 聊天室 Id
   */
  chatroomId: string = "";
  /**
   * 禁言操作类型
   */
  banType: ChatroomMemberBanType;
  /**
   * 禁言时长，单位为毫秒：最大值为43200分钟（1个月）, 最小值1分钟。 banType 为 禁言 类型时，该字段有效
   */
  durationTime: number;
  /**
   * 操作时间(毫秒时间戳)
   */
  operateTime: number;
  /**
   * 被禁言/解禁言的用户 ID 列表
   */
  userIdList: List<string>;
  /**
   * 附加信息
   */
  extra: string = "";
}

/**
 * 聊天室禁言/解除禁言操作类型枚举
 */
enum ChatroomMemberBanType {
  /**
   * 解除指定聊天室中用户禁言
   */
  UnmuteUsers = 0,
  /**
   * 禁言指定聊天室中用户
   */
  MuteUsers = 1,
  /**
   * 解除聊天室全体禁言
   */
  UnmuteAll = 2,
  /**
   * 聊天室全体禁言
   */
  MuteAll = 3,
  /**
   * 移出禁言用户白名单
   */
  RemoveWhitelist = 4,
  /**
   * 添加禁言用户白名单
   */
  AddWhitelist = 5,
  /**
   * 解除用户聊天室全局禁言
   */
  UnmuteGlobal = 6,
  /**
   * 用户聊天室全局禁言
   */
  MuteGlobal = 7,
}