创建和管理聊天室以及监听事件

大约 6 分钟

创建和管理聊天室以及监听事件

聊天室是支持多人沟通的即时通讯系统。聊天室中的成员没有固定关系，一旦离线后，不会收到聊天室中的任何消息，超过 2 分钟会自动退出聊天室。聊天室可以应用于直播、消息广播等。若需调整该时间，需联系环信商务经理。

本文介绍如何使用环信即时通讯 IM SDK 在实时互动 app 中创建和管理聊天室，并实现聊天室的相关功能。

消息相关内容见 消息管理。

技术原理

环信即时通讯 IM SDK 提供 ChatRoomManager、ChatRoom 和 ChatRoomEventListener 类用于聊天室管理，支持你通过调用 API 在项目中实现如下功能：

  • 创建聊天室
  • 加入聊天室
  • 获取聊天室详情
  • 解散聊天室
  • 监听聊天室事件
  • 实时更新聊天室成员人数

前提条件

开始前，请确保满足以下条件：

  • 完成 SDK 初始化，详见 初始化文档。
  • 了解环信即时通讯 IM 的 使用限制。
  • 了解环信即时通讯 IM 不同版本的聊天室相关数量限制，详见 环信即时通讯 IM 价格open in new window。
  • 只有超级管理员才有创建聊天室的权限，因此你还需要确保已调用 RESTful API 添加了超级管理员，详见 添加聊天室超级管理员。
  • 聊天室创建者和管理员的数量之和不能超过 100，即管理员最多可添加 99 个。

实现方法

本节介绍如何使用环信即时通讯 IM SDK 提供的 API 实现上述功能。

创建聊天室

仅 超级管理员 可以调用 createChatRoom 方法创建聊天室，并设置聊天室的名称、描述、最大成员数等信息。成功创建聊天室后，该超级管理员为该聊天室的所有者。

建议直接调用 REST API 从服务端创建聊天室。

示例代码如下：

// 聊天室名称，不能超过 128 个字符
const subject = "";
// 聊天室描述， 不能超过 512 个字符
const desc = "this is room description.";
// 欢迎消息
const welcomeMsg = "welcome to you.";
// 聊天室成员列表
const members = ["Tom", "Json"];
// 最大成员数
const maxCount = 10000;
ChatClient.getInstance()
  .roomManager.createChatRoom(subject, desc, welcomeMsg, members, maxCount)
  .then(() => {
    console.log("get room success.");
  })
  .catch((reason) => {
    console.log("get room fail.", reason);
  });

加入聊天室

用户申请加入聊天室的步骤如下：

  1. 调用 fetchPublicChatRoomsFromServer 方法从服务器获取聊天室列表，查询到想要加入的聊天室 ID。
  2. 调用 joinChatRoomEx 方法传入聊天室 ID，申请加入对应聊天室。该接口支持加入时设置扩展信息，决定是否退出所有聊天室。加入后，聊天室中的其他成员会收到 ChatRoomEventListener#onMemberJoined 事件。

示例代码如下：

ChatClient.getInstance()
  .chatManager.joinChatRoomEx({
    roomId: "foo",
    exitOtherRoom: false,
    ext: "test",
  })
  .then(() => {
    console.log("success");
  })
  .catch((e) => {
    console.warn("fail:", e);
  });

获取聊天室详情

聊天室所有成员均可调用 fetchChatRoomInfoFromServer 获取聊天室的详情，包括聊天室 ID、聊天室名称，聊天室描述、聊天室公告、管理员列表、最大成员数、聊天室所有者、是否全员禁言以及聊天室权限类型。成员列表、黑名单列表、禁言列表需单独调用接口获取。

示例代码如下：

ChatClient.getInstance()
  .roomManager.fetchChatRoomInfoFromServer(roomId)
  .then((info) => {
    console.log("get room info success.", info);
  })
  .catch((reason) => {
    console.log("get room info fail.", reason);
  });

也可以从本地获取聊天室信息。

示例代码如下：

ChatClient.getInstance()
  .roomManager.getChatRoomWithId(roomId)
  .then((info) => {
    console.log("get room info success.", info);
  })
  .catch((reason) => {
    console.log("get room info fail.", reason);
  });

解散聊天室

仅聊天室所有者可以调用 destroyChatRoom 方法解散聊天室。聊天室解散时，其他成员收到 onChatRoomDestroyed 回调并被踢出聊天室。

示例代码如下：

ChatClient.getInstance()
  .roomManager.destroyChatRoom(roomId)
  .then(() => {
    console.log("destroy room success.");
  })
  .catch((reason) => {
    console.log("destroy room fail.", reason);
  });

监听聊天室事件

ChatRoomEventListener 类中提供了聊天室事件的监听接口。你可以通过注册聊天室监听器，获取聊天室事件，并作出相应处理。如不再使用该监听器，需要移除，防止出现内存泄露。

示例代码如下：

