群成员管理

功能简介

说明

本文档适用于开发以下平台的应用：iOS、Android、macOS、Windows、Web。

ZIM SDK 提供了群成员管理功能，支持查询群组成员列表、查询群组成员基本信息以及转让群主等功能。

实现流程

注意

用户使用“群成员管理”功能之前，请先加入某个群组，否则无法使用相关功能，详情请参考加入群组。

查询群成员列表

用户登录 ZIM SDK、并加入某个群组后，如果想要了解自己所在群组都有哪些成员，可以通过调用 queryGroupMemberList 接口，分页查询该群组的成员列表。单次调用接口最多可获取 100 名成员，传入 count 超过 100 按照 100 处理。

查询成功后，用户可以通过 ZIMGroupMemberListQueriedResult 收到查询结果。

说明

截至当前版本，首次调用此接口拉取群成员列表时，可以获取群成员头像。再次调用此接口后，可以获取新增用户的头像信息，但存量用户的头像信息不会更新。

如需获取群成员最新头像，请调用接口 queryGroupMemberInfo 查询群成员信息。

示例代码

// 群内成员查询群组的成员列表
ZIMGroupMemberQueryConfig groupMemberQueryConfig =
      ZIMGroupMemberQueryConfig();
// count 超过 100 按照 100 处理
groupMemberQueryConfig.count = 100;

