群组管理

本文档指导您如何使用融云即时通讯（IM）Harmony IMLib SDK 实现创建群组、群组资料设置、踢出群组、退出群组、解散群组、转让群组等功能。

提示

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

开通服务

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

群事件监听

群事件定义在 GroupEventListener 中，包含群操作、群信息群成员信息变更、加群申请相关通知、群备注名多端同步、群特别关注多端同步等。

您可以调用 addGroupEventListener 添加群事件监听器，如果不想再接收群事件，调用 removeGroupEventListener 即可，需要配对使用，避免资源泄露。

提示

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

代码示例

TypeScript

let listener: GroupEventListener = {
  // 执行群操作后的回调：包括创建群、加入群、踢出、退出、解散、添加管理员、移除管理员、转让群主，具体参照 [GroupOperation] 
  onGroupOperation : (
    groupId: string,
    operatorInfo: GroupMemberInfo,
    groupInfo: GroupInfo,
    operation: GroupOperation,
    memberInfos: Array<GroupMemberInfo>,
    operationTime: number
  ): void => {

  },
  // 群组资料变更回调。注意：只有包含在 updateKeys 中的属性值有效
  onGroupInfoChanged : (
    operatorInfo: GroupMemberInfo,
    fullGroupInfo: GroupInfo,
    properties: Array<string>,
    operationTime: number
  ): void => {

  },
  // 群成员资料变更回调
  onGroupMemberInfoChanged : (
    groupId: string,
    operatorInfo: GroupMemberInfo,
    memberInfo: GroupMemberInfo,
    operationTime: number
  ): void => {

  },
  // 群请求事件回调。包含以下事件：
  // 1，用户申请加入群组的 "申请" 或 "结果"
  // 2，邀请加入群组的 "申请" 或 "结果"
  onGroupApplicationEvent : (
    info: GroupApplicationInfo
  ): void => {

  },
  // 群名称备注名更新多端同步回调事件
  onGroupRemarkChangedSync : (
    groupId: string,
    operationType: GroupOperationType,
    groupRemark: string,
    operationTime: number
  ): void => {

  },
  // 群成员特别关注变更多端回调事件
  onGroupFollowsChangedSync : (
    groupId: string,
    operationType: GroupOperationType,
    userIds: Array<string>,
    operationTime: number
  ): void => {

  }
}
// 添加监听
IMEngine.getInstance().addGroupEventListener(listener);

// 移除监听
IMEngine.getInstance().removeGroupEventListener(listener);

群组管理

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

创建群组

调用 createGroup 方法创建群组。

群资料 GroupInfo 参数介绍

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

inviteeUserIds 参数介绍

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

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

• 需要被邀请人验证（InviteeVerify）时，创建群组成功后，成功回调的 EngineError 会返回 GroupNeedInviteeAccept(25427)，被邀请人会收到 [onGroupApplicationEvent] 事件，需要调用 acceptGroupInvite 接口同意后才能加入群组。
• 无需被邀请人验证（Free）时，创建群组成功后，成功回调的 EngineError 会返回 Success(0)，表示被邀请人已加入群组。

提示

创建群组成功，群主会收到 [onGroupOperation] 回调，GroupOperation 类型 Create。

示例代码

TypeScript

// 群组 ID。必填，不能为空，长度不超过 64 个字符，大小写英文字母与数字的组合，不能包含空格
let groupId = "testGroupId";
// 群名称。必填，不能为空，长度不超过 64 个字符
let groupName = "testGroupName";
let portraitUri = "";
let introduction = ""; // 群组简介
let notice = ""; // 群组公告信息
let joinPermission = 0; // 需要群主验证，按需传入枚举值
let removeMemberPermission = 0; // 群主，按需传入枚举值
let invitePermission = 0; // 群主，按需传入枚举值
let inviteHandlePermission = 0; // 不需要被邀请人同意，按需传入枚举值
let groupInfoEditPermission = 0; // 群主，按需传入枚举值
let memberInfoEditPermission = 0; // 群主+管理员+自己，按需传入枚举值
let hashMap = new HashMap<string, string>();
hashMap.set("key1", "value1"); // key 需要预先在开发者后台配置
hashMap.set("key2", "value2");

let groupInfo = new GroupInfo();
groupInfo.setGroupId(groupId);
groupInfo.setGroupName(groupName);
groupInfo.setPortraitUri(portraitUri);
groupInfo.setIntroduction(introduction);
groupInfo.setNotice(notice);
groupInfo.setJoinPermission(joinPermission);
groupInfo.setRemoveMemberPermission(removeMemberPermission);
groupInfo.setInvitePermission(invitePermission);
groupInfo.setInviteHandlePermission(inviteHandlePermission);
groupInfo.setGroupInfoEditPermission(groupInfoEditPermission);
groupInfo.setMemberInfoEditPermission(memberInfoEditPermission);
groupInfo.setExtProfile(hashMap);

// 设置加入群组的用户 ID，非必填，一次最多允许 30 个用户加入
let userIds = ["user1Id", "user2Id"];

IMEngine.getInstance().createGroup(groupInfo, userIds).then(result => {
  if (EngineError.Success !== result.code) {
    // 创建群组失败
    if (result.data) {
      let ret: GroupResultWithProcessCode<string> = result.data;
      if (ret.dataArray) {
        let array: Array<string> = ret?.dataArray; // 失败的 key 数组
      }
    }
  } else {
    // 创建群组成功
    if (result.data) {
      let ret: GroupResultWithProcessCode<string> = result.data;
      let processCode = ret.processCode; // 业务错误码
    }
  }
});

