Web

群组管理

更新时间: 2024/03/14 19:21:10

网易云信 NIM SDK 提供了高级群形式的群组功能,支持用户创建、加入、退出、转让、更新、查询、解散群组,拥有完善的管理功能。

技术原理

网易云信 NIM SDK 的 TeamServiceInterface 提供管理群组的相关方法,帮助您快速实现和使用群组的管理功能。

群组相关 API 都挂载在 team 模块中,使用 nim.team 进行访问,具体请参见 TeamServiceInterface

群组相关事件监听

在进行群组操作前,您可以提前注册监听群相关事件。监听后,在进行群组管理相关操作时,会收到对应的通知。

群组可能会触发以下事件,具体事件类型请参见IMEventInterface

  • teams:初始化同步群
  • myTeamMembers:初始化同步自己在所有群组中的用户信息;在线或多端登录时修改自己在群组中的用户信息,也会收到该事件通知
  • createTeam 多端同步创建群的情况
  • updateTeamMember 更新群成员的多端同步
  • updateTeam 群更新
  • addTeamMembers 群成员添加
  • updateTeamManagers 群管理员更新
  • transferTeam 转让群
  • removeTeamMembers 移除群成员
  • dismissTeam 解散群
  • updateTeamMembersMute 群成员禁言

示例代码如下:

// 事件声明
  const eventList = [
  'teams',// 初始化同步群
  'myTeamMembers',//初始化同步自己在所有群组中的用户信息
  'createTeam',// 多端同步创建群的情况
  'updateTeamMember',  // 更新群成员的多端同步
  'updateTeam', 'addTeamMembers', 'updateTeamManagers', 'transferTeam', 'removeTeamMembers', 'dismissTeam', 'updateTeamMembersMute',
  ]
// 注册监听
  eventList.forEach((key: any) => {
  nim.on(key, (res) => {
    console.log(`收到 ${key} 事件:`, res ? JSON.parse(JSON.stringify(res)) : res);
  });
})

实现流程

本章节通过群主、管理员、普通成员之间的交互为例,介绍群组管理的实现流程。

uml diagram

创建群组

通过调用 createTeam 方法创建群组,创建者即为该群群主。

接口原型:

jscreateTeam(options: CreateTeamOptions): Promise<Team>

CreateTeamOptions 参数说明

参数 类型 说明
name String 群名称
type TeamType 群组类型请选择 advanced 创建高级群,高级群拥有完善的成员权限体系及管理功能。为避免产生问题,不建议使用其他取值。
accounts Array 群成员
announcement String 群公告
avatar String 群头像
intro String 群简介
level number 群人数上限
joinMode TeamJoinMode 群加入方式
noVerify:不需要验证
needVerify:加此群需要群主或管理员的验证
rejectAll:拒绝其他人加入
默认为needVerify
beInviteMode TeamBeInviteMode 被邀请模式
noVerify:不需要验证
needVerify:此群邀请某人,需要被邀请人验证通过才能加入
默认为needVerify
inviteMode TeamInviteMode 群邀请模式
manager:仅限群主和管理员可以邀请人进群
all:群组内的所有人都可以邀请人进群
默认为manager
updateTeamMode TeamUpdateTeamMode 群信息修改权限
manager:仅限群主和管理员可以修改群信息
all:所有人都可以修改
默认为manager
updateExtMode TeamUpdateExtMode 群信息自定义字段修改权限
manager:仅限群主和管理员可以修改群自定义信息
all:所有人都可以修改
默认为manager
ext String 第三方扩展字段, 开发者可以自行扩展, 建议封装成 JSON 格式字符串
ps String 附言,长度不得大于 5000,开发者可以使用 JSON 格式字符串填充
  • 若被邀请模式(beInviteMode)设为需要验证(needVerify),那么创建群组后,需要用户(accounts)接受邀请,才会成为群成员。
  • 创建时邀请加入的用户数不能超过群人数上限(level)。

示例代码:

jsawait nim.team.createTeam({
  type: 'advanced',
  name: '高级群',
  avatar: 'avatar',
  accounts: ['cs1', 'cs2'],
  intro: '群简介',
  announcement: '群公告',
  // joinMode: 'needVerify',
  // beInviteMode: 'needVerify',
  // inviteMode: 'manager',
  // updateTeamMode: 'manager',
  // updateCustomMode: 'manager',
  level: 50,
  ps: '我建了一个高级群',
  ext: '群扩展字段, 建议封装成JSON格式字符串',
});

加入群组

加入群组可以通过以下两种方式:

  • 用户接受邀请入群。
  • 用户主动申请入群。

邀请入群

邀请入群的权限可以通过 inviteMode 来定义,设为 manager,那么仅限群主和管理员可以邀请人进群;设为 all ,那么群组内的所有人都可以邀请人进群。

