跳到主要内容

群成员管理

本文档指导您如何使用融云即时通讯(IM)Harmony IMLib SDK 实现设置或查询群组成员资料,添加或删除群管理员等功能。

提示

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

开通服务

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

群成员

可以查询指定群组的群成员,也可以设置群成员信息。

分页获取群成员信息

使用 getGroupMembersByRole 按群成员角色分页获取群成员信息。

此接口支持返回本次查询条件的总数,见 PagingQueryResulttotalCount

群成员角色 GroupMemberRole 枚举介绍:

枚举值群成员角色
Undef未定义角色(使用此枚举查询代表查询全部类型群成员)
Normal普通群成员
Manager群管理员
Owner群主
提示

分页拉取说明:

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

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 通过 role 参数指定拉取全部群成员角色类型的群成员信息
let role : GroupMemberRole = GroupMemberRole.Undef; // 未定义角色(使用此枚举代表查询全部类型群成员)
// 分页拉取参数
let pageToken = "";
// 设置分页大小,取值范围为 [1~100]
let count = 10;
// 按加入群组时间正序、倒序获取。true:正序;false:倒序
let order = false;
// 分页请求参数
let paging_option = new PagingQueryOption(pageToken, count, order);

IMEngine.getInstance().getGroupMembersByRole(groupId, role, paging_option).then(result => {
if (EngineError.Success !== result.code) {
// 拉取失败
return;
}

if (result.data) {
let ret: PagingQueryResult<GroupMemberInfo> = result.data;
let pageToken: string = ret?.pageToken;
let totalCount: number = ret?.totalCount;
let data = Array.from(ret.data as Array<GroupMemberInfo>);
// 使用返回的 pageToken 拉取下一页
}
});

获取群成员信息

使用 getGroupMembers 获取指定群组指定用户的群成员信息。

该接口支持批量获取,您可以一次传入多个 userId 获取多个群成员信息,最多不超过 100 个。

提示

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

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 设置查询用户 ID 列表
let userIds = ["user1Id", "user2Id"];

IMEngine.getInstance().getGroupMembers(groupId, userIds).then(result => {
if (EngineError.Success !== result.code) {
// 拉取失败
return;
}

// 拉取成功
let ret: object = result;
if (result.data) {
ret = Array.from(result.data as Array<GroupMemberInfo>);
}
});

根据昵称搜索群成员信息

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

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

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

提示

分页拉取说明:

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

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 群成员昵称,不能为空最长不超过 64 个字符
let nickname = "name";
// 分页请求参数
let pageToken = null; // 首次查询可以传 null
// 设置分页大小,取值范围为 [1~200]
let count = 10;
// 按加入群组时间正序、倒序获取。true:正序;false:倒序
let order = false;
// 分页请求参数
let paging_option = new PagingQueryOption(pageToken, count, order);

IMEngine.getInstance().searchGroupMembers(groupId, nickname, paging_option).then(result => {
if (EngineError.Success !== result.code) {
// 拉取失败
return;
}

// 拉取成功
if (result.data) {
let ret: PagingQueryResult<GroupMemberInfo> = result.data;
let pageToken: string = ret.pageToken;
let totalCount: number = ret.totalCount;
let data = Array.from(ret.data as Array<GroupMemberInfo>);
// 使用返回的 pageToken 拉取下一页
}
});

设置群成员信息

使用 setGroupMemberInfo 设置指定群组的群成员信息。

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

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

GroupMemberInfoEditPermission 枚举介绍:

枚举值群成员角色
OwnerOrManagerOrSelf群主、管理员和当前用户,可以修改在群组中的成员信息
OwnerOrSelf群主和当前用户,可以修改在群组中的成员信息
Self只有当前用户可以修改自己的群成员资料信息

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 群成员用户 ID
let userId = "userId";
// 群成员昵称
let nickname = "name";
// 群成员附加信息
let extra = "extra";

IMEngine.getInstance().setGroupMemberInfo(groupId, userId, nickname, extra).then(result => {
if (EngineError.Success !== result.code) {
// 操作失败
if (result.data) {
let array: Array<string> = result.data; // 失败的 key 数组
}
}
// 操作成功
});

群管理员

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

添加群管理员

使用 addGroupManagers 添加群管理员。

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

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

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 管理员用户 ID 列表
let userIds = ["user1Id", "user2Id"];

IMEngine.getInstance().addGroupManagers(groupId, userIds).then(result => {
if (EngineError.Success !== result.code) {
// 添加失败
}
// 添加成功
});

移除群管理员

使用 removeGroupManagers 移除群管理员。

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

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

提示

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

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 管理员用户 ID 列表
let userIds = ["user1Id", "user2Id"];

IMEngine.getInstance().removeGroupManagers(groupId, userIds).then(result => {
if (EngineError.Success !== result.code) {
// 移除失败
}
// 移除成功
});

特别关注用户

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

功能介绍

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

添加特别关注用户

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

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 用户 ID 列表
let userIds = ["user1Id", "user2Id"];

IMEngine.getInstance().addGroupFollows(groupId, userIds).then(result => {
if (EngineError.Success !== result.code) {
// 添加失败
}
// 添加成功
});

移除特别关注用户

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

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";
// 用户 ID 列表
let userIds = ["user1Id", "user2Id"];

IMEngine.getInstance().removeGroupFollows(groupId, userIds).then(result => {
if (EngineError.Success !== result.code) {
// 移除失败
}
// 移除成功
});

查询特别关注用户

使用 getGroupFollows 查询特别关注用户。

代码示例

TypeScript
// 群组 ID
let groupId = "groupId";

IMEngine.getInstance().getGroupFollows(groupId).then(result => {
if (EngineError.Success !== result.code) {
// 查询失败
return;
}

// 查询成功
let ret : Object = result;
if (result.data) {
ret = Array.from(result.data);
}
});