// 实现监听器以及定义监听器对象。
const roomListener: ChatRoomEventListener = new (class
  implements ChatRoomEventListener
{
  that: QuickTestScreenBase<S, SL>;
  constructor(parent: QuickTestScreenBase<S, SL>) {
    this.that = parent;
  }
  // 聊天室被解散。聊天室的所有成员会收到该事件。
  onChatRoomDestroyed(params: {
    roomId: string;
    roomName?: string | undefined;
  }): void {
    console.log(`onChatRoomDestroyed:`, params.roomId, params.roomName);
  }
  // 有用户加入聊天室。聊天室的所有成员（除新成员外）会收到该事件。
  onMemberJoined(params: { roomId: string; participant: string }): void {
    console.log(`onMemberJoined:`, params.roomId, params.participant);
  }
  // 有成员主动退出聊天室。聊天室的所有成员（除退出的成员）会收到该事件。
  onMemberExited(params: {
    roomId: string;
    participant: string;
    roomName?: string | undefined;
  }): void {
    console.log(
      `onMemberJoined:`,
      params.roomId,
      params.participant,
      params.roomName
    );
  }
  // 有成员被移出聊天室。被移出的成员会收到该事件。
  onRemoved(params: {
    roomId: string;
    participant?: string | undefined;
    roomName?: string | undefined;
  }): void {
    console.log(
      `onRemoved:`,
      params.roomId,
      params.participant,
      params.roomName
    );
  }
  // 有成员被加入禁言列表。被添加的成员收到该事件。
  onMuteListAddedV2(params: {
    roomId: string;
    mutes: Record<string, number>;
  }): void {
    console.log(
      'onMuteListAddedV2:',
      params.roomId,
      params.mutes
    );
  }
  // 有成员被移出禁言列表。被解除禁言的成员会收到该事件。
  onMuteListRemoved(params: { roomId: string; mutes: string[] }): void {
    console.log(`onMuteListRemoved:`, params.roomId, params.mutes);
  }
  // 有成员被设为管理员。被添加的管理员会收到该事件。
  onAdminAdded(params: { roomId: string; admin: string }): void {
    console.log(`onAdminAdded:`, params.roomId, params.admin);
  }
  // 有成员被移除管理员权限。被移除的管理员会收到该事件。
  onAdminRemoved(params: { roomId: string; admin: string }): void {
    console.log(`onAdminRemoved:`, params.roomId, params.admin);
  }
  // 聊天室所有者变更。聊天室所有成员会收到该事件。
  onOwnerChanged(params: {
    roomId: string;
    newOwner: string;
    oldOwner: string;
  }): void {
    console.log(
      `onOwnerChanged:`,
      params.roomId,
      params.newOwner,
      params.oldOwner
    );
  }
  // 聊天室公告变更。聊天室的所有成员会收到该事件。
  onAnnouncementChanged(params: {
    roomId: string;
    announcement: string;
  }): void {
    console.log(`onAnnouncementChanged:`, params.roomId, params.announcement);
  }
  // 有成员被加入聊天室白名单。被添加的成员收到该事件。
  onAllowListAdded(params: { roomId: string; members: string[] }): void {
    console.log(`onAllowListAdded:`, params.roomId, params.members);
  }
  // 有成员被移出聊天室白名单。被移出白名单的成员会收到该事件。
  onAllowListRemoved(params: { roomId: string; members: string[] }): void {
    console.log(`onAllowListRemoved:`, params.roomId, params.members);
  }
  // 聊天室全员禁言状态变更。聊天室所有成员会收到该事件。
  onAllChatRoomMemberMuteStateChanged(params: {
    roomId: string;
    isAllMuted: boolean;
  }): void {
    console.log(
      `onAllChatRoomMemberMuteStateChanged:`,
      params.roomId,
      params.isAllMuted ? "true" : "false"
    );
  }
  // 聊天室详情发生改变。聊天室所有成员会收到该事件。
  onSpecificationChanged?(room: ChatRoom): void {
    console.log(`onSpecificationChanged:`, room);
  }
  // 聊天室自定义属性（key-value）有更新。聊天室所有成员会收到该事件。
  onAttributesUpdated?(params: {
    roomId: string;
    attributes: Map<string, string>;
    from: string;
  }): void {
    console.log(
      `onAttributesUpdated:`,
      params.roomId,
      params.attributes,
      params.from
    );
  }
  // 聊天室自定义属性被移除。聊天室所有成员会收到该事件。
  onAttributesRemoved?(params: {
    roomId: string;
    removedKeys: Array<string>;
    from: string;
  }): void {
    console.log(
      `onAttributesRemoved:`,
      params.roomId,
      params.removedKeys,
      params.from
    );
  }
})(this);

// 清空聊天室监听器。
ChatClient.getInstance().roomManager.removeAllRoomListener();

// 添加聊天室监听器。
ChatClient.getInstance().roomManager.addRoomListener(roomListener);

实时更新聊天室成员人数

如果聊天室短时间内有成员频繁加入或退出时，实时更新聊天室成员人数的逻辑如下：

  1. 聊天室内有成员加入时，其他成员会收到 ChatRoomEventListener#onMemberJoined 事件。有成员主动或被动退出时，其他成员会收到 ChatRoomEventListener#onMemberExited 事件。

  2. 收到通知事件后，调用 fetchChatRoomInfoFromServer 方法获取本地聊天室详情，其中包括聊天室当前人数。

ChatClient.getInstance()
  .chatManager.fetchChatRoomInfoFromServer(
    roomId // 房间ID
  )
  .then((res) => {
    // todo: 操作成功, 获取房间信息
  })
  .catch((error) => {
    // todo: 发生错误
  });
环信 IM 文档 Version: 1.0.0 ©️环信