通过调用 addTeamMembers 方法邀请其他用户进入群组。

  • 若群组的被邀请模式 beInviteModenoVerify,那么无需验证,其他用户可直接加入群组。
  • 若群组的被邀请模式 beInviteModeneedVerify,那么需要被邀请用户同意才能加入群组。

接口原型

jsaddTeamMembers(options: AddTeamMembersOptions): Promise<void>

AddTeamMembersOptions 参数说明

参数 类型 说明
teamId String 群ID
accounts Array 邀请入群的用户
ext String 第三方扩展字段, 开发者可以自行扩展, 建议封装成 JSON 格式字符串
ps String 附言,长度不得大于 5000,开发者可以使用 JSON 格式字符串填充
  • 发起邀请后,被邀请用户会收到系统通知 SystemMessage,其通知类型为teamInvite
  • 被邀请用户可以调用 acceptTeamInvite 方法接受入群邀请。接受后,该群的所有群成员会收到群通知消息,其类型为addTeamMembers
  • 也可以调用 rejectTeamInvite 方法拒绝入群邀请。拒绝后,邀请者会收到系统通知 SystemMessage,其通知类型为 rejectTeamInvite

示例代码:

jsawait nim.team.addTeamMembers({
  accounts: ['cs1', 'cs2'],
  teamId:  '{{TARGET_TEAM_ID}}',
  ps: '我邀请了xx 加入',
  ext: '附加字段,推荐使用 JSON 格式字符串',
});

//接受邀请
await nim.team.acceptTeamInvite({
  teamId:  '{{TARGET_TEAM_ID}}',
  from: 'cs1',
});
//拒绝邀请
await nim.team.rejectTeamInvite({
  teamId:  '{{TARGET_TEAM_ID}}',
  from: 'cs1',
  ps: '拒绝',
});

申请入群

通过调用 applyTeam 方法申请加入群组。

  • 若群组的加入模式 joinModenoVerify,那么无需验证,其他用户可直接加入群组。
  • 若群组的加入模式 joinModeneedVerify,那么需要群主或者群管理员同意才能加入群组。

接口原型:

jsapplyTeam(options: ApplyTeamOptions): Promise<Team>

ApplyTeamOptions 参数说明

参数 类型 说明
teamId String 群ID
ps String 附言,长度不得大于 5000,开发者可以使用 JSON 格式字符串填充
  • 当用户发起入群申请后,该群群主和管理员会收到系统通知 SystemMessage,其通知类型为applyTeam
  • 群主和群管理员可以调用 passTeamApply 方法接受入群申请。接受后,该群的所有群成员会收到群通知消息,其类型为 addTeamMembers
  • 也可以调用 rejectTeamApply 方法拒绝入群申请。拒绝后,申请者会收到系统通知 SystemMessage,其通知类型为 rejectTeamApply

示例代码:

jsawait nim.team.applyTeam({
  teamId:  '{{TARGET_TEAM_ID}}',
  ps: '我申请加入 xx 群组',
});

//接受申请
await nim.team.passTeamApply({
  teamId:  '{{TARGET_TEAM_ID}}',
  from: 'cs1',
});
//拒绝申请
await nim.team.rejectTeamApply({
  teamId:  '{{TARGET_TEAM_ID}}',
  from: 'cs1',
  ps: '拒绝',
});

转让群组

只有群主才有转让群组的权限。

通过调用 transferTeam 方法将群组转让给其他成员。

  • 转让群后, 所有群成员会收到群通知消息,其类型为 transferTeam
  • 如果转让群的同时离开群, 那么相当于同时调用leaveTeam主动退群,所有群成员会再收到群通知消息,其类型为 removeTeamMembers

接口原型:

jstransferTeam(options: TransferTeamOptions): Promise<void>

TransferTeamOptions 参数说明

参数 类型 说明
teamId String 群ID
account String 转让后的群主账号
leave boolean 转让群的同时是否离开群
true:离开
false:不离开

示例代码:

jsawait nim.team.transferTeam({
  account: 'cs1'
  teamId:  '{{TARGET_TEAM_ID}}',
  leave: 'false',
});

退出群组

退出群组可以通过以下两种方式:

  • 群主或群组管理员将用户踢出群组。
  • 用户主动退群。

踢人出群

  • 只有群主和管理员才能将成员踢出群组。
  • 管理员不能踢群主和其他管理员。

通过调用 removeTeamMembers 方法将某个成员踢出群组。

移除成员后, 所有群成员会收到群通知消息,其类型为 removeTeamMembers

接口原型:

jsremoveTeamMembers(options: RemoveTeamMembersOptions): Promise<void>

RemoveTeamMembersOptions 参数说明

参数 类型 说明
teamId String 群ID
accounts Array 踢除的群成员

示例代码:

jsawait nim.team.removeTeamMembers({
  accounts: ['cs1', 'cs2'],
  teamId:  '{{TARGET_TEAM_ID}}',
});

