跳到主要内容

群成员管理

本文档旨在指导开发者如何使用融云即时通讯 Flutter IMLib SDK 实现设置或查询群组成员资料，添加或删除群管理员等功能。

提示

此功能从 5.18.0 版本开始支持。

开通服务​

使用此功能前，您须在控制台开通信息托管服务。

群成员​

支持查询指定群的群成员信息，并可设置群成员信息。

分页获取群成员信息​

您可以使用 getGroupMembersByRole 按群成员角色分页获取群成员信息。
此接口支持返回本次查询条件的总数，见 RCIMIWPagingQueryOption 的 getTotalCount 属性。

群成员角色 RCIMIWGroupMemberRole 枚举介绍：

枚举值群成员角色
undef未定义角色（使用此枚举查询代表查询全部类型群成员）
normal普通群成员
manager管理员
owner群主
提示

分页拉取说明：

  1. 首次拉取时，RCIMIWPagingQueryOption 的 pageToken 无需设置（不设置、设置null、设置""，效果等同）。
  2. 拉取第二页需要传入首次拉取返回结果 RCIMIWPagingQueryResult 类型中的 pageToken。
    • 如果不为 ""，则可以传入该值再次拉取，直至 pageToken 返回为 ""，表示全部拉取完成。
    • 如果为 ""，表示没有下一页或已拉取完成，无需再次拉取。如传递 ""，将视为拉取首页数据。

代码示例​

Dart
// 分页拉取参数（设置null与设置""，效果等同）
String pageToken = "";

Future<void> getGroupMembersByRole(String pageToken) async {
  // 群Id
  String groupId = "groupId";
  
  // 通过 role 参数指定拉取全部群成员角色类型的群成员信息
  RCIMIWGroupMemberRole role = RCIMIWGroupMemberRole.undef;
  
  // 分页请求参数
  RCIMIWPagingQueryOption option = RCIMIWPagingQueryOption.create(
    count: 20,  // 设置分页大小，取值范围为 [1~100]
    pageToken: pageToken,  // 分页拉取参数
    order: false,  // 按加入群组时间正序、倒序获取。true：正序；false：倒序
  );
  
  // 创建回调
  IRCIMIWGetGroupMembersByRoleCallback callback = IRCIMIWGetGroupMembersByRoleCallback(
    onSuccess: (RCIMIWPagingQueryResult<RCIMIWGroupMemberInfo>? result) {
      if (result != null && result.pageToken.isNotEmpty) {
        // 使用返回的 pageToken 拉取下一页
        getGroupMembersByRole(result.pageToken);
      } else {
        // 拉取结束
        print("群成员拉取完成");
      }
    },
    onError: (RCIMIWCoreErrorCode? code) {
      // 拉取失败
      print("拉取失败，code: $code");
    },
  );
  
  // 调用分页获取群成员方法
  int? code = await engine?.getGroupMembersByRole(
    groupId,
    role,
    option,
    callback: callback,
  );
}

获取群成员信息​

您可以使用 getGroupMembers 获取指定群指定用户的群成员信息。
该接口支持批量获取，您可以一次传入多个 userId 获取多个群成员信息，最多不超过 100 个。

提示

若当前用户未加入指定群组，则无法获取群成员信息。

代码示例​

Dart
// 群Id
String groupId = "groupId";

// 设置查询用户ID列表
List<String> userIdList = ["userId1", "userId2", "userId3"];

// 创建回调
IRCIMIWGetGroupMembersCallback callback = IRCIMIWGetGroupMembersCallback(
  onSuccess: (List<RCIMIWGroupMemberInfo>? groupMemberInfos) {
    // 拉取成功
    print("获取群成员信息成功，数量: ${groupMemberInfos?.length}");
  },
  onError: (RCIMIWCoreErrorCode? code) {
    // 拉取失败
    print("拉取失败，code: $code");
  },
);

// 调用获取群成员信息方法
int? code = await engine?.getGroupMembers(
  groupId,
  userIdList,
  callback: callback,
);

根据昵称搜索群成员信息​

您可以使用 searchGroupMembers 分页搜索本地群组中指定群的群成员信息。

