群组管理
更新时间: 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);
});
})
实现流程
本章节通过群主、管理员、普通成员之间的交互为例,介绍群组管理的实现流程。
创建群组
通过调用 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
方法邀请其他用户进入群组。
- 若群组的被邀请模式
beInviteMode
为noVerify
,那么无需验证,其他用户可直接加入群组。 - 若群组的被邀请模式
beInviteMode
为needVerify
,那么需要被邀请用户同意才能加入群组。
接口原型
jsaddTeamMembers(options: AddTeamMembersOptions): Promise<void>
参数 | 类型 | 说明 |
---|---|---|
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
方法申请加入群组。
- 若群组的加入模式
joinMode
为noVerify
,那么无需验证,其他用户可直接加入群组。 - 若群组的加入模式
joinMode
为needVerify
,那么需要群主或者群管理员同意才能加入群组。
接口原型:
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>
参数 | 类型 | 说明 |
---|---|---|
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>
参数 | 类型 | 说明 |
---|---|---|
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 |
解散群组 |