群组管理

本文档旨在指导开发者如何使用融云即时通讯 Flutter IMLib SDK 实现创建群组、群组资料设置、踢出群组、退出群组、解散群组、转让群组等功能。

提示

• 此功能从 5.18.0 版本开始支持。
• 针对已经通过原群组功能接口/group/create.json创建的群组，默认不支持调用群托管的相关功能接口，需要调用"导入群托管数据"接口，设置群主及群组的默认权限后才能使用。

开通服务

使用此功能前，您须在控制台开通信息托管服务。

群事件监听

群事件监听器直接在 RCIMIWEngine 实例上设置，包含群操作、群信息群成员信息变更、加群申请相关通知、群备注名多端同步、群特别关注多端同步等回调。
您可以直接在引擎实例上设置相应的回调函数，如果不想再接收某个事件，将对应的回调函数设置为 null 即可。

提示

信息托管服务中，群组操作产生的 SDK 通知回调也是一种状态通知行为，无论应用是否实现 SDK 的事件监听，服务端都会对 SDK 进行状态同步，确保本地为最新的数据信息，所以会计入消息的分发、下行数据统计中。

代码示例

Dart

// 获取引擎实例
RCIMIWEngine? engine = await RCIMIWEngine.create(appKey, options);

// 设置群组操作回调
engine?.onGroupOperation = (String? groupId, RCIMIWGroupMemberInfo? operatorInfo, 
    RCIMIWGroupInfo? groupInfo, RCIMIWGroupOperation? operation, 
    List<RCIMIWGroupMemberInfo>? memberInfos, int? operationTime) {
  // 执行群操作后的回调：包括创建群、加入群、踢出、退出、解散、添加管理员、移除管理员、转让群主
  // 具体参照 RCIMIWGroupOperation 枚举
  print("群组操作: $operation, 群组ID: $groupId");
};

// 设置群组资料变更回调
engine?.onGroupInfoChanged = (RCIMIWGroupMemberInfo? operatorInfo, 
    RCIMIWGroupInfo? groupInfo, List<String>? updateKeys, int? operationTime) {
  // 群组资料变更回调。注意：只有包含在 updateKeys 中的属性值有效
  print("群组资料变更: $updateKeys");
};

// 设置群成员资料变更回调
engine?.onGroupMemberInfoChanged = (String? groupId, RCIMIWGroupMemberInfo? operatorInfo, 
    RCIMIWGroupMemberInfo? memberInfo, int? operationTime) {
  // 群成员资料变更回调
  print("群成员资料变更: 群组ID $groupId");
};

// 设置群申请事件回调
engine?.onGroupApplicationEvent = (RCIMIWGroupApplicationInfo? info) {
  // 群请求事件回调。包含以下事件：
  // 1，用户申请加入群组的 "申请" 或 "结果"
  // 2，邀请加入群组的 "申请" 或 "结果"
  print("群申请事件: ${info?.type}");
};

// 设置群备注名更新多端同步回调
engine?.onGroupRemarkChangedSync = (String? groupId, RCIMIWGroupOperationType? operationType, 
    String? groupRemark, int? operationTime) {
  // 群名称备注名更新多端同步回调事件
  print("群备注名同步: 群组ID $groupId, 操作类型 $operationType");
};

// 设置群成员特别关注变更多端同步回调
engine?.onGroupFollowsChangedSync = (String? groupId, RCIMIWGroupOperationType? operationType, 
    List<String>? userIds, int? operationTime) {
  // 群成员特别关注变更多端回调事件
  print("群特别关注同步: 群组ID $groupId, 用户列表 $userIds");
};

群组管理

群组管理包含：创建群组、群组资料设置、踢出群组、退出群组、解散群组、群组转让。

创建群组

您可以调用 createGroup 方法创建一个新群组。

群资料 RCIMIWGroupInfo 参数介绍：

属性名	类型	必填	描述
groupId	String	是	群组 ID：最大长度 64 个字符。支持大小写英文字母与数字的组合。
groupName	String	是	群组名称：最大长度 64 个字符。
portraitUri	String?	否	群头像地址：长度不超过 128 个字符
introduction	String?	否	群简介：最大长度不超过 512 个字符
notice	String?	否	群公告：最大长度不超过 1024 个字符
extProfile	Map<String, String>?	否	扩展信息：在现有群信息基础上，开发者可根据自身业务需求添加自定义扩展属性（Key、Value），最多可设置 10 个扩展信息。 自定义属性需要通过融云控制台 群组自定义属性 设置后才能使用，否则返回设置失败
joinPermission	RCIMIWGroupJoinPermission	否	加入群组的权限：不用验证、需要群主验证（默认）、需要群管理员及群主验证、不允许任何人加入，不设置按默认值处理
removeMemberPermission	RCIMIWGroupOperationPermission	否	将群成员移出群组的权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理
invitePermission	RCIMIWGroupOperationPermission	否	邀请他人加入群组的权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理
inviteHandlePermission	RCIMIWGroupInviteHandlePermission	否	被邀请加入群组处理的权限：不需要被邀请人同意（默认）、需要被邀请人同意，不设置按默认值处理
groupInfoEditPermission	RCIMIWGroupOperationPermission	否	修改群资料的权限：群主（默认）、群主+群管理员、所有人，不设置按默认值处理。此权限只有群主可以修改
memberInfoEditPermission	RCIMIWGroupMemberInfoEditPermission	否	设置群成员资料的权限：仅自已、群主+自已、群主+群管理员+自已（默认），不设置按默认值处理

