群成员管理
本文档旨在指导开发者如何使用融云即时通讯 Flutter IMLib SDK 实现设置或查询群组成员资料,添加或删除群管理员等功能。
此功能从 5.18.0 版本开始支持。
开通服务
使用此功能前,您须在控制台开通信息托管服务。
群成员
支持查询指定群的群成员信息,并可设置群成员信息。
分页获取群成员信息
您可以使用 getGroupMembersByRole
按群成员角色分页获取群成员信息。
此接口支持返回本次查询条件的总数,见 RCIMIWPagingQueryOption
的 getTotalCount
属性。
群成员角色 RCIMIWGroupMemberRole
枚举介绍:
枚举值 | 群成员角色 |
---|---|
undef | 未定义角色(使用此枚举查询代表查询全部类型群成员) |
normal | 普通群成员 |
manager | 管理员 |
owner | 群主 |
分页拉取说明:
- 首次拉取时,
RCIMIWPagingQueryOption
的pageToken
无需设置(不设置、设置null、设置"",效果等同)。 - 拉取第二页需要传入首次拉取返回结果
RCIMIWPagingQueryResult
类型中的pageToken
。- 如果不为 "",则可以传入该值再次拉取,直至
pageToken
返回为 "",表示全部拉取完成。 - 如果为 "",表示没有下一页或已拉取完成,无需再次拉取。如传递 "",将视为拉取首页数据。
- 如果不为 "",则可以传入该值再次拉取,直至
代码示例
// 分页拉取参数(设置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 个。
若当前用户未加入指定群组,则无法获取群成员信息。
代码示例
// 群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
。只要其中一个字段匹配成功,即返回搜索结果。
此接口不支持返回所有群成员总数。
分页拉取说明:
- 首次拉取时,
RCIMIWPagingQueryOption
的pageToken
无需设置(不设置、设置null、设置"", 效果等同)。 - 拉取第二页需要传入首次拉取返回结果
RCIMIWPagingQueryResult
类型中的pageToken
。- 如果不为 "",则可以传入该值再次拉取,直至
pageToken
返回为 "",表示全部拉取完成。 - 如果为 "",表示没有下一页或已拉取完成,无需再次拉取。如传递 "",将视为拉取首页数据。
- 如果不为 "",则可以传入该值再次拉取,直至
代码示例
// 分页拉取参数(设置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 | 只有当前用户可以修改,自己的群成员信息信息 |
代码示例
// 群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 个。
代码示例
// 群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
。
- 只有群主可以移除群管理员。
代码示例
// 群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个。
代码示例
// 群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个。
代码示例
// 群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
查询特别关注群成员。
代码示例
// 群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,
);