创建和管理群组

小于 1 分钟

创建和管理群组及监听群组事件

群组是支持多人沟通的即时通讯系统,本文介绍如何使用环信即时通讯 IM Web SDK 在实时互动 app 中创建和管理群组,并实现群组相关功能。

如需查看消息相关内容,参见 消息管理

技术原理

环信即时通讯 IM Web SDK 支持你通过调用 API 在项目中实现以下群组管理功能:

  • 创建、解散群组
  • 获取群组详情信息
  • 获取群成员列表
  • 获取已加入的群组列表
  • 获取公开群列表
  • 监听群组事件

前提条件

开始前,请确保满足以下条件:

实现方法

创建群组

1、调用 createGroup 方法新建群组,设置群组参数。

群组分为私有群和公开群。私有群无法搜索到,公开群可通过群 ID 搜索到。

创建群组时,需设置以下参数:

参数类型描述
groupnameString群组名称。
descString群组描述。
membersArray群成员的用户 ID 组成的数组。
publicBool是否为公开群:
- true:是;
- false:否。该群组为私有群。
approvalBool入群申请是否需群主或管理员审批:
- true:需要;
- false:不需要。
由于私有群不支持用户申请入群,只能通过邀请方式进群,因此该参数仅对公开群有效,即 public 设置为 true 时,对私有群无效。
allowinvitesBool是否允许普通群成员邀请人入群:
- true:允许;
- false:不允许。只有群主和管理员才可以向群组添加用户。
该参数仅对私有群有效,即 public 设置为 false 时, 因为公开群(public:true) 仅支持群主和群管理员邀请人入群,不支持普通群成员邀请人入群。
inviteNeedConfirmBool邀请加群时是否需要受邀用户确认:
- true:受邀用户需同意才会加入群组;
- false:受邀用户直接加入群组,无需确认。
maxusersInt群组最大成员数。
extString群组详情扩展信息。

创建群组的示例代码如下:

let option = {
  data: {
    groupname: "groupName",
    desc: "A description of a group",
    members: ["user1", "user2"],
    public: true,
    approval: true,
    allowinvites: true,
    inviteNeedConfirm: true,
    maxusers: 500,
    ext: "group detail extensions",
  },
};
conn.createGroup(option).then((res) => console.log(res));

2、邀请用户入群。

公开群只支持群主和管理员邀请用户入群。对于私有群,除了群主和群管理员,群成员是否也能邀请其他用户进群取决于 allowinvites 选项的设置。

邀请用户加群流程如下:

  1. 群成员调用 inviteUsersToGroup 方法邀请用户入群。
conn.inviteUsersToGroup({ groupId: "groupId", users: ["user1", "user2"] });
  1. 受邀用户会收到 inviteToJoin 事件,自动进群或确认是否加入群组。

    入群邀请是否需受邀用户确认取决于群组选项 inviteNeedConfirm 的设置:

    • inviteNeedConfirm 设置为 false 时,受邀用户直接进群,无需确认,群组所有成员会收到 memberPresence 事件。

    • inviteNeedConfirm 设置为 true 时,受邀用户需确认是否加入群组。

      • 受邀用户同意加入群组,需要调用 acceptGroupJoinRequest 方法。用户加入成功后,邀请人会收到 acceptInvite 事件,群组所有成员会收到 memberPresence 事件。
      conn.acceptGroupInvite({ invitee: "myUserId", groupId: "groupId" });
      
      • 受邀用户拒绝入群,需要调用 rejectGroupJoinRequest 方法。邀请人会收到 rejectInvite 事件。
      conn.rejectGroupInvite({ invitee: "myUserId", groupId: "groupId" });
      

3、用户加入群组后,可以收发群消息。

解散群组

仅群主可以调用 destroyGroup 方法解散群组。群组解散时,其他群组成员收到 destroy 事件并被踢出群组。

示例代码如下:

let option = {
  groupId: "groupId",
};
conn.destroyGroup(option).then((res) => console.log(res));

获取群组详情信息

所有群成员均可调用 getGroupInfo 方法根据群组 ID 获取群组详情,包括群组 ID、群组名称、群组描述、群组基本属性、群主、群组管理员列表、、是否已屏蔽群组消息以及群组是否禁用。默认不包含群成员列表。

示例代码如下:

let option = {
  // 群组 ID 或群组 ID 数组。
  groupId: "groupId",
};
conn.getGroupInfo(option).then((res) => {
  console.log(res);
});

获取群成员列表

所有群成员均可调用 listGroupMembers 方法分页获取群成员列表,包括群主、群管理员和普通群成员。

示例代码如下:

let pageNum = 1,
  pageSize = 100;
