群组管理
本文档旨在指导开发者如何使用融云即时通讯 Web IMLib SDK 实现创建群组、群组资料设置、踢出群组、退出群组、解散群组、转让群组等功能。
- 此功能从 5.12.0 版本开始支持。
- 针对已经通过原群组功能接口
/group/create.json
创建的群组,默认不支持调用群托管的相关功能接口,需要调用“导入群托管数据”接口,设置群组所有者(群主)及群组的默认权限后才能使用。
开通服务
使用此功能前,您须在控制台开通信息托管服务。
群组操作
群组操作事件通知
群组操作包含:创建群组、群组资料设置、踢出群组、退出群组、解散群组、群组转让。可以通过 IGroupOperationInfo
中的 operation
来区分操作类型。
监听建议全局注册切仅注册一次,多次调用会通知多次。通知数据为 IGroupOperationInfo 类型。
RongIMLib.addEventListener(Events.GROUP_OPERATION, (data) => {
// data 为 IGroupOperationInfo 类型,通过 operation 来判断操作类型
console.log('群组操作变更', data);
});
群组资料变更通知
调用 updateGroupInfo
群组信息更新成功后,群组内的所有成员会收到 Events.GROUP_INFO_CHANGED
事件,事件通知仅包含变更项,未修改项值不会再 Events.GROUP_INFO_CHANGED
事件中返回。
监听建议全局注册切仅注册一次,多次调用会通知多次。通知数据为 IGroupInfoChanged 类型。
RongIMLib.addEventListener(Events.GROUP_INFO_CHANGED, (data) => {
console.log('群组资料变更通知', data);
});
创建群组
您可以调用 createGroup
方法创建一个新群组。
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
groupInfo | IGroupInfoOption | 是 | 群组信息。 |
inviteeUserIds | string[] | 否 | 您可以选择在创建群的同时,邀请用户加入群组。可以为空,一次最多允许 30 个用户加入。 |
groupInfo 参数介绍:
属性名 | 类型 | 必填 | 描述 |
---|---|---|---|
groupId | string | 是 | 群组 ID:最大长度 64 个字符。支持大小写英文字母与数字的组合。 |
groupName | string | 是 | 群组名称:最大长度 64 个字符。不可设置为纯空格。 |
portraitUri | string | 否 | 群头像 URL 地址:长度不超过 128 个字符。 |
introduction | string | 否 | 群简介:最大长度不超过 512 个字符。 |
notice | string | 否 | 群公告:最大长度不超过 1024 个字符。 |
extProfile | {[key: string]: string} | 否 | 扩展信息:在现在群信息基础上,开发者可根据自身业务需求添加自定义扩展属性(Key、Value),最多可设置 10 个扩展信息。 自定义属性需要通过开发者后台或 API 设置后才能使用,否则返回设置失败。 |
joinPermission | GroupJoinPermission | 否 | 主动加入群权限:不用验证、群主验证(默认)、群管理员及群主验证、不允许任何人加入,不设置按默认值处理。 |
removeMemberPermission | GroupOperationPermission | 否 | 将群成员移出群组权限:群主(默认)、群主+群管理员、所有人,不设置按默认值处理。 |
invitePermission | GroupOperationPermission | 否 | 谁可以邀请他人入群:群主(默认)、群主+群管理员、所有人,不设置按默认值处理。 |
inviteHandlePermission | GroupInviteHandlePermission | 否 | 邀请加入群组处理方式:不需要被邀请人同意(默认)、需要被邀请人同意,不设置按默认值处理。 |
groupInfoEditPermission | GroupOperationPermission | 否 | 修改群资料及权限:群主(默认)、群主+群管理员、所有人,不设置按默认值处理。。该属性仅支持群主修改 |
memberInfoEditPermission | GroupMemberInfoEditPermission | 否 | 设置群成员资料:仅自已、群主+自已、群主+群管理员+自已(默认),不设置按默认值处理。 |
-
创建群组成功,群主收到
Events.GROUP_OPERATION
监听,事件返回数据中operation
操作类型值为 0,对应枚举GroupOperation.CREATE
。 -
当设置了
inviteeUserIds
时,如果inviteHandlePermission
为GroupInviteHandlePermission.FREE
,被邀请人会自动加入群组。群组内所有成员会收到Events.GROUP_OPERATION
监听,事件返回数据中operation
操作类型值为 1,对应枚举GroupOperation.JOIN
。 -
当设置了
inviteeUserIds
时,如果inviteHandlePermission
为GroupInviteHandlePermission.INVITEE_VERIFY
- 当前用户接口会返回
processCode
值为 25427,表示需要等待邀请人同意后才能加入群组。 - 被邀请人会收到
Events.GROUP_APPLICATION_EVENT
事件,需要调用acceptGroupInvite
同意后才能加入群组。
- 当前用户接口会返回
const groupInfo = {
// 必填,最大长度 64 个字符。支持大小写英文字母与数字的组合
groupId: 'group001',
// 必填,最大长度 64 个字符
groupName: 'groupName',
// 自定义属性需要通过开发者后台或 API 设置后才能使用,否则返回设置失败
extProfile: {},
};
const memberIdsArr = ['userId001', 'userId002'];
const res = await RongIMLib.createGroup(groupInfo, memberIdsArr);
console.info('创建群组结果', res);
修改群组资料
您可以调用 updateGroupInfo
方法修改群组名称、公告、权限等其他资料。
修改群组资料时,只有 groupId
为必填项,其他字段可按需设置,接口只会更新有修改的项。
群组信息更新成功后,群组内的所有成员会收到 Events.GROUP_INFO_CHANGED
事件,事件通知仅包含变更项,未修改项值不会再 Events.GROUP_INFO_CHANGED
事件中返回。
groupInfo 参数介绍:
属性名 | 类型 | 必填 | 描述 |
---|---|---|---|
groupId | string | 是 | 群组 ID:最大长度 64 个字符。支持大小写英文字母与数字的组合。 |
groupName | string | 否 | 群组名称:最大长度 64 个字符。不可设置为纯空格。 |
portraitUri | string | 否 | 群头像 URL 地址:长度不超过 128 个字符。 |
introduction | string | 否 | 群简介:最大长度不超过 512 个字符。 |
notice | string | 否 | 群公告:最大长度不超过 1024 个字符。 |
extProfile | {[key: string]: string} | 否 | 扩展信息:在现在群信息基础上,开发者可根据自身业务需求添加自定义扩展属性(Key、Value),默认最多可设置 10 个扩展信息。 自定义属性需要通过开发者后台或 API 设置后才能使用,否则返回设置失败。 |
joinPermission | GroupJoinPermission | 否 | 主动加入群权限:不用验证、群主验证、群管理员及群主验证、不允许任何人加入。 |
removeMemberPermission | GroupOperationPermission | 否 | 将群成员移出群组权限:群主、群主+群管理员、所有人。 |
invitePermission | GroupOperationPermission | 否 | 谁可以邀请他人入群:群主、群主+群管理员、所有人。 |
inviteHandlePermission | GroupInviteHandlePermission | 否 | 邀请加入群组处理方式:不需要被邀请人同意、需要被邀请人同意。 |
groupInfoEditPermission | GroupOperationPermission | 否 | 修改群资料及权限:群主、群主+群管理员、所有人。 |
memberInfoEditPermission | GroupMemberInfoEditPermission | 否 | 设置群成员资料:仅自已、群主+自已、群主+群管理员+自已。 |
const groupInfo = {
// 必填,最大长度 64 个字符。支持大小写英文字母与数字的组合
groupId: 'group001',
introduction: 'group introduction',
};
const res = await RongIMLib.updateGroupInfo(groupInfo);
console.info('修改群组资料结果', res);
踢出群组
您可以调用 kickGroupMembers
方法将用户从群组中移除。支持一次移除多个用户,单次上限为 100 个。
踢出成功后,群组内的所有成员会收到 Events.GROUP_OPERATION
事件,事件返回数据中 operation
操作类型值为 2,对应枚举 GroupOperation.KICK
。
- 群主不可以被踢出。
- 踢出操作受群组的
removeMemberPermission
权限限制,符合限制条件的角色才可以进行操作。
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
memberIds | array | 是 | 要踢出的成员 ID 列表。 |
config | IQuitGroupConfig | 否 | 配置选项,控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config 默认为都移除。 |
const groupId = 'group001';
const memberIds = ['user01', 'user02'];
const config = {
// 默认为都移除
removeMuteStatus: true,
// 默认为都移除
removeWhiteList: true,
// 默认为都移除
removeFollow: true,
}
const res = await RongIMLib.kickGroupMembers(groupId, memberIds, config)
console.info('踢出群组结果', res);
退出群组
您可以调用 quitGroup
方法主动退出群组。
退出成功后,群组内的所有成员会收到 Events.GROUP_OPERATION
事件,事件返回数据中 operation
操作类型值为 3,对应枚举 GroupOperation.QUIT
。
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
groupId | string | 是 | 群组 ID。 |
config | IQuitGroupConfig | 否 | 配置选项,控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config,默认在退出群组时会全部移除。 |
const groupId = 'group001';
const res = await RongIMLib.quitGroup(groupId)
console.info('退出群组结果', res);
- 群主调 用
quitGroup
方法返回 25417 状态码提示:群主不能被踢出/退出群组。 - 群主需要先调用
transferGroupOwner
接口转让群组后再退出群组。
解散群组
只有群主有权解散群组。
您可以调用 dismissGroup
方法解散群组。
解散群组成功后,群会话消息仍然保留,历史消息不做删除处理。
解散成功后,群组内的所有成员会收到 Events.GROUP_OPERATION
事件,事件返回数据中 operation
操作类型值为 4,对应枚举 GroupOperation.DISMISS
。
const groupId = 'group001';
const res = await RongIMLib.dismissGroup(groupId)
console.info('解散群组结果', res);
转让群组
您可以调用 transferGroupOwner
方法将群组转让给其他用户。
- 只有群主有权转让群组。
- 若在转让时选择了退出群组,转让成功后,群组内的所有成员会收到
Events.GROUP_OPERATION
事件,事件返回数据中operation
操作类型值为 7,对应枚举GroupOperation.TRANSFER_GROUP_OWNER
。 - 退出成功后,群组内的所有成员会收到
Events.GROUP_OPERATION
事件,事件返回数据中operation
操作类型值为 3,对应枚举GroupOperation.QUIT
。