搜索时优先匹配群成员昵称 nickname，再匹配群成员用户名 name。只要其中一个字段匹配成功，即返回搜索结果。

此接口不支持返回所有群成员总数。

提示

分页拉取说明：

  1. 首次拉取时，RCIMIWPagingQueryOption 的 pageToken 无需设置（不设置、设置null、设置""，效果等同）。
  2. 拉取第二页需要传入首次拉取返回结果 RCIMIWPagingQueryResult 类型中的 pageToken。
    • 如果不为 ""，则可以传入该值再次拉取，直至 pageToken 返回为 ""，表示全部拉取完成。
    • 如果为 ""，表示没有下一页或已拉取完成，无需再次拉取。如传递 ""，将视为拉取首页数据。

代码示例​

Dart
// 分页拉取参数（设置null与设置""，效果等同）
String pageToken = "";

Future<void> searchGroupMembers(String pageToken) async {
  // 群Id
  String groupId = "groupId";
  
  // 群成员昵称，不能为空最长不超过 64 个字符
  String name = "name";
  
  // 分页请求参数
  RCIMIWPagingQueryOption option = RCIMIWPagingQueryOption.create(
    count: 20,  // 设置分页大小，取值范围为 [1~200]
    pageToken: pageToken,  // 分页拉取参数
    order: false,  // 按加入群组时间正序、倒序获取。true：正序；false：倒序
  );
  
  // 创建回调
  IRCIMIWSearchGroupMembersCallback callback = IRCIMIWSearchGroupMembersCallback(
    onSuccess: (RCIMIWPagingQueryResult<RCIMIWGroupMemberInfo>? result) {
      if (result != null && result.pageToken.isNotEmpty) {
        // 使用返回的 pageToken 拉取下一页
        searchGroupMembers(result.pageToken);
      } else {
        // 拉取结束
        print("搜索完成");
      }
    },
    onError: (RCIMIWCoreErrorCode? code) {
      // 拉取失败
      print("搜索失败，code: $code");
    },
  );
  
  // 调用搜索群成员方法
  int? code = await engine?.searchGroupMembers(
    groupId,
    name,
    option,
    callback: callback,
  );
}

设置群成员信息​

您可以使用 setGroupMemberInfo 设置指定群的群成员信息。

接口调用成功后，群内所有人会收到群成员信息变更事件 onGroupMemberInfoChanged 回调。

群成员信息更新权限 memberInfoEditPermission (RCIMIWGroupMemberInfoEditPermission)，决定是否可以修改群成员信息，如果没有权限设置，调用将会返回错误码。

RCIMIWGroupMemberInfoEditPermission 枚举介绍：

枚举值群成员角色
ownerOrManagerOrSelf群主、管理员和当前用户，可以修改在群组中的成员信息
ownerOrSelf群主和当前用户，可以修改在群组中的成员信息
self只有当前用户可以修改，自己的群成员信息信息

代码示例​

Dart
// 群Id
String groupId = "groupId";

// 群成员用户Id
String userId = "userId1";

// 群成员昵称
String nickname = "nickname";

// 群成员附加信息
String extra = "群成员附加信息";

// 创建回调
IRCIMIWSetGroupMemberInfoCallback callback = IRCIMIWSetGroupMemberInfoCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("操作成功");
    } else {
      print("操作失败，code: $code");
    }
  },
);

// 调用设置群成员信息方法
int? code = await engine?.setGroupMemberInfo(
  groupId,
  userId,
  nickname,
  extra,
  callback: callback,
);

群管理员​

可以添加或者移除群管理员。

添加群管理员​

您可以使用 addGroupManagers 添加群管理员。

接口调用成功后，群内所有人会收到群组操作事件 onGroupOperation 回调，操作类型为 addManager。

提示
  • 只有群主可以添加群管理员。
  • 要设置的成员必须在此群内，且群主不能被设置为管理员。
  • 一个群组的管理员数量上限为 10 个。

代码示例​

Dart
// 群Id
String groupId = "groupId";

// 管理员用户Id列表
List<String> userIds = ["userId1", "userId2", "userId3"];