let option = {
  pageNum: pageNum,
  pageSize: pageSize,
  groupId: "groupId",
};
conn.listGroupMembers(option).then((res) => console.log(res));

获取群组列表

  • 用户可以调用 getJoinedGroups 方法获取当前用户加入和创建的群组列表,代码如下:
conn.getJoinedGroups({
  pageNum: 0,
  pageSize: 20,
  needAffiliations: true,
  needRole: true,
});
  • 用户还可以分页获取公开群列表:
let option = {
  limit: 20,
  cursor: cursor,
};
conn.getPublicGroups(option).then((res) => console.log(res));

监听群组事件

SDK 提供 addEventHandler 方法用于注册监听事件。开发者可以通过设置此监听,获取群组中的事件。

示例代码如下:

// 创建一个群组事件监听器
// 在该方法的举例中,用户 A 表示当前用户。
conn.addEventHandler("eventName", {
  onGroupEvent: function (msg) {
    switch (msg.operation) {
      // 有新群组创建。群主的其他设备会收到该回调。
      case "create":
        break;
      // 关闭群组一键禁言。群组所有成员(除操作者外)会收到该回调。
      case "unmuteAllMembers":
        break;
      // 开启群组一键禁言。群组所有成员(除操作者外)会收到该回调。
      case "muteAllMembers":
        break;
      // 有成员从群白名单中移出。被移出的成员及群主和群管理员(除操作者外)会收到该回调。
      case "removeAllowlistMember":
        break;
      // 有成员添加至群白名单。被添加的成员及群主和群管理员(除操作者外)会收到该回调。
      case "addUserToAllowlist":
        break;
      // 删除群共享文件。群组所有成员会收到该回调。
      case "deleteFile":
        break;
      // 上传群共享文件。群组所有成员会收到该回调。
      case "uploadFile":
        break;
      // 删除群公告。群组所有成员会收到该回调。
      case "deleteAnnouncement":
        break;
      // 更新群公告。群组所有成员会收到该回调。
      case "updateAnnouncement":
        break;
      // 更新群组信息,如群组名称和群组描述。群组所有成员会收到该回调。
      case "updateInfo":
        break;  
      // 有成员被移出禁言列表。被解除禁言的成员及群主和群管理员(除操作者外)会收到该回调。
      case "unmuteMember":
        break;
      // 有群组成员被加入禁言列表。被禁言的成员及群主和群管理员(除操作者外)会收到该回调。
      case "muteMember":
        break;
      // 有管理员被移出管理员列表。群主、被移除的管理员和其他管理员会收到该回调。
      case "removeAdmin":
        break;
      // 设置管理员。群主、新管理员和其他管理员会收到该回调。
      case "setAdmin":
        break;
      // 转让群组。原群主和新群主会收到该回调。
      case "changeOwner":
        break;
      // 群组所有者和管理员拉用户进群时,无需用户确认时会触发该回调。被拉进群的用户会收到该回调。
      case "directJoined":
        break;
      // 群成员主动退出群组。除了退群的成员,其他群成员会收到该回调。
      case "memberAbsence":
        break;
      // 有用户加入群组。除了新成员,其他群成员会收到该回调。
      case "memberPresence":
        break;
      // 用户被移出群组。被踢出群组的成员会收到该回调。
      case "removeMember":
        break;
      // 当前用户的入群邀请被拒绝。邀请人会收到该回调。例如,用户 B 拒绝了用户 A 的入群邀请,用户 A 会收到该回调。
      case "rejectInvite":
        break;
      // 当前用户的入群邀请被接受。邀请人会收到该回调。例如,用户 B 接受了用户 A 的入群邀请,则用户 A 会收到该回调。
      case "acceptInvite":
        break;
      // 当前用户收到了入群邀请。受邀用户会收到该回调。例如,用户 B 邀请用户 A 入群,则用户 A 会收到该回调。
      case "inviteToJoin":
        break;
      // 当前用户的入群申请被拒绝。申请人会收到该回调。例如,用户 B 拒绝用户 A 的入群申请后,用户 A 会收到该回调。
      case "joinPublicGroupDeclined":
        break;
      // 当前用户的入群申请被接受。申请人会收到该回调。例如,用户 B 接受用户 A 的入群申请后,用户 A 会收到该回调。
      case "acceptRequest":
        break;
      // 当前用户发送入群申请。群主和群管理员会收到该回调。
      case "requestToJoin":
        break;
      // 群组被解散。群主解散群组时,所有群成员均会收到该回调。
      case "destroy":
        break;
      // 设置群成员的自定义属性。群组内其他成员均会收到该回调。
      case "memberAttributesUpdate":
        break;  
      default:
        break;
    }
  },
});
上次编辑于: