# 创建管理群组和监听群组事件

    群组是支持多人沟通的即时通讯系统,本文介绍如何使用环信即时通讯 IM React Native SDK 在实时互动 app 中创建和管理群组,并实现群组相关功能。

    如需查看消息相关内容,参见 消息管理

    # 技术原理

    环信即时通讯 IM React Native SDK 提供 ChatGroupManager 类和 ChatGroup 类,用于管理群组,以及事件监听回调 ChatGroupEventListener。其中包含如下主要方法:

    • 创建、解散群组
    • 获取群组详情
    • 获取群组列表
    • 屏蔽和解除屏蔽群消息
    • 监听群组事件

    # 前提条件

    开始前,请确保满足以下条件:

    # 实现方法

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

    # 创建群组

    在创建群组前,你需要设置群组的类型(ChatGroupStyle)和邀请进群是否需要对方同意(ChatGroupOptions#inviteNeedConfirm)。其中:

    • 群组类型(ChatGroupStyle)可以设置为如下值:

      • PrivateOnlyOwnerInvite —— 私有群,只有群主和管理员可以邀请人进群;
      • PrivateMemberCanInvite —— 私有群,所有群成员均可以邀请人进群;
      • PublicJoinNeedApproval —— 公开群,用户加入群组需要群组或管理员同意;
      • PublicOpenJoin —— 公开群,任何人都可以进群,无需群主和群管理员同意。
    • 邀请用户进群(ChatGroupOptions#inviteNeedConfirm

      公开群只支持群主和管理员邀请用户入群。对于私有群,除了群主和群管理员,群成员是否也能邀请其他用户进群取决于群样式(ChatGroupStyle)的设置:

      • ChatGroupStylePrivateOnlyOwnerInvite:只有群主和管理员可以邀请人入群;
      • ChatGroupStylePrivateMemberCanInvite:普通群成员也能邀请人进群。

      邀请入群是否需受邀用户确认取决于群组选项 ChatGroupOptions#inviteNeedConfirm 和受邀用户的参数 autoAcceptGroupInvitation 的设置,前者参数的优先级高于后者,即 ChatGroupOptions#inviteNeedConfirm 若设置为 false,不论 autoAcceptGroupInvitation 设置为何值,受邀用户无需确认直接进群。

      1. 受邀用户无需确认,直接进群。

      以下两种设置的情况下,用户直接进群:

      • ChatGroupOptions#inviteNeedConfirm 设置为 false,不论 autoAcceptGroupInvitation 设置为 falsetrue,受邀用户均无需确认,直接进群。
      • ChatGroupOptions#inviteNeedConfirmautoAcceptGroupInvitation 均设置为 true,用户自动接受群组邀请,直接进群。

      受邀用户直接进群,会收到如下回调:

      • 新成员会收到 ChatGroupEventListener#onAutoAcceptInvitation 回调;
      • 邀请人会收到 ChatGroupEventListener#onInvitationAcceptedChatGroupEventListener#onMemberJoined 回调;
      • 其他群成员会收到 ChatGroupEventListener#onMemberJoined 回调。
      1. 受邀用户需要确认才能进群。

      只有 ChatGroupOptions#inviteNeedConfirm 设置为 trueautoAcceptGroupInvitation 设置为 false 时,受邀用户需要确认才能进群。这种情况下,受邀用户收到 ChatGroupEventListener#onInvitationReceived 回调,并选择同意或拒绝进群邀请:

      • 用户同意入群邀请后,邀请人收到 ChatGroupEventListener#onInvitationAccepted 回调和 ChatGroupEventListener#onMemberJoined 回调,其他群成员收到 ChatGroupEventListener#onMemberJoined 回调;
      • 用户拒绝入群邀请后,邀请人收到 ChatGroupEventListener#onInvitationDeclined 回调。

    你可以调用 createGroup 方法创建群组,并通过 ChatGroupOptions 参数设置群组名称、群组描述、群组成员和建群原因。

    示例代码如下:

    // 群组选项。核心选项为 `style`,用于设置群组类型。详见 `ChatGroupStyle`。
    option.style = PrivateOnlyOwnerInvite;
    // 群组的名称,不能超过 128 个字符
    const groupName = "study";
    // 群组描述,不能超过 512 个字符
    const desc = "this is study group";
    // 成员列表
    const allMembers = ["Tom", "Jason"];
    // 执行操作
    ChatClient.getInstance()
      .groupManager.createGroup(option, groupName, desc, allMembers, reason)
      .then(() => {
        console.log("create group success.");
      })
      .catch((reason) => {
        console.log("create group fail.", reason);
      });
    

    # 解散群组

    仅群主可以调用 destroyGroup 方法解散群组。群组解散时,其他群组成员收到 ChatGroupEventListener#onGroupDestroyed 回调并被踢出群组。

    注意

    解散群组后,将删除本地数据库及内存中的群相关信息及群会话,谨慎操作。

    示例代码如下:

    // 将要解散的群组 ID
    const groupId = "100";
    ChatClient.getInstance()
      .groupManager.destroyGroup(groupId)
      .then(() => {
        console.log("destroy group success.");
      })
      .catch((reason) => {
        console.log("destroy group fail.", reason);
      });
    

    # 退出群组

    群成员可调用 leaveGroup 方法退出群组,其他成员收到 ChatGroupEventListener#onMemberExited 回调。退出群组后,该成员将不再收到群消息。 群主不能调用该接口退出群组,只能调用 destroyGroup 方法解散群组。

    示例代码如下:

    ChatClient.getInstance()
      .groupManager.leaveGroup(groupId)
      .then(() => {
        console.log("leave group success.");
      })
      .catch((reason) => {
        console.log("leave group fail.", reason);
      });
    

    # 获取群组详情

    获取单个群组详情有以下两种方法:

    • getGroupWithId:从内存获取群组详情。返回的结果包括群组 ID、群组名称、群组描述、群主、公告信息、群成员列表数量、消息屏蔽、是否全体禁言、权限类型等,默认不包含群成员。
    • fetchGroupInfoFromServer:从服务器获取群组详情。返回的结果包括群组 ID、群组名称、群组描述、群组基本属性、群主、群组管理员列表、是否已屏蔽群组消息和群组是否禁用等信息。若将该方法的 fetchMembers 参数设置为 true,可获取群成员列表,默认最多包括 200 个成员。
    // 从本地获取群组详情。
    ChatClient.getInstance()
      .groupManager.getGroupWithId(groupId)
      .then((groupInfo) => {
        console.log("get group info success: ", groupInfo);
      })
      .catch((reason) => {
        console.log("get group info fail.", reason);
      });
    
    // 从服务器获取群组详情。
    ChatClient.getInstance()
      .groupManager.fetchGroupInfoFromServer(groupId)
      .then((groupInfo) => {
        console.log("get group info success: ", groupInfo);
      })
      .catch((reason) => {
        console.log("get group info fail.", reason);
      });
    

    # 获取群组列表

    用户可以调用 fetchJoinedGroupsFromServer 方法从服务器获取自己加入和创建的群组列表。示例代码如下:

    // 分页获取群组列表
    // 每页期望返回的群组数量
    const pageSize = 10;
    // 当前页码
    const pageNum = 1;
    ChatClient.getInstance()
      .groupManager.fetchJoinedGroupsFromServer(pageSize, pageNum)
      .then((groups) => {
        console.log("get group list success: ", groups);
      })
      .catch((reason) => {
        console.log("get group list fail.", groups);
      });
    
    • 用户可以调用 getJoinedGroups 方法加载本地群组列表。为了保证数据的正确性,需要先从服务器获取自己加入和创建的群组列表。示例代码如下:
    ChatClient.getInstance()
      .groupManager.getJoinedGroups()
      .then((groups) => {
        console.log("get group list success: ", groups);
      })
      .catch((reason) => {
        console.log("get group list fail.", groups);
      });
    
    • 用户还可以分页获取公开群列表:
    // 获取的群组列表来自服务器,但是不包括成员列表
    ChatClient.getInstance()
      .groupManager.fetchPublicGroupsFromServer(pageSize, cursor)
      .then((groups) => {
        console.log("get group list success: ", groups);
      })
      .catch((reason) => {
        console.log("get group list fail.", groups);
      });
    

    # 屏蔽和解除屏蔽群消息

    群成员可以屏蔽群消息和解除屏蔽群消息。

    # 屏蔽群消息

    群成员可以调用 blockGroup 方法屏蔽群消息。屏蔽群消息后,该成员不再从指定群组接收消息,群主和群管理员不能进行此操作。示例代码如下:

    ChatClient.getInstance()
      .groupManager.blockGroup(groupId)
      .then(() => {
        console.log("block group success. ");
      })
      .catch((reason) => {
        console.log("block group fail.", groups);
      });
    

    # 解除屏蔽群消息

    群成员可以调用 unblockGroup 方法解除屏蔽群消息。示例代码如下:

    ChatClient.getInstance()
      .groupManager.unblockGroup(groupId)
      .then(() => {
        console.log("unblock group success. ");
      })
      .catch((reason) => {
        console.log("unblock group fail.", groups);
      });
    

    # 解除屏蔽或者屏蔽的通知

    当发生了屏蔽或者解除屏蔽全体成员的时候会收到通知 ChatGroupEventListener#onAllGroupMemberMuteStateChanged

    # 监听群组事件

    ChatGroupEventListener 中提供群组事件的监听接口。开发者可以通过设置此监听,获取群组中的事件,并做出相应处理。如果不再使用该监听,需要移除,防止出现内存泄漏。

    示例代码如下:

    // 创建一个群组事件监听
    const groupListener: ChatGroupEventListener = new (class
      implements ChatGroupEventListener
    {
      that: any;
      constructor(parent: any) {
        this.that = parent;
      }
      // 用户收到进群邀请,受邀人收到该事件回调
      onInvitationReceived(params: {
        groupId: string;
        inviter: string;
        groupName?: string | undefined;
        reason?: string | undefined;
      }): void {
        console.log(
          `onInvitationReceived:`,
          params.groupId,
          params.inviter,
          params.groupName,
          params.reason
        );
      }
      // 群主或群管理员收到入群申请的事件回调
      onRequestToJoinReceived(params: {
        groupId: string;
        applicant: string;
        groupName?: string | undefined;
        reason?: string | undefined;
      }): void {
        console.log(
          `onRequestToJoinReceived:`,
          params.groupId,
          params.applicant,
          params.groupName,
          params.reason
        );
      }
      // 群主或群管理员同意用户的进群申请,申请人收到该事件回调
      onRequestToJoinAccepted(params: {
        groupId: string;
        accepter: string;
        groupName?: string | undefined;
      }): void {
        console.log(
          `onRequestToJoinAccepted:`,
          params.groupId,
          params.accepter,
          params.groupName
        );
      }
      // 群主或群管理员拒绝用户的进群申请,申请人收到该事件回调
      onRequestToJoinDeclined(params: {
        groupId: string;
        decliner: string;
        groupName?: string | undefined;
        reason?: string | undefined;
      }): void {
        console.log(
          `onRequestToJoinDeclined:`,
          params.groupId,
          params.decliner,
          params.groupName,
          params.reason
        );
      }
      // 用户同意进群邀请,邀请人收到回调
      onInvitationAccepted(params: {
        groupId: string;
        invitee: string;
        reason?: string | undefined;
      }): void {
        console.log(
          `onInvitationAccepted:`,
          params.groupId,
          params.invitee,
          params.reason
        );
      }
      // 用户拒绝进群邀请,邀请人收到回调
      onInvitationDeclined(params: {
        groupId: string;
        invitee: string;
        reason?: string | undefined;
      }): void {
        console.log(
          `onInvitationDeclined:`,
          params.groupId,
          params.invitee,
          params.reason
        );
      }
      // 用户被移出群组,所有群组成员收到回调
      onUserRemoved(params: {
        groupId: string;
        groupName?: string | undefined;
      }): void {
        console.log(`onUserRemoved:`, params.groupId, params.groupName);
      }
      // 群组解散,被解散群组所有成员收到该回调
      onGroupDestroyed(params: {
        groupId: string;
        groupName?: string | undefined;
      }): void {
        console.log(`onGroupDestroyed:`, params.groupId, params.groupName);
      }
      // 用户自动同意进群邀请,邀请人收到该事件回调
      onAutoAcceptInvitation(params: {
        groupId: string;
        inviter: string;
        inviteMessage?: string | undefined;
      }): void {
        console.log(
          `onAutoAcceptInvitation:`,
          params.groupId,
          params.inviter,
          params.inviteMessage
        );
      }
      // 群成员被加入禁言列表,被加入禁言列表的成员及管理员和群主收到该事件回调
      onMuteListAdded(params: {
        groupId: string;
        mutes: string[];
        muteExpire?: number | undefined;
      }): void {
        console.log(
          `onMuteListAdded:`,
          params.groupId,
          params.mutes,
          params.muteExpire?.toString
        );
      }
      // 群成员被移出禁言列表,被移出禁言列表的成员及管理员和群主收到该事件回调
      onMuteListRemoved(params: { groupId: string; mutes: string[] }): void {
        console.log(`onMuteListRemoved:`, params.groupId, params.mutes);
      }
      // 群组新增管理员,被添加权限的管理员及其他管理员和群主收到该事件回调
      onAdminAdded(params: { groupId: string; admin: string }): void {
        console.log(`onAdminAdded:`, params.groupId, params.admin);
      }
      // 群组管理员被移除,被移除权限的管理员及其他管理员和群主收到该事件回调
      onAdminRemoved(params: { groupId: string; admin: string }): void {
        console.log(`onAdminRemoved:`, params.groupId, params.admin);
        this.that.setState({
          group_listener: `onAdminRemoved: ` + params.groupId + params.admin,
        });
      }
      // 群主转移权限,所有群成员收到该回调
      onOwnerChanged(params: {
        groupId: string;
        newOwner: string;
        oldOwner: string;
      }): void {
        console.log(
          `onOwnerChanged:`,
          params.groupId,
          params.newOwner,
          params.oldOwner
        );
      }
      // 有新成员加入群组,所有群成员收到该回调
      onMemberJoined(params: { groupId: string; member: string }): void {
        console.log(`onMemberJoined:`, params.groupId, params.member);
      }
      // 有群成员主动退出群,所有群成员收到该回调
      onMemberExited(params: { groupId: string; member: string }): void {
        console.log(`onMemberExited:`, params.groupId, params.member);
      }
      // 群组公告更新,所有群成员收到该回调
      onAnnouncementChanged(params: {
        groupId: string;
        announcement: string;
      }): void {
        console.log(`onAnnouncementChanged:`, params.groupId, params.announcement);
      }
      // 有成员新上传群组共享文件,所有群成员收到该回调
      onSharedFileAdded(params: { groupId: string; sharedFile: string }): void {
        console.log(`onSharedFileAdded:`, params.groupId, params.sharedFile);
      }
      // 群组共享文件被删除,所有群成员收到该回调
      onSharedFileDeleted(params: { groupId: string; fileId: string }): void {
        console.log(`onSharedFileDeleted:`, params.groupId, params.fileId);
      }
      // 有成员被加入群组白名单,被加入白名单的成员及管理员和群主收到该事件回调
      onAllowListAdded(params: { groupId: string; members: string[] }): void {
        console.log(`onAllowListAdded:`, params.groupId, params.members);
      }
      // 有成员被移出群组白名单,被移出白名单的成员及管理员和群主收到该事件回调
      onAllowListRemoved(params: { groupId: string; members: string[] }): void {
        console.log(`onAllowListRemoved:`, params.groupId, params.members);
      }
      // 群成员全员禁言状态变更,所有群成员收到该事件回调
      onAllGroupMemberMuteStateChanged(params: {
        groupId: string;
        isAllMuted: boolean;
      }): void {
        console.log(
          `onAllGroupMemberMuteStateChanged:`,
          params.groupId,
          params.isAllMuted
        );
      }
      // 群组详情变更,所有群成员收到该事件回调
      onDetailChanged(group: ChatGroup): void {
            console.log(`${QuickTestScreenBase.TAG}: onDetailChanged:`, group);
            this.that.setState({
              recvResult: `onDetailChanged: ` + group,
            });
          }
      // 群组禁言状态变更,所有群成员收到该事件回调   
      onStateChanged(group: ChatGroup): void {
            console.log(`${QuickTestScreenBase.TAG}: onStateChanged:`, group);
            this.that.setState({
              recvResult: `onStateChanged: ` + group,
            });
          }  
    })(this);
    
    // 清空监听器对象
    ChatClient.getInstance().groupManager.removeAllGroupListener();
    
    // 添加监听器对象
    ChatClient.getInstance().groupManager.addGroupListener(groupListener);
    
    更新时间:2023-01-14 23:03:25