跳到主要内容

版本:5.X

群成员管理

本文档旨在指导开发者如何使用融云即时通讯 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

提示

分页拉取说明:

  1. 首次拉取时,optionpageToken 无需设置(不传递或设置 '',效果等同)。
  2. 拉取第二页需要传入首次拉取返回结果 IPagingQueryResult 类型中的 pageToken
    • 如果不为 '',则可以传入该值再次拉取,直至 pageToken 返回为 '',表示全部拉取完成。
    • 如果为 '',表示没有下一页,或已拉取完成,无需在此拉取,如传递 '',拉取将视为拉取首页数据。
参数名类型必填描述
groupIdstring群组 ID。
roleGroupMemberRole群成员角色,指定只拉取该角色的群成员信息。设置为 GroupMemberRole.UNDEF 不区分角色或位置角色获取所有群成员。
optionIPagingQueryOption分页请求参数。 一页最多查询 100 条数据。
注意

Web 返回的 IPagingQueryResult 结构中暂不支持返回 totalCount

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 获取指定群指定用户的群成员信息。

提示
  1. 当前用户未在群组中不支持获取群成员信息。

  2. userIds 获取多个群成员信息,最多不超过 100 个。

  3. 仅支持查询群组内成员信息,如输入 userIds 数组中包含未在群组的 userId 过滤不做返回。

参数名类型必填描述
groupIdstring群组 ID。
userIdsstring[]用户 ID 数组,最多不超过 100 个。
const groupId = 'group001';
// user01 如不在 group001 群组则返回 []
const userIds = ['user01'];
const res = await RongIMLib.getGroupMembers(groupId, userIds);
console.info('获取群成员信息', res);

根据昵称搜索群成员信息(仅 Electron)

注意

仅支持 Electron 平台,Web 暂不支持。

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

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

提示

分页拉取说明:

  1. 首次拉取时,optionpageToken 无需设置(不传递或设置 '',效果等同)。
  2. 拉取第二页需要传入首次拉取返回结果 IPagingQueryResult 类型中的 pageToken
    • 如果不为 '',则可以传入该值再次拉取,直至 pageToken 返回为 '',表示全部拉取完成。
    • 如果为 '',表示没有下一页,或已拉取完成,无需在此拉取,如传递 '',拉取将视为拉取首页数据。
参数名类型必填描述
groupIdstring群组 ID。
namestring搜索名称,支持模糊搜索查询,昵称为空时搜索用户名,不能为空,不能为纯空格,最长不超过 64 个字符。
optionIPagingQueryOption分页请求参数。 一页最多查询 100 条数据。
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,决定是否可以修改群成员资料,如果没有权限,返回错误码.

参数名类型必填描述
groupIdstring群组 ID。
userIdstring群成员用户 ID。
nicknamestring群成员昵称。长度不超过 64 个字符,nickname 不可为纯空格。
extrastring群成员附加信息。长度不超过 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 添加群管理员。

添加群管理员成功,群内全部成员收到 Events.GROUP_OPERATION 回调,事件返回数据中 operation 操作类型值为 5,对应枚举 GroupOperation.ADD_MANAGER

提示
  • 只有群主可以调用此接口。
  • 一个群组的管理员数量上限为 10 个。
参数名类型必填描述
groupIdstring群组 ID。
userIdsstring[]用户 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

参数名类型必填描述
groupIdstring群组 ID。
userIdsstring[]用户 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 个。

参数名类型必填描述
groupIdstring群组 ID。
userIdsstring[]用户 ID 数组,单次最多关注 100 个用户。
const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组,单次最多关注 100 个用户

const res = await RongIMLib.addGroupFollows(groupId, userIds);
console.info('设置群组成员关注结果', res);

移除特别关注群成员

您可以使用 removeGroupFollows 移除特别关注群成员。

参数名类型必填描述
groupIdstring群组 ID。
userIdsstring[]用户 ID 数组,单次取消关注 100 个用户。
const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组,单次取消关注 100 个用户

const res = await RongIMLib.removeGroupFollows(groupId, userIds);
console.info('移除群组成员关注结果', res);

查询特别关注群成员

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

const groupId = 'group001'; // 群组 ID
const res = await RongIMLib.getGroupFollows(groupId);
console.info('获取群组成员关注结果', res);