ZIM.getInstance()
  !.queryGroupMemberList('groupID', groupMemberQueryConfig)
   .then((value) {
       //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

Copied!

查询群成员信息

用户登录 ZIM SDK、并加入某个群组后，如果想要了解自己所在群组的某个成员的信息，可以通过调用 queryGroupMemberInfo 接口，查询该成员的个人信息。

查询成功后，用户可以通过 ZIMGroupMemberInfoQueriedResult 收到查询结果。

示例代码

// 群内成员 查询群组内某个成员的信息
ZIM.getInstance()
  !.queryGroupMemberInfo('userID', 'groupID')
   .then((value) {
     //成功触发此处
   })
   .catchError((onError) {
     //失败触发此处
   });

Copied!

设置群成员昵称

用户登录 ZIM SDK、并加入某个群组后，如果想要设置自己在群组中的昵称，可以通过调用 setGroupMemberNickname 接口，设置昵称。

注意

在群组中，群主可以设置自己和其他群内成员在该群中的昵称；其他群内成员仅可以设置自己在该群的昵称。

设置成功后，用户可以通过 ZIMGroupMemberNicknameUpdatedResult 收到通知。

示例代码

// 群内成员设置在群内的昵称。
// 注意：群主可以设置自己和其他群内成员的昵称；其他群内成员仅可以设置自己在群内的群昵称。
ZIM.getInstance()
  !.setGroupMemberNickname('nickname', 'forUserID', 'groupID')
   .then((value) {
       //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

Copied!

设置群成员角色

群主登录 ZIM SDK 后，可以通过调用 setGroupMemberRole 接口，设置其他群内成员的角色，比如设置某个群成员为普通成员或者为管理员。

设置成功后，群主可以通过 ZIMGroupMemberRoleUpdatedResult 类型收到设置结果。

群内成员可以通过 onGroupMemberInfoUpdated 收到用户角色变更的通知。

群成员角色与权限说明

ZIM SDK 默认支持将用户设置为群主、管理员、普通成员。在群组中，群主拥有所有客户端权限，可以实现所有群组功能。管理员拥有大部分客户端权限。普通成员拥有的客户端权限最少，具体如下表所示：

客户端权限	群主（对应枚举值为 1）	管理员（对应枚举值为 2）	普通成员（对应枚举值为 3）
修改群头像、群名称、群公告	支持	支持	支持
修改群属性	支持	支持	支持
修改群成员昵称	支持，可对所有群角色用户使用此功能	支持，可对所有普通成员使用此功能	支持，仅可对自己使用此功能
撤回群成员消息			支持，仅可对自己使用此功能
踢人			不支持。
对单独群成员禁言
对特定群角色禁言
设置群成员角色		不支持
转让群主
解散群组
全员禁言

示例代码

// 群主将普通用户设置为管理员
ZIM.getInstance()
  !.setGroupMemberRole(2, 'forUserID', 'groupID')
   .then((value) {
      //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

Copied!

转让群主

用户登录 ZIM SDK、并加入某个群组后，如果自己是某个群组中的群主，可以通过调用 transferGroupOwner 接口，传入 toUserID（被转让群主的群成员 ID），将自己的群主角色，转让给其他群内成员。

注意

群组中，只有群主向其他群内成员转让群主的角色。
群主转让时，toUserID（被转让群主的用户 ID）必须是本群组内的成员，否则会操作失败。

转让成功后，群内成员可以通过 onGroupMemberInfoUpdated 收到群主变更的通知。

示例代码

// 转让群主身份给其他群内成员
ZIM.getInstance()
  !.transferGroupOwner('toUserID', 'groupID')
   .then((value) {
       //成功触发此处
   })
   .catchError((onError) {
       //失败触发此处
   });

Copied!

查询群内成员数量

用户登录 ZIM SDK、并加入某个群组后，如果想要了解自己所在群组的成员数量，可以通过调用 queryGroupMemberCount 接口，查询该群成员的数量。

查询成功后，用户可以通过 ZIMGroupMemberCountQueriedResult 收到查询结果。

示例代码

// 群内成员 查询群组内成员的数量
try {
    ZIMGroupMemberCountQueriedResult result =
        await ZIM.getInstance().queryGroupMemberCount('groupID');
        //这里写查询成功后的逻辑
    } on PlatformException catch (onError) {
        //根据 onError 写对应的失败逻辑
    }

Copied!

搜索群成员

用户登录 ZIM SDK、并加入群组后，如果想要根据条件在群成员中搜索用户，可以通过调用 searchLocalGroupMembers 接口，传入 groupID、config、callback 搜索符合条件的群成员。

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

示例代码

// 在某个群组中搜索名称中包含 “zego” 的群成员
ZIMGroupMemberSearchConfig config = ZIMGroupMemberSearchConfig();
config.count = 10;
config.isAlsoMatchGroupMemberNickname = true; // 如果群成员昵称包含 zego，搜索结果将包含该成员
config.keywords.add("zego");

ZIM.getInstance()!.searchLocalGroupMembers("groupID", config).then((value){
    // 开发者可从 userList 中获取到群成员信息
    }).catchError((onError){

});

Copied!

设置群成员禁言状态

登录 ZIM SDK 后，用户可以禁言或解禁自己管理的群组内的特定成员。调用 muteGroupMembers 接口，批量修改 100 名群成员的禁言状态。禁言期限可为永久（ZIMGroupMemberMuteConfig > duration 为 -1）或最长为 7 天（ZIMGroupMemberMuteConfig > duration 为 604800）。当 ZIMGroupMemberMuteConfig > duration 为 0 时，表示取消禁言。

说明

群主可以禁止所有群成员发言，包括自己。
如需上调单次操作数量或最长禁言期限，请联系 ZEGO 技术支持。

设置成功后，操作用户可以通过 ZIMGroupMembersMutedResult 收到通知。

禁言或解禁成功后，全体群成员会收到 onGroupMemberInfoUpdated ，得知哪些群成员无法在该群组发言或解除禁言状态。

说明

如果您希望禁止特定群成员角色发言，请参考群组管理 - 禁言或解禁群组。

Untitled

try {
    bool isMute = true;
    List<String> userIDs = ['user_1','user_2','user_3'];
    String groupID = 'group_id';
    ZIMGroupMemberMuteConfig config = ZIMGroupMemberMuteConfig();
    // 禁言时长 30 秒
    config.duration = 30;
    ZIMGroupMembersMutedResult result = await ZIM.getInstance()!.muteGroupMembers(isMute, userIDs, groupID, config);
    // 开发者可从 result 各参数中获取到禁言结果相关信息
} on PlatformException catch (onError){
    onError.code;//根据错误码表处理
    onError.message;//错误信息
}

Copied!

查询群内禁言成员列表

查询成功后，操作用户可通过 ZIMGroupMemberMutedListQueriedResult 获取具体信息。

Untitled

try {
    // 群内成员查询群组的被禁言成员列表
    ZIMGroupMemberMutedListQueryConfig config = ZIMGroupMemberMutedListQueryConfig();
    //单次获取成员数量为 100
    config.count = 100;
    config.nextFlag = 0;
    ZIMGroupMemberMutedListQueriedResult result = await ZIM.getInstance()!.queryGroupMemberMutedList('gorupID', config);
} on PlatformException catch (onError){
    onError.code; // 根据错误码表处理
    onError.message; // 错误信息
}

Copied!

获取当前群成员禁言状态

如需主动获取当前用户在群组的禁言状态，请通过以下任意方法：

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

当会话类型是群类型时，从返回结果中的 ZIMGroupConversation 获取 mutedExpiredTime ，即群禁言时间，单位为秒。

mutedExpiredTime 值说明如下：

为 -1 时，表示当前用户永久无法在该群组发言。
为 0 时，表示当前用户可以在该群组发言。
为其他值时，表示当前用户于该数值时间内无法在该群组发言。

说明

如果当前用户既因群角色被禁言（详见群组管理 - 禁言或解禁群组，又被单独禁言（详见本文设置群成员禁言状态），则 mutedExpiredTime 值以“群禁言时间”与“单独被禁言时间”中的最大值为准。