跳到主要内容

群组管理

本文档旨在指导开发者如何使用融云即时通讯 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 方法创建一个新群组。

参数名类型必填描述
groupInfoIGroupInfoOption是群组信息。
inviteeUserIdsstring[]否您可以选择在创建群的同时，邀请用户加入群组。可以为空，一次最多允许 30 个用户加入。

groupInfo 参数介绍：

属性名类型必填描述
groupIdstring是群组 ID：最大长度 64 个字符。支持大小写英文字母与数字的组合。
groupNamestring是群组名称：最大长度 64 个字符。不可设置为纯空格。
portraitUristring否群头像 URL 地址：长度不超过 128 个字符。
introductionstring否群简介：最大长度不超过 512 个字符。
noticestring否群公告：最大长度不超过 1024 个字符。
extProfile{[key: string]: string}否扩展信息：在现在群信息基础上，开发者可根据自身业务需求添加自定义扩展属性（Key、Value），最多可设置 10 个扩展信息。 自定义属性需要通过开发者后台或 API 设置后才能使用，否则返回设置失败。
joinPermissionGroupJoinPermission否主动加入群权限：不用验证、群主验证（默认）、群管理员及群主验证、不允许任何人加入，不设置按默认值处理。
removeMemberPermissionGroupOperationPermission否将群成员移出群组权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。
invitePermissionGroupOperationPermission否谁可以邀请他人入群：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。
inviteHandlePermissionGroupInviteHandlePermission否邀请加入群组处理方式：不需要被邀请人同意（默认）、需要被邀请人同意，不设置按默认值处理。
groupInfoEditPermissionGroupOperationPermission否修改群资料及权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。。该属性仅支持群主修改
memberInfoEditPermissionGroupMemberInfoEditPermission否设置群成员资料：仅自已、群主+自已、群主+群管理员+自已（默认），不设置按默认值处理。
提示

  1. 创建群组成功，群主收到 Events.GROUP_OPERATION 监听，事件返回数据中 operation 操作类型值为 0，对应枚举 GroupOperation.CREATE。

  2. 当设置了inviteeUserIds 时，如果 inviteHandlePermission 为 GroupInviteHandlePermission.FREE，被邀请人会自动加入群组。群组内所有成员会收到 Events.GROUP_OPERATION 监听，事件返回数据中 operation 操作类型值为 1，对应枚举 GroupOperation.JOIN。

  3. 当设置了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 参数介绍：

属性名类型必填描述
groupIdstring是群组 ID：最大长度 64 个字符。支持大小写英文字母与数字的组合。
groupNamestring否群组名称：最大长度 64 个字符。不可设置为纯空格。
portraitUristring否群头像 URL 地址：长度不超过 128 个字符。
introductionstring否群简介：最大长度不超过 512 个字符。
noticestring否群公告：最大长度不超过 1024 个字符。
extProfile{[key: string]: string}否扩展信息：在现在群信息基础上，开发者可根据自身业务需求添加自定义扩展属性（Key、Value），默认最多可设置 10 个扩展信息。 自定义属性需要通过开发者后台或 API 设置后才能使用，否则返回设置失败。
joinPermissionGroupJoinPermission否主动加入群权限：不用验证、群主验证、群管理员及群主验证、不允许任何人加入。
removeMemberPermissionGroupOperationPermission否将群成员移出群组权限：群主、群主+群管理员、所有人。
invitePermissionGroupOperationPermission否谁可以邀请他人入群：群主、群主+群管理员、所有人。
inviteHandlePermissionGroupInviteHandlePermission否邀请加入群组处理方式：不需要被邀请人同意、需要被邀请人同意。
groupInfoEditPermissionGroupOperationPermission否修改群资料及权限：群主、群主+群管理员、所有人。
memberInfoEditPermissionGroupMemberInfoEditPermission否设置群成员资料：仅自已、群主+自已、群主+群管理员+自已。
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 权限限制，符合限制条件的角色才可以进行操作。
参数名类型必填描述
groupIdstring是群组 ID。
memberIdsarray是要踢出的成员 ID 列表。
configIQuitGroupConfig否配置选项，控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 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。

参数名类型必填描述
groupIdstring是群组 ID。
configIQuitGroupConfig否配置选项，控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config，默认在退出群组时会全部移除。
const groupId = 'group001';
const res = await RongIMLib.quitGroup(groupId)
console.info('退出群组结果', res);
提示
  1. 群主调用 quitGroup 方法返回 25417 状态码提示：群主不能被踢出/退出群组。
  2. 群主需要先调用 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。
参数名类型必填描述
groupIdstring是群组 ID。
newOwnerIdstring是转让后的群主用户 ID。
quitGroupboolean否转让后是否退出群组，默认值为 false。
configIQuitGroupConfig否仅在 quitGroup 为 true 时生效，控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config，默认在退出群组时会全部移除。
// 必填，群组 ID
const groupId = 'group001';
// 必填，转让后的群主用户ID
const newOwnerId = 'newOwnerId';
// 转让后是否退出群组，默认 false。
const quitGroup = true; 
// 该配置参数仅在 quitGroup 为 true 时生效
const config = {
    // 默认为都移除
    removeMuteStatus: true, 
    // 默认为都移除
    removeWhiteList: true,
    // 默认为都移除
    removeFollow: true,
}
const res = await RongIMLib.transferGroupOwner(groupId, newOwnerId, quitGroup, config);
console.info('转让群组结果', res);

群组备注名​

群组备注名只对用户当前用户生效。当群组中有新消息产生且该用户不在线时，推送标题将优先显示设置的群备注名。若用户未对该群设置备注名，则默认显示群名称。

群名称备注名更新多端同步通知​

设置或移除成功后，其他终端会收到好友信息变更多端同步 Events.GROUP_REMARK_CHANGED_SYNC。

监听建议全局注册切仅注册一次，多次调用会通知多次。通知数据为 IGroupRemarkChangedSync 类型。

RongIMLib.addEventListener(Events.GROUP_REMARK_CHANGED_SYNC, (data) => {
  console.log('群名称备注名更新多端同步通知', data);
});

设置群组备注名​

您可以调用 setGroupRemark 方法设置群组备注名。

当需要移除群组备注名时，remark 参数传 ''。

参数名类型必填描述
groupIdstring是群组 ID。
remarkstring是群备注名。设置为 '' 代表移除。字符串长度不超过 64 个字符，如群备注名已存在则做替换处理，以最后一次设置为准。
提示
  1. 群组备注名只对用户当前用户生效。当群组中有新消息产生且该用户不在线时，推送标题将优先显示设置的群备注名。若用户未对该群设置备注名，则默认显示群名称。
  2. remark 不可以设置为纯空格。
const groupId = 'group001';
// 设置为 '' 代表移除。字符串长度不超过 64 个字符，如群备注名已存在则做替换处理，以最后一次设置为准
const remark = 'remark';
const res = await RongIMLib.setGroupRemark(groupId, remark);
// 需要输入存在的群组 ID，否则无法查询到群组信息，打印语句会抛异常
console.info('设置群组备注名结果', res);

查询群组备注名​

您可以使用 getGroupsInfo 方法获取群组资料，其中包含有关 remark 信息。

// 必填项，群 ID 数组，单次查询最多支持 20 个群组。
const groupIds = ['group001']
const res = await RongIMLib.getGroupsInfo(groupIds);
// 需要输入存在的群组 ID，否则无法查询到群组信息，打印语句会抛异常
console.info('群组备注名称', res[0].remark);
最后于 更新