群组管理

---

功能简介

ZIM SDK 提供了群组管理功能，支持用户创建/解散群组、加入/退出群组，持久化维系群组关系。

群组管理功能可应用于办公群、社交群、兴趣群以及粉丝群等场景中，群组成员数量上限请参考 计费说明。

前提条件

在实现“群组管理”功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考控制台的 服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “2 集成 SDK”。

创建群组

客户端 A 登录 ZIM SDK 后，调用 createGroup 接口，设置高级配置，创建一个群组，此时 A 就是 群主；其他客户端可以根据 A 创建的群组 groupID 加入群组。

开发者可以通过 ZIMGroupCreatedResult，判断群组是否创建成功。相关错误码请查看 常见错误码。

// 创建一个群组
// groupID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'，且不能以 ’#‘ 开头。
// groupName 最大 50 字节的字符串，无特殊字符限制
ZIMGroupInfo groupInfo = ZIMGroupInfo();
groupInfo.groupID = 'groupID';
groupInfo.groupName = 'groupName';
List<String> inviteUserIDs = ['userID1', 'userID2'];
ZIMGroupAdvancedConfig advancedConfig = ZIMGroupAdvancedConfig();
// 主动加群模式
// 
advancedConfig.joinMode = ZIMGroupJoinMode.any;
// 邀请进群验证模式
advancedConfig.inviteMode = ZIMGroupInviteMode.any;
// 被邀请入群验证模式
advancedConfig.beInviteMode = ZIMGroupBeInviteMode.none;
//成员数量限制
advancedConfig.maxMemberCount = 300;
try{
    await ZIM.getInstance()!.createGroup(groupInfo, inviteUserIDs,advancedConfig);
    //这里写创建群组后的业务逻辑
    } on PlatformException catch(onError){
    onError.code;
    onError.message;
}

加入群组

其他用户登录 ZIM SDK 后，可以通过主动加入或被邀请加入由 A 创建的群组。

如果用户加入成功后，全体群成员（包括该新成员）都会收到 onGroupMemberStateChanged 和 onGroupStateChanged 的回调通知：

//群成员状态变更通知
ZIMEventHandler.onGroupMemberStateChanged = (
    ZIM zim,
    ZIMGroupMemberState state,
    ZIMGroupMemberEvent event,
    List<ZIMGroupMemberInfo> userList,
    ZIMGroupOperatedInfo operatedInfo,
    String groupID
){};

//群状态变更通知
ZIMEventHandler.onGroupStateChanged = (
    ZIM zim,
    ZIMGroupState state,
    ZIMGroupEvent event,
    ZIMGroupOperatedInfo operatedInfo,
    ZIMGroupFullInfo groupInfo
){};

方式 1：主动加入群组

• 当 joinMode 为 0（Any），用户调用 joinGroup 接口，传入 groupID（groupID 必须已经存在，否则会操作失败），即可直接加入群组。加入成功后，全体群成员（包括自己）都会收到 onGroupMemberStateChanged 的回调通知。

  开发者可以通过 ZIMGroupJoinedResult，判断用户加入群组是否成功。

  // 其他客户端直接加入群组
  ZIM.getInstance()
  !.joinGroup('groupID')
  .then((value){
      //成功触发此处
  })
  .catchError((onError) {
      //失败触发此处
  });

• 当 joinMode 为 1（Auth）时：

  1. 用户调用 sendGroupJoinApplication 接口发起申请。

     ZIMGroupJoinApplicationSendConfig sendConfig = ZIMGroupJoinApplicationSendConfig();
     sendConfig.wording = '请让我进群';
     try{
         var result = await ZIM.getInstance()!.sendGroupJoinApplication('groupID', sendConfig);
     } on PlatformException catch (onError){
         onError.code;
         onError.message;
     }

  2. 群主或管理员通过监听 onGroupApplicationListChanged 事件，得知新增申请待处理。

       ZIMEventHandler.onGroupApplicationListChanged = (ZIM zim,
         List<ZIMGroupApplicationInfo> applicationList,
         ZIMGroupApplicationListChangeAction action){}; 

  3. 群主或管理员审批

     • 群主或管理员调用 acceptGroupJoinApplication 接口，同意用户入群，用户成功入群。

       // 同意申请
       try{
           ZIMGroupJoinApplicationAcceptConfig acceptConfig = ZIMGroupJoinApplicationAcceptConfig();
           var result = await ZIM.getInstance()!.acceptGroupJoinApplication('userID', 'groupID', acceptConfig);    
       } on PlatformException catch (onError){
           onError.code;
           onError.message;
       }

     • 群主或管理员调用 rejectGroupJoinApplication 接口，拒绝用户入群。

       // 拒绝申请
       try{
           ZIMGroupJoinApplicationRejectConfig rejectConfig = ZIMGroupJoinApplicationRejectConfig();
           var result = await ZIM.getInstance()!.rejectGroupJoinApplication('userID', 'groupID', rejectConfig);
       } on PlatformException catch (onError){
           onError.code;
           onError.message;
       }

  4. 入群申请人、群主、管理员和接口调用者会收到 onGroupApplicationUpdated 回调通知。

     // 监听 onGroupApplicationUpdated 事件
     ZIMEventHandler.onGroupApplicationUpdated = (ZIM zim,
         List<ZIMGroupApplicationInfo> applicationList){
     
     };