修改群组资料

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

提示

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

代码示例

TypeScript

// 群组 ID
let groupId = "groupId";
let groupName = "groupName";
let portraitUri = "";
let introduction = "这是一个测试群";
let notice = "";
let joinPermission = 0; // 需要群主验证，按需传入枚举值
let removeMemberPermission = 0; // 群主，按需传入枚举值
let invitePermission = 0; // 群主，按需传入枚举值
let inviteHandlePermission = 0; // 不需要被邀请人同意，按需传入枚举值
let groupInfoEditPermission = 0; // 群主，按需传入枚举值
let memberInfoEditPermission = 0; // 群主+管理员+自己，按需传入枚举值
let hashMap = new HashMap<string, string>();
hashMap.set("key1", "value1");
hashMap.set("key2", "value2");

let groupInfo = new GroupInfo();
groupInfo.setGroupId(groupId);
groupInfo.setGroupName(groupName);
groupInfo.setPortraitUri(portraitUri);
groupInfo.setIntroduction(introduction);
groupInfo.setNotice(notice);
groupInfo.setJoinPermission(joinPermission);
groupInfo.setRemoveMemberPermission(removeMemberPermission);
groupInfo.setInvitePermission(invitePermission);
groupInfo.setInviteHandlePermission(inviteHandlePermission);
groupInfo.setGroupInfoEditPermission(groupInfoEditPermission);
groupInfo.setMemberInfoEditPermission(memberInfoEditPermission);
groupInfo.setExtProfile(hashMap);

IMEngine.getInstance().updateGroupInfo(groupInfo).then(result => {
  if (EngineError.Success !== result.code) {
    // 更新群组信息失败
    if (result.data) {
      let array: Array<string> = result.data; // 具体失败的 key 数组
    }
  }
  // 更新群组信息成功
});

踢出群组

调用 kickGroupMembers 方法将用户从群组中移除。

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

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

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

提示

踢出成功后，群组内所有成员会收到 [onGroupOperation] 回调，GroupOperation 类型是 Kick。

代码示例

TypeScript

// 群组 ID
let groupId = "groupId";
// 用户 ID 列表
let userIds = ["user1Id", "user2Id"];
// 是否关闭移除群成员禁言状态（默认为 true）
let removeMute = true;
// 是否关闭移除白名单（默认为 true）
let removeWhiteList = true; 
// 是否关闭移除群组特别关注的用户（默认为 true）
let removeFavoriteMembers = true;
let config = new QuitGroupConfig(removeMute, removeWhiteList, removeFavoriteMembers);

IMEngine.getInstance().kickGroupMembers(groupId, userIds, config).then(result => {
  if (EngineError.Success !== result.code) {
    // 操作失败
  }
  // 操作成功
});

退出群组

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

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

提示

退出成功后，群组内的所有成员会收到 [onGroupOperation] 事件，GroupOperation 类型是 Quit。

代码示例

TypeScript

// 群组 ID
let groupId = "groupId";
// 是否关闭移除群成员禁言状态（默认为 true）
let removeMute = true;
// 是否关闭移除白名单（默认为 true）
let removeWhiteList = true; 
// 是否关闭移除群组特别关注的用户（默认为 true）
let removeFavoriteMembers = true;
let config = new QuitGroupConfig(removeMute, removeWhiteList, removeFavoriteMembers);

IMEngine.getInstance().quitGroup(groupId, config).then(result => {
  if (EngineError.Success !== result.code) {
    // 退出失败
  }
  // 退出成功
});

解散群组

调用 dismissGroup 方法解散群组。

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

提示

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

代码示例

TypeScript

// 群组 ID
let groupId = "groupId";

IMEngine.getInstance().dismissGroup(groupId).then(result => {
  if (EngineError.Success !== result.code) {
    // 解散失败
  }
  // 解散成功
});

转让群组

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

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

退出成功后，群组内的所有成员会收到 [onGroupOperation] 事件，GroupOperation 类型是 TransferGroupOwner。

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

提示

只有群主有权转让群组。

代码示例

TypeScript

// 群组 ID
let groupId = "groupId";
// 转让后的群主用户 ID
let newOwnerId = "userId";
// 转让后退出群组
let autoQuit = true;
// 是否关闭移除群成员禁言状态（默认为 true）
let removeMute = true;
// 是否关闭移除白名单（默认为 true）
let removeWhiteList = true; 
// 是否关闭移除群组特别关注的用户（默认为 true）
let removeFavoriteMembers = true;
let config = new QuitGroupConfig(removeMute, removeWhiteList, removeFavoriteMembers);

IMEngine.getInstance().transferGroupOwner(groupId, newOwnerId, autoQuit, config).then(result => {
  if (EngineError.Success !== result.code) {
    // 转让失败
  }
  // 转让成功
});

群组备注名

功能介绍

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

设置群组备注名

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

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

代码示例

TypeScript

// 群组 ID
let groupId = "groupId";
// 群备注名
let remark = "group remark";

IMEngine.getInstance().setGroupRemark(groupId, remark).then(result => {
  if (EngineError.Success !== result.code) {
    // 设置失败
    return;
  }
  // 设置成功
});

查询群组备注名

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

代码示例

TypeScript

// 群组 ID 列表
let groupIds = ["group1Id", "group2Id"];

IMEngine.getInstance().getGroupsInfo(groupIds).then(result => {
  if (EngineError.Success !== result.code) {
    // 获取失败
    return;
  }
  // 获取群组信息成功
  let ret : Object = result;
  if (result.data) {
    ret = Array.from(result.data as Array<GroupInfo>);
  }
});