// 创建回调
IRCIMIWAddGroupManagersCallback callback = IRCIMIWAddGroupManagersCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("操作成功");
    } else {
      print("操作失败，code: $code");
    }
  },
);

// 调用添加群管理员方法
int? code = await engine?.addGroupManagers(
  groupId,
  userIds,
  callback: callback,
);

移除群管理员​

您可以使用 removeGroupManagers 移除群管理员。
该接口支持批量移除，您可以一次传入多个 userId 移除多个群管理员，最多不超过 10 个。

接口调用成功后，群内所有人会收到群组操作事件 onGroupOperation 回调，操作类型为 removeManager。

提示
  • 只有群主可以移除群管理员。

代码示例​

Dart
// 群Id
String groupId = "groupId";

// 管理员用户Id列表
List<String> userIds = ["userId1", "userId2", "userId3"];

// 创建回调
IRCIMIWRemoveGroupManagersCallback callback = IRCIMIWRemoveGroupManagersCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("操作成功");
    } else {
      print("操作失败，code: $code");
    }
  },
);

// 调用移除群管理员方法
int? code = await engine?.removeGroupManagers(
  groupId,
  userIds,
  callback: callback,
);

特别关注群成员​

可以添加、移除或者查询群特别关注成员。

功能介绍​

  • 特别关注群成员数量上限为 200 个。
  • 特别关注用户在该群发送的消息不受会话免打扰的设置影响，可正常发送通知提醒。
  • 针对特别关注用户发送的消息，推送优先级说明如下：
    • 应用级别免打扰状态为不发推送 > 消息体中标识该消息为静音消息 > 发送消息用户为特别关注用户 > 会话免打扰设置。
  • 免打扰相关说明详见 免打扰功能概述。
  • 特别关注群成员设置或移除成功后，该用户登录的其他终端会收到好友信息变更多端事件回调 onGroupFollowsChangedSync。

添加特别关注群成员​

您可以使用 addGroupFollows 添加特别关注群成员。
该接口支持批量添加，您可以一次传入多个 userId 添加多个特别关注群成员，最多不超过100个。

代码示例​

Dart
// 群Id
String groupId = "groupId";

// 群成员用户Id列表
List<String> userIds = ["userId1", "userId2", "userId3"];

// 创建回调
IRCIMIWAddGroupFollowsCallback callback = IRCIMIWAddGroupFollowsCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("操作成功");
    } else {
      print("操作失败，code: $code");
    }
  },
);

// 调用添加特别关注群成员方法
int? code = await engine?.addGroupFollows(
  groupId,
  userIds,
  callback: callback,
);

移除特别关注群成员​

您可以使用 removeGroupFollows 移除特别关注群成员。
该接口支持批量移除，您可以一次传入多个 userId 移除多个特别关注群成员，最多不超过100个。

代码示例​

Dart
// 群Id
String groupId = "groupId";

// 群成员用户Id列表
List<String> userIds = ["userId1", "userId2", "userId3"];

// 创建回调
IRCIMIWRemoveGroupFollowsCallback callback = IRCIMIWRemoveGroupFollowsCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("操作成功");
    } else {
      print("操作失败，code: $code");
    }
  },
);

// 调用移除特别关注群成员方法
int? code = await engine?.removeGroupFollows(
  groupId,
  userIds,
  callback: callback,
);

查询特别关注群成员​

您可以使用 getGroupFollows 查询特别关注群成员。

代码示例​

Dart
// 群Id
String groupId = "groupId";

// 创建回调
IRCIMIWGetGroupFollowsCallback callback = IRCIMIWGetGroupFollowsCallback(
  onSuccess: (List<RCIMIWFollowInfo>? followInfos) {
    // 拉取成功
    print("获取特别关注群成员成功，数量: ${followInfos?.length}");
  },
  onError: (RCIMIWCoreErrorCode? code) {
    // 拉取失败
    print("拉取失败，code: $code");
  },
);

// 调用查询特别关注群成员方法
int? code = await engine?.getGroupFollows(
  groupId,
  callback: callback,
);