inviteeUserIds 参数介绍

您可以选择在创建群的同时，邀请用户加入群组。一次最多允许 30 个用户加入。

邀请的结果受群组的 被邀请人处理权限 (inviteHandlePermission) 参数影响：

• 需要被邀请人验证 (inviteeVerify) 时，创建群组成功后，成功回调的 RCIMIWCoreErrorCode 会返回 rcGroupNeedInviteeAccept(25427)，被邀请人会收到 onGroupApplicationEvent 事件，需要调用 acceptGroupInvite 接口同意后才能加入群组。
• 无需被邀请人验证 (free) 时，创建群组成功后，成功回调的 RCIMIWCoreErrorCode 会返回 success(0)， 表示被邀请人已加入群组。

提示

• 群组创建的结果不受 RCIMIWCoreErrorCode 的影响，只要回调了 onSuccess 就表示群组创建成功。
• 创建群组成功，群主会收到 onGroupOperation 回调，RCIMIWGroupOperation 类型 create。

代码示例

Dart

// 创建群组信息
RCIMIWGroupInfo groupInfo = RCIMIWGroupInfo.create(
  groupId: "groupId",  // 群Id。必填，否则创建失败返回错误码
  groupName: "groupName",  // 群名称。必填，否则创建失败返回错误码
);

// 设置其他可选属性
groupInfo.portraitUri = "https://example.com/group_avatar.png";
groupInfo.introduction = "这是一个测试群组";
groupInfo.notice = "群公告内容";

// 设置加入群组的用户Id。非必填
List<String> inviteeUserIds = ["userId1", "userId2", "userId3"];

// 创建回调（可选）
IRCIMIWCreateGroupCallback? callback = IRCIMIWCreateGroupCallback(
  onSuccess: (RCIMIWCoreErrorCode? processCode) {
    // 创建群组请求成功
    print("创建群组成功，processCode: $processCode");
  },
  onError: (RCIMIWCoreErrorCode? code, String? errorData) {
    // 创建群组请求失败，如果errorData不为空，代表GroupInfo具体出错的key
    print("创建群组失败，code: $code, errorData: $errorData");
  },
);

// 调用创建群组方法
int? code = await engine?.createGroup(
  groupInfo,
  inviteeUserIds,
  callback: callback,
);

修改群组资料

您可以调用 updateGroupInfo 方法修改群组名称、公告、权限等其他资料。修改群组资料时，只有 groupId 为必填项，其他字段可按需设置，接口只会更新有修改的项。

提示

• 群组信息更新成功后，群组内的所有成员会收到 onGroupInfoChanged 回调。
• 群信息更新权限：groupInfoEditPermission，只有群主可以修改。

代码示例

Dart

// 创建要更新的群组信息
RCIMIWGroupInfo groupInfo = RCIMIWGroupInfo.create(
  groupId: "groupId",  // 群Id，必填
  groupName: "新的群名称",  // 要更新的群名称
);

// 设置要更新的其他属性
groupInfo.notice = "新的群公告";
groupInfo.introduction = "新的群简介";

// 创建回调（可选）
IRCIMIWUpdateGroupInfoCallback? callback = IRCIMIWUpdateGroupInfoCallback(
  onGroupInfoUpdated: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("更新群组信息成功");
    } else {
      print("更新群组信息失败，code: $code");
    }
  },
);

// 调用更新群组信息方法
int? code = await engine?.updateGroupInfo(
  groupInfo,
  callback: callback,
);

踢出群组

您可以调用 kickGroupMembers 方法踢出群组。

该接口支持批量移除，您可以一次传入多个 userId 移除多个用户，最多不超过 100 个。

在移除时可以设置 RCIMIWQuitGroupConfig 配置项，控制是否移除特别关注的用户、白名单用户、群成员禁言状态。如果不设置，默认为都移除。

将群成员移出群组权限 removeMemberPermission (RCIMIWGroupOperationPermission)，决定是否可以踢出群组，如果没有权限设置，调用将会返回错误码。

提示

• 踢出成功后，群组内所有成员会收到 onGroupOperation 回调，RCIMIWGroupOperation 类型是 kick。

代码示例

Dart

// 群Id
String groupId = "groupId";

// 用户ID列表
List<String> userIds = ["userId1", "userId2", "userId3"];

// 创建配置（可选）
RCIMIWQuitGroupConfig config = RCIMIWQuitGroupConfig.create(
  removeFollow: false,  // 关闭移除群组特别关注的用户（默认为 true）
  removeWhiteList: false,  // 关闭移除白名单（默认为 true）
  removeMuteStatus: false,  // 关闭移除群成员禁言状态（默认为 true）
);

// 创建回调（可选）
IRCIMIWKickGroupMembersCallback? callback = IRCIMIWKickGroupMembersCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("踢出成功");
    } else {
      print("踢出失败，code: $code");
    }
  },
);

// 调用踢出群成员方法
int? code = await engine?.kickGroupMembers(
  groupId,
  userIds,
  config: config,
  callback: callback,
);

退出群组

您可以调用 quitGroup 方法主动退出群组。

在退出时可以设置 RCIMIWQuitGroupConfig 配置项，以控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config，默认在退出群组时会全部移除。

提示

• 退出成功后，群组内的所有成员会收到 onGroupOperation 事件，RCIMIWGroupOperation 类型是 quit。

代码示例

Dart

// 群Id
String groupId = "groupId";

// 创建配置（可选）
RCIMIWQuitGroupConfig config = RCIMIWQuitGroupConfig.create(
  removeFollow: false,  // 关闭移除群组特别关注的用户（默认为 true）
  removeWhiteList: false,  // 关闭移除白名单（默认为 true）
  removeMuteStatus: false,  // 关闭移除群成员禁言状态（默认为 true）
);

// 创建回调（可选）
IRCIMIWQuitGroupCallback? callback = IRCIMIWQuitGroupCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("退出成功");
    } else {
      print("退出失败，code: $code");
    }
  },
);

// 调用退出群组方法
int? code = await engine?.quitGroup(
  groupId,
  config: config,
  callback: callback,
);

解散群组

您可以调用 dismissGroup 方法解散群组。

解散群组成功后，群会话消息仍然保留，本地历史消息不做删除处理。

提示

• 只有群主有权解散群组。
• 解散成功后，群组内的所有成员会收到 onGroupOperation 事件，RCIMIWGroupOperation 类型是 dismiss。

代码示例

Dart

// 群Id
String groupId = "groupId";

// 创建回调（可选）
IRCIMIWDismissGroupCallback? callback = IRCIMIWDismissGroupCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("解散成功");
    } else {
      print("解散失败，code: $code");
    }
  },
);

// 调用解散群组方法
int? code = await engine?.dismissGroup(
  groupId,
  callback: callback,
);

转让群组

您可以调用 transferGroupOwner 方法将群组转让给其他用户。

通过设置 quitGroup 参数，您可以选择在转让成功后是否退出群组，若设置 true 退出群组，您还可以设置 RCIMIWQuitGroupConfig 配置项，以控制是否移除特别关注的用户、白名单用户、群成员禁言状态。若未设置 config，默认在退出群组时会全部移除。

退出成功后，群组内的所有成员会收到 onGroupOperation 事件，RCIMIWGroupOperation 类型是 transferGroupOwner。

若在转让时选择了退出群组，转让成功后，群组内的所有成员除了会收到 onGroupOperation 操作类型为 transferGroupOwner 的转让事件，还会收到操作类型为 quit 的退出事件。

提示

• 只有群主有权转让群组。

代码示例

Dart

// 群Id
String groupId = "groupId";

// 转让后的群主用户ID
String newOwnerId = "userId1";

// 转让后是否退出群组
bool quitGroup = true;

// 创建配置（可选，仅在 quitGroup 为 true 时生效）
RCIMIWQuitGroupConfig config = RCIMIWQuitGroupConfig.create(
  removeFollow: false,  // 关闭移除群组特别关注的用户（默认为 true）
  removeWhiteList: false,  // 关闭移除白名单（默认为 true）
  removeMuteStatus: false,  // 关闭移除群成员禁言状态（默认为 true）
);

// 创建回调（可选）
IRCIMIWTransferGroupOwnerCallback? callback = IRCIMIWTransferGroupOwnerCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("转让成功");
    } else {
      print("转让失败，code: $code");
    }
  },
);

// 调用转让群组方法
int? code = await engine?.transferGroupOwner(
  groupId,
  newOwnerId,
  quitGroup,
  config: config,
  callback: callback,
);

群组备注名

功能介绍

• 群组备注名只对用户本人生效。当群组中有新消息产生且该用户不在线时，推送标题将优先显示设置的群备注名。若用户未对该群设置备注名，则默认显示群名称。
• 设置或移除成功后，其他终端会收到群组备注名变更多端回调 onGroupRemarkChangedSync。

设置群组备注名

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

当需要移除群组备注名时，remark 参数传 null 或空字符串 ""。

代码示例

Dart

// 群Id
String groupId = "groupId";

// 群备注名
String remark = "remark";

// 创建回调（可选）
IRCIMIWSetGroupRemarkCallback? callback = IRCIMIWSetGroupRemarkCallback(
  onCompleted: (RCIMIWCoreErrorCode? code) {
    if (code == RCIMIWCoreErrorCode.success) {
      print("设置成功");
    } else {
      print("设置失败，code: $code");
    }
  },
);

// 调用设置群组备注名方法
int? code = await engine?.setGroupRemark(
  groupId,
  remark,
  callback: callback,
);