主动退群

通过调用 leaveTeam 方法主动退出群组。

除群主(需先转让群主)外,其他用户均可以直接主动退群。主动退群后, 所有群成员会收到群通知消息,其类型为 removeTeamMembers

接口原型:

jsleaveTeam(options: { teamId: string }): Promise<void>

示例代码:

jsawait nim.team.leaveTeam({
  teamId:  '{{TARGET_TEAM_ID}}',
});

解散群组

只有群主才能解散群组。

通过调用 dismissTeam 方法解散群组。

解散群后, 所有群成员会收到群通知消息,其类型为 dismissTeam

接口原型:

jsdismissTeam(options: { teamId: string }): Promise<void>

示例代码:

jsawait nim.team.dismissTeam({
  teamId:  '{{TARGET_TEAM_ID}}',
});

修改群组信息

通过调用 updateTeamInfo 方法修改群组信息。

当用户更新群组信息后,所有群成员会收到群通知消息,其类型为 updateTeam

修改群信息需要权限。若该群组的群信息修改权限(TeamUpdateTeamMode)为 manager,那么只有群主和管理员才能修改群组信息;若为 all,则群组内的所有人都可以修改群组信息。

接口原型:

jsupdateTeamInfo(options: UpdateTeamInfoOptions): Promise<Team>

UpdateTeamInfoOptions 参数说明

参数 类型 说明
teamId String 群ID
name String 群名称
announcement String 群公告
avatar String 群头像
intro String 群简介
joinMode TeamJoinMode 群加入方式
noVerify:不需要验证
needVerify:加此群需要群主或管理员的验证
rejectAll:拒绝其他人加入
默认为needVerify
beInviteMode TeamBeInviteMode 被邀请模式
noVerify:不需要验证
needVerify:此群邀请某人,需要被邀请人验证通过才能加入
默认为needVerify
inviteMode TeamInviteMode 群邀请模式
manager:仅限群主和管理员可以邀请人进群
all:群组内的所有人都可以邀请人进群
默认为manager
updateTeamMode TeamUpdateTeamMode 群信息修改权限
manager:仅限群主和管理员可以修改群信息
all:所有人都可以修改
默认为manager
updateExtMode TeamUpdateExtMode 群信息自定义字段修改权限
manager:仅限群主和管理员可以修改群自定义信息
all:所有人都可以修改
默认为manager
ext String 第三方扩展字段, 开发者可以自行扩展, 建议封装成 JSON 格式字符串

示例代码:

jsawait nim.team.updateTeamInfo({
  teamId: '{{TARGET_TEAM_ID}}',
  name: '高级群',
  avatar: 'avatar',
  intro: '群简介',
  announcement: '群公告',
  joinMode: 'needVerify',
  beInviteMode: 'nodVerify',
  inviteMode: 'all',
  updateTeamMode: 'all',
  updateCustomMode: 'all',
  ext: '群扩展字段, 建议封装成 JSON 格式字符串',
});

查询群组信息

  • 通过调用 getTeamInfo 方法查询单个群组的详细信息。

接口原型:

jsgetTeamInfo(options: { teamId: string }): Promise<Team>
  • 通过根据一批群组 ID(teamId) 获取群组列表,请参见 getTeamsById

接口原型:

jsgetTeamsById(options: { teamIds: string[] }): Promise<GetTeamsByIdResult>
  • 通过分页获取群列表,请参见 getTeams

接口原型:

jsgetTeams(): Promise<Team[]>

示例代码:

jsconst team = await nim.team.getTeamInfo({
  teamId: '{{TARGET_TEAM_ID}}'
});

const teamListByIds = await nim.team.getTeamInfo({
  teamIds: ['{{TARGET_TEAM_ID1}}', '{{TARGET_TEAM_ID2}}' ]
});

const teams = await nim.team.getTeams();

API 参考

API
说明
createTeam 创建群组
addTeamMembers 邀请某人入群
acceptTeamInvite 接受入群邀请
rejectTeamInvite 拒绝入群邀请
applyTeam 申请入群
passTeamApply 接受入群申请
rejectTeamApply 拒绝入群申请
removeTeamMembers 踢人出群
leaveTeam 主动退群
transferTeam 转让群组
updateTeamInfo 修改群组信息
getTeamInfo 查询群组信息
getTeams 查询群组列表
getTeamsById 根据群组 ID 查询群组列表
dismissTeam 解散群组
此文档是否对你有帮助?
有帮助
去反馈
  • 技术原理
  • 群组相关事件监听
  • 实现流程
  • 创建群组
  • 加入群组
  • 邀请入群
  • 申请入群
  • 转让群组
  • 退出群组
  • 踢人出群
  • 主动退群
  • 解散群组
  • 修改群组信息
  • 查询群组信息
  • API 参考