群成员管理
本文档旨在指导开发者如何使用融云即时通讯 Web IMLib SDK 实现设置或查询群组成员资料,添加或删除群管理员等功能。
此功能从 5.12.0 版本开始支持。
开通服务
使用此功能前,您须在控制台开通信息托管服务。
群成员
可以查询指定群的群成员,也可以设置群成员信息。
群成员资料变更回调
调用 setGroupMemberInfo 方法,设置指定群的群成员信息成功后,群内所有人会收到群成员资料变更事件 Events.GROUP_MEMBER_INFO_CHANGED
回调。
- 事件监听器应全局注册,且仅注册一次,避免重复接收事件通知。
- 事件回调数据类型为 IGroupMemberInfoChanged
示例代码
RongIMLib.addEventListener(Events.GROUP_MEMBER_INFO_CHANGED, (data) => {
console.log('群成员资料变更回调', data);
});
分页获取群成员信息
调用 getGroupMembersByRole 方法,可按群成员角色分页获取指定群组中的成员信息,角色类型请参考 GroupMemberRole。
Web 端返回的 IPagingQueryResult 结构中暂不包含 totalCount 字段。
接口
RongIMLib.getGroupMembersByRole(groupId, role, option)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
role | GroupMemberRole | 是 | 群成员角色。设置为 GroupMemberRole.UNDEF 不区分角色或位置角色获取所有群成员。 |
option | IPagingQueryOption | 是 | 分页请求参数。 一页最多查询 100 条数据。 |
- 首次拉取时,
option
的pageToken
参数可不传或传''
,效果等同。 - 拉取下一页数据时,需传入上次接口返回结果中的 pageToken。
- 当
pageToken
不为''
,表示存在下一页,可继续拉取。 - 当
pageToken
为''
,表示数据已全部拉取完毕,继续传 '' 会视为拉取首页数据。
示例代码
const groupId = 'group001';
// 设置为 '' 代表移除。字符串长度不超过 64 个字符,如群备注名已存在则做替换处理,以最后一次设置为准
const role = RongIMLib.GroupMemberRole.UNDEF;
const option = {
// 必填,范围 1 ~ 100
count: 50,
}
const res = await RongIMLib.getGroupMembersByRole(groupId, role, option);
console.info('分页获取群成员信息', res);
// 拉取下一页
if (res && res.pageToken) {
const nextRes = await RongIMLib.getGroupMembersByRole(groupId, role, {
...option,
pageToken: res.pageToken
});
console.info('分页获取群成员信息,拉取下一页', nextRes);
}
获取群成员信息
调用 getGroupMembers 方法,获取指定群组内某些成员的详细信息。
接口
RongIMLib.getGroupMembers(groupId, userIds)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
userIds | string[] | 是 | 用户 ID 数组,最多不超过 100 个。 |
- 当前用户若不在该群组内,无法获取群成员信息。
- 仅支持查询群内已有成员信息,若
userIds
中包含非群成员的用户 ID,将自动过滤不返回。
示例代码
const groupId = 'group001';
// user01 如不在 group001 群组则返回 []
const userIds = ['user01'];
const res = await RongIMLib.getGroupMembers(groupId, userIds);
console.info('获取群成员信息', res);
根据昵称搜索群成员信息(仅 Electron)
仅支持 Electron 平台,Web 暂不支持。
调用 searchGroupMembers 方法,可分页搜索本地群组中指定群的群成员信息。
- 优先匹配群成员昵称(nickname),若昵称为空则匹配用户名(name)
- 任一字段匹配成功即返回该成员信息。
接口
RongIMLib.searchGroupMembers(groupId, name, option)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
name | string | 是 | 搜索名称,支持模糊匹配,不能传空字符串或纯空格,长度不超过 64 个字符。 |
option | IPagingQueryOption | 是 | 分页请求参数,每页最多查询 100 条数据。 |
- 首次拉取时,
option
的pageToken
参数可不传或传''
,效果等同。 - 拉取下一页数据时,需传入上次接口返回结果中的 pageToken。
- 当
pageToken
不为''
,表示存在下一页,可继续拉取。 - 当
pageToken
为''
,表示数据已全部拉取完毕,继续传 '' 会视为拉取首页数据。
示例代码
const groupId = 'group001';
// 不能为空,不可以传递纯空格,最长不超过 64 个字符
// 支持模糊搜索查询,昵称为空时搜索用户名
const name = 'name';
const option = {
// 必填,范围 1 ~ 100
count: 50,
}
const res = await RongIMLib.searchGroupMembers(groupId, name, option);
console.info('根据群成员昵称分页获取群成员信息', res);
// 拉取 下一页
if (res && res.pageToken) {
const nextRes = await RongIMLib.searchGroupMembers(groupId, name, {
...option,
pageToken: res.pageToken
});
console.info('根据群成员昵称分页获取群成员信息,拉取下一页', nextRes);
}
设置群成员资料
调用 setGroupMemberInfo 方法,可设置指定群的群成员信息。
- 调用成功后,群内所有用户会收到群成员资料变更事件 Events.GROUP_MEMBER_INFO_CHANGED 通知。
- 群成员资料更新权限
memberInfoEditPermission
类型为 GroupMemberInfoEditPermission,决定是否可以修改群成员资料,如果没有权限,返回错误码.
接口
RongIMLib.setGroupMemberInfo(groupId, userId, nickname, extra)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
userId | string | 是 | 群成员用户 ID。 |
nickname | string | 是 | 群成员昵称,长度不超过 64 个字符,不能为纯空格。 |
extra | string | 否 | 群成员附加信息,长度不超过 128 个字符。 |
示例代码
const groupId = 'group001'; // 群组 ID
const userId = 'user01'; // 群成员用户 ID
const nickname = 'nickname'; // 群成员昵称,长度不超过 64 个字符,nickname 不可为纯空格
const extra = 'extra info'; // 非必填,群成员附加信息,长度不超过 128 个字符
const res = await RongIMLib.setGroupMemberInfo(groupId, userId, nickname, extra);
console.info('设置群成员资料结果', res);
return res;
群管理员
可以添加或者移除群管理员。
添加群管理员
调用 addGroupManagers 方法,可添加群管理员。
- 只有群主可以调用此接口。
- 一个群组的管理员数量上限为 10 个。
- 添加群管理员成功,群内所有成员将收到 Events.GROUP_OPERATION 事件回调,事件中的 operation=5(GroupOperation.ADD_MANAGER)。
接口
RongIMLib.addGroupManagers(groupId, userIds)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | String | 是 | 群组 ID。 |
userIds | string[] | 是 | 用户 ID 数组,用户 ID 必须为群成员,最多添加 10 个管理员。 |
示例代码
const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组,必须为群成员,一次最多添加 10 个管理员
const res = await RongIMLib.addGroupManagers(groupId, userIds);
console.info('设置群管理员结果', res);
移除群管理员
调用 removeGroupManagers 方法,可移除群管理员。
添加群管理员成功,群内所有成员将收到 Events.GROUP_OPERATION 事件回调,事件中的 operation=6(GroupOperation.REMOVE_MANAGER)。
接口
RongIMLib.removeGroupManagers(groupId, userIds)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | String | 是 | 群组 ID。 |
userIds | Array | 是 | 用户 ID 数组,最多移除 10 个管理员。 |
示例代码
const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组,一次最多添加 10 个管理员
const res = await RongIMLib.removeGroupManagers(groupId, userIds);
console.info('设置群管理员结果', res);
特别关注群成员
支持为群组添加、移除及查询特别关注的群成员。
功能介绍
- 特别关注群成员数量上限为 200 个。
- 特别关注用户在该群发送的消息不受会话免打扰的设置影响,可正常发送通知提醒。
- 针对特别关注用户发送的消息,推送优先级说明如下:
- 应用级别免打扰状态为不发推送 > 消息体中标识该消息为静音消息 > 发送消息用户为特别关注用户 > 会话免打扰设置
- 免打扰相关说明详见 免打扰功能概述。
- 特别关注群成员设置或移除成功后,该用户登录的其他终端会收到好友信息变更多端事件回调 Events.GROUP_FOLLOWS_CHANGED_SYNC。
群成员特别关注变更多端回调
特别关注群成员设置或移除成功后,该用户登录的其他终端会收到好友信息变更多端事件回调。
- 事件监听器应全局注册,且仅注册一次,避免重复接收事件通知。
- 事件回调数据类型为 IGroupFollowsChangedSync。
示例代码
RongIMLib.addEventListener(Events.GROUP_FOLLOWS_CHANGED_SYNC, (data) => {
console.log('群成员特别关注变更多端回调', data);
});
添加特别关注群成员
调用 addGroupFollows 方法,可添加特别关注群成员。
特别关注群成员数量上限为 200 个。
接口
RongIMLib.addGroupFollows(groupId, userIds)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
userIds | string[] | 是 | 用户 ID 数组,单次最多添加 100 个用户。 |
示例代码
const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组,单次最多关注 100 个用户
const res = await RongIMLib.addGroupFollows(groupId, userIds);
console.info('设置群组成员关注结果', res);
移除特别关注群成员
调用 removeGroupFollows 方法,可移除特别关注群成员。
接口
RongIMLib.removeGroupFollows(groupId, userIds)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
userIds | string[] | 是 | 用户 ID 数组,单次取消关注 100 个用户。 |
示例代码
const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组,单次取消关注 100 个用户
const res = await RongIMLib.removeGroupFollows(groupId, userIds);
console.info('移除群组成员关注结果', res);
查询特别关注群成员
调用 getGroupFollows 方法,可查询特别关注群成员。
接口
RongIMLib.getGroupFollows(groupId)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
groupId | string | 是 | 群组 ID |
示例代码
const groupId = 'group001'; // 群组 ID
const res = await RongIMLib.getGroupFollows(groupId);
console.info('获取群组成员关注结果', res);