群成员管理

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

提示

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

开通服务

信息托管服务已默认开通，您可以直接使用此功能。

群成员

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

群成员资料变更回调

调用 setGroupMemberInfo 方法，设置指定群的群成员信息成功后，群内所有人会收到群成员资料变更事件 Events.GROUP_MEMBER_INFO_CHANGED 回调。

提示

• 事件监听器应全局注册，且仅注册一次，避免重复接收事件通知。
• 事件回调数据类型为 IGroupMemberInfoChanged

示例代码

javascript

RongIMLib.addEventListener(Events.GROUP_MEMBER_INFO_CHANGED, (data) => {
  console.log('群成员资料变更回调', data);
});

分页获取群成员信息

调用 getGroupMembersByRole 方法，可按群成员角色分页获取指定群组中的成员信息，角色类型请参考 GroupMemberRole。

注意

Web 端返回的 IPagingQueryResult 结构中暂不包含 totalCount 字段。

接口

JavaScript

RongIMLib.getGroupMembersByRole(groupId, role, option)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
role	GroupMemberRole	是	群成员角色。设置为 GroupMemberRole.UNDEF 不区分角色或位置角色获取所有群成员。
option	IGetGroupMembersOption	是	分页请求参数。 一页最多查询 100 条数据。

分页拉取说明

1. 首次拉取时，option 的 pageToken 参数可不传或传 ''，效果等同。
2. 拉取下一页数据时，需传入上次接口返回结果中的 pageToken。

• 当 pageToken 不为 ''，表示存在下一页，可继续拉取。
• 当 pageToken 为 ''，表示数据已全部拉取完毕，继续传 '' 会视为拉取首页数据。

示例代码

javascript

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 方法，获取指定群组内某些成员的详细信息。

接口

JavaScript

RongIMLib.getGroupMembers(groupId, userIds)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
userIds	string[]	是	用户 ID 数组，最多不超过 100 个。

提示

• 当前用户若不在该群组内，无法获取群成员信息。
• 仅支持查询群内已有成员信息，若 userIds 中包含非群成员的用户 ID，将自动过滤不返回。

示例代码

javascript

const groupId = 'group001';
// user01 如不在 group001 群组则返回 []
const userIds = ['user01'];
const res = await RongIMLib.getGroupMembers(groupId, userIds);
console.info('获取群成员信息', res);

根据昵称搜索群成员信息（仅 Electron）

注意

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

调用 searchGroupMembers 方法，可分页搜索本地群组中指定群的群成员信息。

搜索规则

• 优先匹配群成员昵称（nickname），若昵称为空则匹配用户名（name）
• 任一字段匹配成功即返回该成员信息。

接口

JavaScript

RongIMLib.searchGroupMembers(groupId, name, option)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
name	string	是	搜索名称，支持模糊匹配，不能传空字符串或纯空格，长度不超过 64 个字符。
option	IPagingQueryOption	是	分页请求参数，每页最多查询 100 条数据。

分页拉取说明

1. 首次拉取时，option 的 pageToken 参数可不传或传 ''，效果等同。
2. 拉取下一页数据时，需传入上次接口返回结果中的 pageToken。

• 当 pageToken 不为 ''，表示存在下一页，可继续拉取。
• 当 pageToken 为 ''，表示数据已全部拉取完毕，继续传 '' 会视为拉取首页数据。

示例代码

javascript

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，决定是否可以修改群成员资料，如果没有权限，返回错误码.

接口

JavaScript

RongIMLib.setGroupMemberInfo(groupId, userId, nickname, extra)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
userId	string	是	群成员用户 ID。
nickname	string	是	群成员昵称，长度不超过 64 个字符，不能为纯空格。
extra	string	否	群成员附加信息，长度不超过 128 个字符。

示例代码

javascript

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）。

接口

JavaScript

RongIMLib.addGroupManagers(groupId, userIds)

参数说明

参数	类型	必填	说明
groupId	String	是	群组 ID。
userIds	string[]	是	用户 ID 数组，用户 ID 必须为群成员，最多添加 10 个管理员。

示例代码

javascript

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）。

接口

JavaScript

RongIMLib.removeGroupManagers(groupId, userIds)

参数说明

参数	类型	必填	说明
groupId	String	是	群组 ID。
userIds	Array	是	用户 ID 数组，最多移除 10 个管理员。

示例代码

javascript

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。

示例代码

javascript

RongIMLib.addEventListener(Events.GROUP_FOLLOWS_CHANGED_SYNC, (data) => {
  console.log('群成员特别关注变更多端回调', data);
});

添加特别关注群成员

调用 addGroupFollows 方法，可添加特别关注群成员。

提示

特别关注群成员数量上限为 200 个。

接口

JavaScript

RongIMLib.addGroupFollows(groupId, userIds)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
userIds	string[]	是	用户 ID 数组，单次最多添加 100 个用户。

示例代码

javascript

const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组，单次最多关注 100 个用户

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

移除特别关注群成员

调用 removeGroupFollows 方法，可移除特别关注群成员。

接口

JavaScript

RongIMLib.removeGroupFollows(groupId, userIds)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID。
userIds	string[]	是	用户 ID 数组，单次取消关注 100 个用户。

示例代码

javascript

const groupId = 'group001'; // 群组 ID
const userIds = ['user001', 'user002']; // 用户 ID 数组，单次取消关注 100 个用户

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

查询特别关注群成员

调用 getGroupFollows 方法，可查询特别关注群成员。

接口

JavaScript

RongIMLib.getGroupFollows(groupId)

参数说明

参数	类型	必填	说明
groupId	string	是	群组 ID

示例代码

javascript

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