方式 2：由群内成员添加入群组（邀请入群）

1. 群内用户可通过以下任意接口邀请用户入群：

   请确认被邀请用户（以下称为“目标用户”）已通过 login 接口登录注册过，否则会操作失败。

   • inviteUsersIntoGroup：直接邀请用户入群，无需对方同意。

     开发者可以通过 ZIMGroupUsersInvitedResult，判断用户是否被成功加入到群组中。

     // 由群内成员添加入群组
     List<String> userIDs = ['userID1', 'userID2'];
     ZIM.getInstance()
     !.inviteUsersIntoGroup(userIDs, 'groupID')
     .then((value) => {
         //成功调用此处
     })
     .catchError((onError) {
         //失败调用此处
     });

     群内成员调用 inviteUsersIntoGroup 接口，邀请其他用户加入群组时：

     • 被添加的用户将直接进入群组，无需同意。
     • 被添加的用户 userID，必须是真实存在的（即已经通过 login 接口登录注册过），否则会操作失败。

2. sendGroupInviteApplications：向用户发起入群邀请申请。

   // 发送邀请入群申请
   ZIMGroupInviteApplicationSendConfig config = ZIMGroupInviteApplicationSendConfig();
   config.wording = 'xxx邀请你加入群聊';
   ZIMGroupInviteApplicationSendConfig applicationSendConfig = ZIMGroupInviteApplicationSendConfig();
   try{
       var result = await ZIM.getInstance()!.sendGroupInviteApplications(['userID1','userID2'], 'groupID', config);
   } on PlatformException catch (onError) {
       onError.code;
       onError.message;
   } 

   根据群组的 inviteMode 和 beInviteMode，以及调用用户的群组角色，接口调用效果如下表所示：

   beInviteMode	inviteMode	调用接口	调用角色	结果
   0：None	0：Any	inviteUsersIntoGroup	所有群成员	被邀请人自动成为群成员。
   		sendGroupInviteApplications		被邀请人自动成为群成员，且不产生邀请入群申请记录。
   	1：Admin	inviteUsersIntoGroup	普通成员	失败。
   			群主或管理员	被邀请人自动成为群成员。
   		sendGroupInviteApplications	普通成员	失败。
   			群主或管理员	被邀请人自动成为群成员，且不产生邀请入群申请记录。
   1：Auth	0：Any	inviteUsersIntoGroup	所有群成员	产生邀请入群申请记录，等待目标用户做出反应。
   		sendGroupInviteApplications		产生邀请入群申请记录，等待目标用户做出反应。此外，如果调用者为群主或管理员时，会收到 groupApplicationListChanged。
   	1：Admin	inviteUsersIntoGroup	普通成员	失败。
   			群主或管理员	产生邀请入群申请记录，等待目标用户做出反应。
   		sendGroupInviteApplications	普通成员	失败。
   			群主或管理员	产生邀请入群申请记录，等待目标用户做出反应。此外，如果调用者为群主或管理员时，会收到 groupApplicationListChanged。

3. beInviteMode 为 1 时，目标用户和邀请人（仅当接口调用人为群主和群管理员时）会通过 onGroupApplicationListChanged 收到回调通知。目标用户需要审批该申请。

   • 目标用户调用 acceptGroupInviteApplication 接口，同意入群，成为群成员。

     try{
         ZIMGroupInviteApplicationAcceptConfig acceptConfig = ZIMGroupInviteApplicationAcceptConfig();
         var reuslt = await ZIM.getInstance()!.acceptGroupInviteApplication('inviterUserID', 'groupID', acceptConfig); 
     } on PlatformException catch(onError){
         onError.code;
         onError.message;
     }

   • 目标用户调用 rejectGroupInviteApplication 接口，拒绝入群。

     try{
         ZIMGroupInviteApplicationRejectConfig rejectConfig = ZIMGroupInviteApplicationRejectConfig();
         var reuslt = await ZIM.getInstance()!.rejectGroupInviteApplication('inviterUserID', 'groupID', rejectConfig);
     } on PlatformException catch(onError){
         onError.code;
         onError.message;
     }

4. beInviteMode 为 1 时，目标用户和邀请人（仅当接口调用人为群主和群管理员时）会通过 onGroupApplicationUpdated 收到回调通知上述审批事件。

   ZIMEventHandler.onGroupApplicationUpdated = (ZIM zim,
   List<ZIMGroupApplicationInfo> applicationList){
   
   };

退出群组

成员退出群组也存在两种方式（二选一），主动退出和被提出群组。

方式 1：主动退出群组。

成员登录 ZIM SDK 后，直接调用 leaveGroup 接口，传入 groupID（groupID 必须已经存在，否则会操作失败），主动退出群组。退出成功后，全体群成员（包括自己）都会收到 onGroupMemberStateChanged 的回调通知。

开发者可以通过 ZIMGroupLeftResult，判断成员退出群组是否成功。

// 主动退出群组
ZIM.getInstance()
  !.leaveGroup('groupID')
   .then((value){
       //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

方式 2：群主移除群内成员

群主调用 kickGroupMembers 接口，传入 groupID（groupID 必须已经存在，否则会操作失败）、userIDs（需要被移除的成员列表），移除这些成员。移除成功后，全体群成员（包括群主自己、被移除的成员）都会收到 onGroupMemberStateChanged 的回调通知。

开发者可以通过 ZIMGroupMemberKickedResult，判断用户是否被成功移除。

// 群主移除群内成员
ZIM.getInstance()
  !.kickGroupMembers(userIDs, 'groupID')
   .then((value){
       //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

解散群组

群主登录 ZIM SDK 后，如果想要解散群组，可以通过 dismissGroup 接口，解散群组。解散群组成功后，全体群成员都会收到 onGroupStateChanged 回调通知。

开发者可以通过 ZIMGroupDismissedResult，判断解散群组是否成功。

// 群主解散群组
ZIM.getInstance()
  !.dismissGroup('groupID')
   .then((value){
       //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

更多功能

查询已加入群组列表

用户登录 ZIM SDK 后，如果想要了解自己加入了哪些群组，可以通过 queryGroupList 接口，获取自己已加入的群组列表。

开发者可以通过 ZIMGroupListQueriedResult，获取查询结果。

// 用户查询自己加入了哪些群组
ZIM.getInstance()
  !.queryGroupList()
   .then((value){
       //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

搜索已加入群组

用户登录 ZIM SDK 后，如果想要根据条件对已加入的群组进行搜索，可以调用 searchLocalGroups 接口，传入 config、callback 搜索群组。

搜索结果将通过 ZIMGroupsSearchedResult 回调接口返回。

// 搜索名称中包含 “zego” 的已加入群组
ZIMGroupSearchConfig config =  ZIMGroupSearchConfig();
config.count = 10;
config.nextFlag = 0;
config.isAlsoMatchGroupMemberNickname = true; // 如果群成员昵称包含 “zego”，搜索结果将包含该群组。
config.isAlsoMatchGroupMemberUserName = true; // 如果群成员用户名称包含 “zego”，搜索结果将包含该群组。
config.keywords.add("zego");
ZIM.getInstance()!.searchLocalGroups(config).then((result){
    // 开发者可从 groupSearchInfoList 中获取到群组信息    
}).catchError((onError){
    // 根据官网错误码表处理
});

禁言或解禁群组

禁言，是指让群组会话内的用户不能发言。

在登录 ZIM SDK 后，用户可以禁言自己管理的群组。只需调用 muteGroup 接口，传入相应参数设置群组 ID、禁言模式、持续时长和目标角色，即可禁言或解禁群组。

ZIM 支持 3 种群组禁言模式：

• 所有群组成员不能发言；
• 所有普通群组成员（role 为 3）不能发言，；
• 指定角色的群成员不能发言。

禁言操作结果将通过 ZIMGroupMutedResult 回调接口返回。

// 设置群组禁言配置
try {
    // 设置群组禁言配置
    ZIMGroupMuteConfig config = ZIMGroupMuteConfig();
    // 群组禁言模式为指定角色的群成员不能发言
    config.mode = ZIMGroupMuteMode.custom;
    // 禁言时长为 30 秒
    config.duration = 30;
    // 角色为 3 和 5 的群成员被禁言
    config.roles = [3,5];
    // 开启禁言
    bool isMute = true;
    ZIMGroupMutedResult result = await ZIM.getInstance()!.muteGroup(isMute, 'group_id', config);
} on PlatformException catch (onError){
    onError.code;//根据错误码表处理
    onError.message;//错误信息
}

群组禁言或解禁成功后，全部群成员会收到 onGroupMutedInfoUpdated，得知哪些角色无法在该群组发言或可恢复发言。

ZIMEventHandler.onGroupMutedInfoUpdated = (ZIM zim, ZIMGroupMuteInfo groupMuteInfo, ZIMGroupOperatedInfo operatedInfo, String groupID){
    //在这里监听群禁言状态变更的信息，并进行相应处理
};

确认群组会话是否可用

如需确认当前用户是否仍在所加入的群组会话中，请通过以下任意方法：

• 参考 会话管理 - 拉取会话列表 主动拉取会话列表。
• 参考 会话管理 - 更新会话列表，监听会话变更回调，更新会话列表。

当会话类型是群类型时，从返回结果中的 ZIMGroupConversation 获取 isDisabled，即会话是否可用。

isDisabled 值说明如下：

• 为 true 时，表示当前用户不在该群组会话。当前用户主动退出、被踢或群组解散都会导致会话不可用。
• 为 false 时，表示当前用户在该群组会话。

更新入群验证模式

群主和管理员登录 ZIM SDK 后，可以通过 updateGroupJoinMode 接口更新入群验证模式。

更新成功后，全体群成员都会收到 onGroupVerifyInfoUpdated 回调通知。

// 监听 onGroupVerifyInfoUpdated 事件
ZIMEventHandler.onGroupVerifyInfoUpdated = (ZIM zim,
    ZIMGroupVerifyInfo verifyInfo,
    ZIMGroupOperatedInfo operatedInfo,
    String groupID){};

// 更新入群验证模式
try{
    var reuslt = await ZIM.getInstance()!.updateGroupJoinMode(ZIMGroupJoinMode.auth, 'groupID');
} on PlatformException catch(onError){
    onError.code;
    onError.message;
}

更新邀请模式

群主和管理员登录 ZIM SDK 后，可以通过 updateGroupInviteMode 接口更新邀请模式。

更新成功后，全体群成员都会收到 onGroupVerifyInfoUpdated 回调通知。

// 监听 onGroupVerifyInfoUpdated 事件
ZIMEventHandler.onGroupVerifyInfoUpdated = (ZIM zim,
    ZIMGroupVerifyInfo verifyInfo,
    ZIMGroupOperatedInfo operatedInfo,
    String groupID){};

// 更新邀请模式
try{
    var result = await ZIM.getInstance()!.updateGroupInviteMode(ZIMGroupInviteMode.any, 'groupID');
} on PlatformException catch(onError){
    onError.code;
    onError.message;
}

更新邀请目标用户验证模式

群主和管理员登录 ZIM SDK 后，可以通过 updateGroupBeInviteMode 接口更新目标用户验证模式。

更新成功后，全体群成员都会收到 onGroupVerifyInfoUpdated 回调通知。

// 监听 onGroupVerifyInfoUpdated 事件
ZIMEventHandler.onGroupVerifyInfoUpdated = (ZIM zim,
    ZIMGroupVerifyInfo verifyInfo,
    ZIMGroupOperatedInfo operatedInfo,
    String groupID){};

// 更新目标用户验证模式
try{
    var result = await ZIM.getInstance()!.updateGroupBeInviteMode(ZIMGroupBeInviteMode.auth, 'groupID');
} on PlatformException catch(onError){
    onError.code;
    onError.message;
}

查询入群申请列表

用户登录 ZIM SDK 后，调用 queryGroupApplicationList 接口，可以查询入群申请列表，查询结果包含自己的入群申请和自己被邀请入群的申请。当用户是群主或管理员时，查询结果还会包含他人的入群申请和自己邀请他人入群的申请。

try{
    ZIMGroupApplicationListQueryConfig queryConfig = ZIMGroupApplicationListQueryConfig();
    queryConfig.count = 100;
    queryConfig.nextFlag = 0;
    var result = await ZIM.getInstance()!.queryGroupApplicationList(queryConfig);
} on PlatformException catch(onError){
    onError.code;
    onError.message;
}