聊天室管理
更新时间: 2024/03/07 11:11:47
聊天室
功能概述
云信提供聊天室功能,人数无上限,用户可自由进出聊天室。聊天室的创建与关闭需要通过服务端 API 来完成。
聊天室原型 NIMChatroomInfo
:
类型 | 属性 | 说明 |
---|---|---|
String | roomId | 获取聊天室 id |
String? | announcement | 获取聊天室公告 |
String? | broadcastUrl | 获取聊天室直播地址 |
String? | creator | 获取聊天室创建者帐号 |
Map<String, dynamic>? | extension | 获取聊天室扩展字段 |
String? | name | 获取聊天室名称 |
int | onlineUserCount | 获取当前在线用户数量 |
NIMChatroomQueueModificationLevel | queueModificationLevel | 获取队列权限配置 |
bool | mute | 获取当前聊天室禁言状态 |
bool | validFlag | 获取聊天室有效标记 |
进入聊天室
用户要在聊天室收发消息之前,必须先调用接口进入聊天室。聊天室只允许用户手动进入,无法进行邀请。支持同时进入 10 个聊天室。
- 进入聊天室可以有两种方式:以独立模式进入聊天室和非独立模式进入聊天室。
- 独立模式是指 在 IM 处于未登录的情况下,进入聊天室的方式,针对只需要聊天室功能的业务场景。
- 非独立模式是指 先完成 IM 登录,再进入聊天室的方式,针对需要 IM 和聊天室功能的业务场景。
dartclass ChatroomService {
/// 加入聊天室
Future<NIMResult<NIMChatroomEnterResult>> enterChatroom(
NIMChatRoomEnterRequest request);
}
NIMChatRoomEnterRequest
部分参数说明:
类型 | 属性 | 说明 |
---|---|---|
String | roomId | 聊天室 ID |
String? | avatar | 设置聊天室展示的头像 |
Map<String, dynamic>? | extension | 设置进入聊天室后展示用户信息的扩展字段,长度限制 4k。 设置后在获取聊天室成员信息 NIMChatroomMember 时可以查询到此扩展字段; 此外,在收到聊天室消息时,可以从 NIMChatroomMessage#extension#senderExtension 中获取消息发送者的用户信息扩展字段。 若没有设置,则这个字段为 null。 |
String? | nickname | 设置聊天室展示的昵称(可选字段), 如果不填则直接使用 UserInfo 中的昵称 |
Map<String, dynamic>? | notifyExtension | 设置聊天室通知消息扩展字段,长度限制 2k。 设置后,在收到聊天室通知消息的 NIMChatroomNotificationAttachment#extension 中可以获取到此扩展字段。 |
int | retryCount | 重试加入聊天室的次数(Windows 和 macOS 暂不支持) |
非独立模式
非独立模式较为简单,在 IM 处于登录状态时,直接调用进入聊天室方法即可。
- 示例
dart NimCore.instance.chatroomService.enterChatroom(
NIMChatRoomEnterRequest(
roomId: '123456',
nickname: 'nickname',
retryCount: 3,
),
).then((result) {
if (result.isSuccess) {
/// 加入聊天室成功
} else {
/// 加入聊天室失败
}
});
独立模式
当选择以独立模式进入聊天室时,必须设置NIMChatRoomEnterRequest.independentModeConfig
字段的各项属性,它的类型为 NIMChatRoomIndependentModeConfig
。
NIMChatRoomIndependentModeConfig 参数列表:
参数 | 类型 | 说明 |
---|---|---|
appKey | String | 独立模式的 AppKey |
linkAddresses | List<String> | 聊天室服务器的地址 |
account | String? | 独立模式下的用户名,若设置为 null ,SDK 将使用自动生成的匿名账号进行登录。在匿名模式下,NIMChatRoomEnterRequest 必须设置昵称和头像信息 |
token | String? | 独立模式下的 Token。 当用户名为空时,token 无效。 |
- 匿名模式与非匿名模式
独立模式下又可分为匿名模式与非匿名模式。匿名模式只能收消息,不能发消息。
当NIMChatRoomIndependentModeConfig.account
设置为 null 时,则为匿名模式。SDK 将使用自动生成的匿名账号进行登录。在匿名模式下,NIMChatRoomEnterRequest
中必须设置昵称和头像信息。
- 获取聊天室地址
独立模式由于不依赖 IM 连接,SDK 无法自动获取聊天室服务器的地址,需要客户端向开发者应用服务器请求该地址,而应用服务器需要向网易云信服务器请求,然后将请求结果原路返回给客户端,即请求路径为:客户端 <-> 开发者应用服务器 <-> 网易云信服务器(API:请求聊天室地址)。
即针对独立模式进入聊天室,需要进行以下步骤:
-
获取聊天室地址
-
设置
NIMChatRoomIndependentModeConfig
-
初始化
NIMChatRoomEnterRequest
,并赋值independentModeConfig
字段。 -
调用进入聊天室的方法。
-
示例(以匿名模式加入独立聊天室)
dart NimCore.instance.chatroomService.enterChatroom(
NIMChatRoomEnterRequest(
roomId: '123456',
nickname: 'nickname',
avatar: 'http://avatar_url.png'
retryCount: 3,
independentModeConfig: NIMChatRoomIndependentModeConfig(
appKey: 'independent_mode_appkey',
linkAddresses: ['chatroom_link_address'],
),
),
).then((result) {
if (result.isSuccess) {
/// 加入独立聊天室成功
} else {
/// 加入独立聊天室失败
}
});
聊天室多端登录
支持设置聊天室多端登录策略,即当同账号在不同客户端登录时,是否可以同时进入同一个聊天室。可以进入云信控制台进行设置:
- 只允许一端登录
- 各端均可以同时登录在线
监听聊天室连接变化
进入聊天室成功后,SDK 会负责维护与服务器的长连接以及断线重连等工作。当用户在线状态发生改变时,会发出通知。登录过程也有状态回调。此外,网络连接上之后,SDK 会负责聊天室的自动登录。
- API 原型
dartclass ChatroomService {
/// 聊天室事件流
///
/// [NIMChatroomStatusEvent] 聊天室状态事件
///
/// [NIMChatroomKickOutEvent] 聊天室离开事件
Stream<NIMChatroomEvent> get onEventNotified;
}
onEventNotified
会通知两类事件,包括连接状态事件 NIMChatroomStatusEvent
和离开事件 NIMChatroomKickOutEvent
- NIMChatroomStatusEvent 类型说明
属性 | 说明 |
---|---|
roomId | 聊天室 ID |
status | 状态码,参考 NIMChatroomStatus |
code | 错误码,参考 NIMChatroomErrors |
错误码 | 说明 |
:----- | :----------------------- |
414 | 参数错误 |
404 | 聊天室不存在 |
403 | 无权限 |
500 | 服务器内部错误 |
13001 | IM 主连接状态异常 |
13002 | 聊天室状态异常 |
13003 | 黑名单用户禁止进入聊天室 |
- 示例
dart
final subscription = NimCore.instance.chatroomService
.onEventNotified.listen((event) {
if (event is NIMChatroomStatusEvent) {
/// 连接状态事件通知
}
});
/// 不再使用时,需要取消监听
/// subscription.cancel();
监听被踢出
当用户被踢出聊天室或者聊天室关闭时,会触发被踢回调。
注意:收到被踢出通知后,不需要再调用退出聊天室接口,SDK 会负责聊天室的退出工作。可以在踢出通知中做相关缓存的清理工作和界面操作。
- API 原型
dartclass ChatroomService {
/// 聊天室事件流
///
/// [NIMChatroomStatusEvent] 聊天室状态事件
///
/// [NIMChatroomKickOutEvent] 聊天室离开事件
Stream<NIMChatroomEvent> get onEventNotified;
}
- NIMChatroomKickOutEvent 类型说明
属性 | 说明 |
---|---|
roomId | 聊天室 ID |
reason | 原因,参考 NIMChatroomKickOutReason |
extension | 扩展字段 |
NIMChatroomKickOutReason 枚举 | 说明 |
:---------------------------- | :--------------- |
blacklisted | 被拉黑了 |
dismissed | 聊天室已经被关闭 |
byConflictLogin | 被其他端踢出 |
byManager | 被管理员踢出 |
unknown | 未知(出错情况) |
- 示例
dart
final subscription = NimCore.instance.chatroomService
.onEventNotified.listen((event) {
if (event is NIMChatroomKickOutEvent) {
/// 离开事件通知
}
});
/// 不再使用时,需要取消监听
/// subscription.cancel();
离开聊天室
离开聊天室,会断开聊天室对应的链接,并不再收到该聊天室的任何消息。如果用户要离开聊天室,可以手动调用离开聊天室接口,该接口没有回调。
###离开单个聊天室
- API 原型
dartclass ChatroomService {
/// 退出聊天室
Future<NIMResult<void>> exitChatroom(String roomId);
}
- 示例
dartNimCore.instance.chatroomService.exitChatroom(roomId);
聊天室消息收发
聊天室消息 NIMChatroomMessage 继承自 NIMMessage。新增了以下方法:
类型 | 属性 | 说明 |
---|---|---|
NIMChatroomMessageExtension | extension | 获取聊天室消息扩展属性 |
bool | isHighPriorityMessage | 是否是高优先级消息 |
bool | enableHistory | 该消息是否要保存到服务器 |
- 为保证用户体验(如避免服务器过载),目前针对消息接收,有两套流控机制。第一套针对普通消息,聊天室用户每秒至多可接收20条,超过部分会因为流控随机丢弃。第二套针对高优先级消息,每秒至多接收10条,超过部分无法保证不丢失。
- 为避免丢失重要消息(通常为服务端消息),可将发送聊天室消息的 HighPriority 参数设置为 true 实现高优先级接收服务端消息,进而保证高优先级消息流控上限内(每秒10条)的重要消息不丢失。详情请参见发送聊天室消息中的 HighPriority 参数说明。
发送聊天室消息
先通过 ChatroomMessageBuilder 提供的接口创建消息对象 NIMChatroomMessage,然后调用 ChatroomService 的 sendMessage 接口发送出去即可。注意,创建消息对象的接口也为异步。
1秒内默认最多可调用该接口100次。如需上调上限,请在官网首页通过微信、在线消息或电话等方式咨询商务人员。
- ChatRoomMessageBuilder 接口说明
返回值 | ChatRoomMessageBuilder 接口 | 说明 |
---|---|---|
Future<NIMResult<NIMChatroomMessage>> | createChatroomAudioMessage({required String roomId,required String filePath,required int duration,NIMNosScene nosScene = NIMNosScenes.defaultIm,}) | 创建一条音频消息(Windows 和 macOS 暂不支持) |
Future<NIMResult<NIMChatroomMessage>> | createChatroomCustomMessage({required String roomId,NIMMessageAttachment? attachment,}) | 创建自定义消息 |
Future<NIMResult<NIMChatroomMessage>> | createChatroomFileMessage({required String roomId,required String filePath,required String displayName,NIMNosScene nosScene = NIMNosScenes.defaultIm,}) | 创建一条文件消息(Windows 和 macOS 暂不支持) |
Future<NIMResult<NIMChatroomMessage>> | createChatroomImageMessage({required String roomId,required String filePath,String? displayName,NIMNosScene nosScene = NIMNosScenes.defaultIm,}) | 创建一条图片消息(Windows 和 macOS 暂不支持) |
Future<NIMResult<NIMChatroomMessage>> | createChatroomLocationMessage({required String roomId,required double latitude,required double longitude,required String address,}) | 创建一条地理位置信息(Windows 和 macOS 暂不支持) |
Future<NIMResult<NIMChatroomMessage>> | createChatroomTextMessage({required String roomId,required String text,}) | 创建普通文本消息 |
Future<NIMResult<NIMChatroomMessage>> | createChatroomVideoMessage({required String roomId,required String filePath,required int duration,required int width,required int height,String? displayName,NIMNosScene nosScene = NIMNosScenes.defaultIm,}) | 创建一条视频消息(Windows 和 macOS 暂不支持) |
Future<NIMResult<NIMChatroomMessage>> | createChatRoomVideoMessage(String roomId, File file, long duration, int width, int height, String displayName, String nosTokenSceneKey) | 创建一条视频消息并指定文件资源场景(Windows 和 macOS 暂不支持) |
Future<NIMResult<NIMChatroomMessage>> | createChatroomTipMessage({required String roomId,}) | 创建一条提醒消息(Windows 和 macOS 暂不支持) |
nosTokenSceneKey 详见文件资源场景。
下面以文本消息发送为例,其它类型的消息发送方式与 IM 单聊群聊类似。
- API 原型
dartclass ChatroomMessageBuilder {
/// 创建文本消息
static Future<NIMResult<NIMChatroomMessage>> createChatroomTextMessage({
required String roomId,
required String text,
}) async { ... }
}
class ChatroomService {
/// 发送聊天室消息
///
/// 聊天室消息通过 [ChatroomMessageBuilder] 进行创建
///
/// [resend] 如果是发送失败后重发,标记为true,否则填false,默认为
Future<NIMResult<NIMChatroomMessage>> sendChatroomMessage(
NIMChatroomMessage message,
[bool resend = false]) async {
...
}
}
- 示例
dart ChatroomMessageBuilder.createChatroomTextMessage(
roomId: '123456',
text: 'Hello World!',
).then<NIMResult>((result) {
if (result.isSuccess) {
return chatroomService.sendChatroomMessage(result.data!);
} else {
return result;
}
}).then((value) {
print('ChatroomService##send message: ${value.code} ${value.errorDetails}');
});
- 特殊错误码
错误码 | 说明 |
---|---|
13004 | 在禁言列表中,不允许发言 |
13006 | 聊天室处于整体禁言状态,只有管理员能发言 |
发送消息配置选项
发送聊天室消息时,可以设置配置选项 enableHistory
,主要用于设置是否存入云端历史记录。
NIMChatroomMessage 属性 | 说明 |
---|---|
enableHistory | 该消息是否要保存到服务器, 如果为 true,通过 ChatroomService#pullMessageHistory 拉取的结果将包含该条消息。 默认为 true。 |
- 示例
dartChatroomMessageBuilder.createChatroomTextMessage(
roomId: '123456',
text: 'Hello World!',
).then<NIMResult>((result) {
if (result.isSuccess) {
result.data!.enableHistory = false;
return chatroomService.sendChatroomMessage(result.data!);
} else {
return result;
}
}).then((value) {
print('ChatroomService##send message: ${value.code} ${value.errorDetails}');
});
接收聊天室消息
通过监听消息事件,在有新消息到达时,就可以接收到通知。
- API 原型
dartclass ChatroomService {
/// 聊天室消息
///
Stream<List<NIMChatroomMessage>> get onMessageReceived;
}
- 示例
dartfinal subsription = NimCore.instance.chatroomService.onMessageReceived.listen((messages) {
messages.forEach((message) {
print(
'ChatroomService##on message received: ${message.fromAccount} ${message.fromNickname} '
'\'${message.content}\'');
}
});
/// 不再监听时需要移除监听器
/// subscription.cancel();
- 附件的下载,请使用
ChatroomService
的downloadAttachment
方法进行下载。 - 监听消息状态变化,请使用
ChatroomService
的onMessageStatusChanged
事件流。 - 监听消息附件上传/下载进度事件,请使用
ChatroomService
的onMessageAttachmentProgressUpdate
。
聊天室通知消息
在聊天室中进行部分操作会产生聊天室通知消息。目前当出现以下事件,会产生通知消息:
NIMChatroomNotificationTypes | 说明 |
---|---|
chatRoomClose | 聊天室被关闭了 |
chatRoomCommonAdd | 成员设定为固定成员 |
chatRoomCommonRemove | 成员取消固定成员 |
chatRoomInfoUpdated | 聊天室信息被更新了 |
chatRoomManagerAdd | 设置为管理员 |
chatRoomManagerRemove | 取消管理员 |
chatRoomMemberBlackAdd | 成员被加黑 |
chatRoomMemberBlackRemove | 成员被取消黑名单 |
chatRoomMemberExit | 成员离开聊天室 |
chatRoomMemberIn | 成员进入聊天室 |
chatRoomMemberKicked | 成员被踢了 |
chatRoomMemberMuteAdd | 成员被设置禁言 |
chatRoomMemberTempMuteAdd | 新增临时禁言 |
chatRoomMemberTempMuteRemove | 主动解除临时禁言 |
chatRoomMyRoomRoleUpdated | 成员主动更新了聊天室内的角色信息(仅指 nick/avator/ext) |
chatRoomQueueBatchChange | 队列批量变更 |
chatRoomQueueChange | 队列中有变更 |
chatRoomRoomDeMuted | 聊天室解除全体禁言状态 |
chatRoomRoomMuted | 聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态 |
特别地,支持设置成员进出聊天室通知是否下发:
- 应用级别:网易云信控制台 > 选择应用 > 聊天室用户进出消息系统下发 > 开启/关闭。
- 单个聊天室:调用服务端 API「关闭指定聊天室进出通知」。
- 如果希望查询聊天室消息历史时,也不要包含聊天室用户进出消息,请联系商务顾问申请关闭「聊天室用户进出消息历史存储」。
所有的聊天室通知都以消息 NIMChatRoomMessage 的形式封装。聊天室通知的解析如下:
聊天室通知解析步骤:
- 通过 NIMChatRoomMessage.messageType 获取 消息类型,若为 NIMMessageType.notification ,则为聊天室通知消息。
- 将 NIMChatRoomMessage.messageAttachment 获取的附件对象强类型转换为 NIMChatroomNotificationAttachment。
- 通过 NIMChatroomNotificationAttachment.type 获取具体的 NotificationType 。
- 根据对应的 NotificationType 将 NIMChatRoomMessage.messageAttachment 得到的附件对象强转为对应的 NIMChatroomNotificationAttachment 或其子类)。
NIMChatroomNotificationAttachment 参数说明:
方法 | 说明 |
---|---|
type | 通知类型,参考 NIMChatroomNotificationTypes |
extension | 获取聊天室通知扩展字段 |
operator | 获取该操作的发起者的账号 |
operatorNick | 获取该操作的发起者的昵称 |
targets | 获取该操作的承受者的账号列表 |
targetNicks | 获取该操作的承受者的昵称列表 |
示例:
dart/// 聊天室通知类型
class NIMChatroomNotificationTypes {
static String typeToString(int type) {
switch (type) {
case chatRoomMemberIn:
return 'chatRoomMemberIn';
case chatRoomMemberExit:
return 'chatRoomMemberExit';
case chatRoomMemberBlackAdd:
return 'chatRoomMemberBlackAdd';
case chatRoomMemberBlackRemove:
return 'chatRoomMemberBlackRemove';
case chatRoomMemberMuteAdd:
return 'chatRoomMemberMuteAdd';
case chatRoomMemberMuteRemove:
return 'chatRoomMemberMuteRemove';
case chatRoomManagerAdd:
return 'chatRoomManagerAdd';
case chatRoomManagerRemove:
return 'chatRoomManagerRemove';
case chatRoomCommonAdd:
return 'chatRoomCommonAdd';
case chatRoomCommonRemove:
return 'chatRoomCommonRemove';
case chatRoomClose:
return 'chatRoomClose';
case chatRoomInfoUpdated:
return 'chatRoomInfoUpdated';
case chatRoomMemberKicked:
return 'chatRoomMemberKicked';
case chatRoomMemberTempMuteAdd:
return 'chatRoomMemberTempMuteAdd';
case chatRoomMemberTempMuteRemove:
return 'chatRoomMemberTempMuteRemove';
case chatRoomMyRoomRoleUpdated:
return 'chatRoomMyRoomRoleUpdated';
case chatRoomQueueChange:
return 'chatRoomQueueChange';
case chatRoomRoomMuted:
return 'chatRoomRoomMuted';
case chatRoomRoomDeMuted:
return 'chatRoomRoomDeMuted';
case chatRoomQueueBatchChange:
return 'chatRoomQueueBatchChange';
default:
return 'unknown';
}
}
}
查询云端历史消息
聊天室没有离线消息和漫游消息。可以通过下面的接口查询聊天室消息历史。服务器只保存最近 10 天的聊天室消息记录。但是 10 天之前发送的文件(例如:图片、音频、视频等),其 url 链接地址仍然是有效的(不过开发者需要自行保存这些 url,因为无法通过已过期的消息来查询这些文件 url)。如需延长「聊天室历史消息天数」,请联系商务顾问。
查询云端历史消息
以 startTime(单位毫秒)为查询起点,选择查询方向往前或者往后拉取 limit 条消息。拉取到的消息中也包含聊天室通知消息。 同时,可以指定要拉取的消息类型,如果不指定,会包含所有消息类型;
查询结果排序与查询方向有关,若方向往前,则结果排序按时间逆序,反之则结果排序按时间顺序。
dartclass ChatroomService {
/// 获取历史消息,可选择给定时间往前或者往后查询,若方向往前,则结果排序按时间逆序,反之则结果排序按时间顺序。
///
/// [roomId] 聊天室id <p>
/// [startTime] 时间戳,单位毫秒 <p>
/// [limit] 可拉取的消息数量 <p>
/// [direction] 查询方向 <p>
/// [messageTypeList] 查询的消息类型
Future<NIMResult<List<NIMChatroomMessage>>> fetchMessageHistory({
required String roomId,
required int startTime,
required int limit,
required QueryDirection direction,
List<NIMMessageType>? messageTypeList,
});
}
- 参数说明
参数 | 说明 |
---|---|
roomId | 聊天室 id |
startTime | 时间戳,单位毫秒 |
limit | 可拉取的消息数量,最多 100 条 |
direction | 查询方向 |
messageTypeList | 查询消息类型 |
QueryDirection 属性说明
QueryDirection 属性 | 说明 |
---|---|
QUERY_OLD | 查询比锚点时间更早的消息 |
QUERY_NEW | 查询比锚点时间更晚的消息 |
- 示例
dart NimCore.instance.chatroomService.fetchMessageHistory(
roomId: '123456',
startTime: DateTime.now().millisecondsSinceEpoch,
limit: 10,
direction: QueryDirection.QUERY_OLD,
messageTypeList: [NIMMessageType.text],
).then((messages) {
var index = 0;
messages.data?.forEach((message) {
print(
'ChatroomService##message history: ${index++} ${message.fromAccount} ${message.fromNickname} '
'\'${message.content}\'');
});
});
聊天室信息管理
获取聊天室信息
此接口可以向服务器获取聊天室信息。SDK 不提供聊天室信息的缓存,开发者可根据需要自己做缓存。聊天室基本信息的扩展字段需要在服务器端设置,客户端 SDK 只提供查询。
- API 原型
dartclass ChatroomService {
/// 获取当前聊天室信息
Future<NIMResult<NIMChatroomInfo>> fetchChatroomInfo(String roomId);
}
- 示例
dartNimCore.instance.chatroomService.fetchChatroomInfo('123456')
.then(
(value) {
print(
'ChatroomService##fetch updated chatroom info: ${value.data?.name} '
'${value.data?.announcement}');
}
);
修改聊天室信息
支持修改聊天室信息,只有创建者和管理员拥有权限修改聊天室信息。可以设置修改是否通知,若设置通知,聊天室内会收到类型为NIMChatroomNotificationTypes#chatRoomInfoUpdated
的消息。
- API 原型
dartclass ChatroomService {
/// 更新聊天室信息
Future<NIMResult<void>> updateChatroomInfo({
required String roomId,
required NIMChatroomUpdateRequest request,
bool needNotify = true,
Map<String, dynamic>? notifyExtension,
});
}
- 参数说明
参数 | 说明 |
---|---|
roomId | 聊天室 id |
request | 可更新的聊天室信息 |
needNotify | 是否通知 |
notifyExtension | 更新聊天室信息扩展字段,这个字段会放到更新聊天室信息通知的扩展字段中 |
NIMChatroomUpdateRequest | 说明 |
:----------------------- | :-------------------------------------------------------------------------------------------------- |
name | 聊天室名称 |
announcement | 聊天室公告 |
broadcastUrl | 视频直播拉流地址 |
extension | 第三方扩展字段 |
queueLevel | 队列管理权限,如是否有权限提交他人 key 和信息到队列; 0 表示所有人有权限,1 表示只有主播管理员有权限 |
- 示例
dart NimCore.instance.chatroomService
.updateChatroomInfo(
roomId: '123456',
request: NIMChatroomUpdateRequest(
announcement: '修改群公告',
),
needNotify: true,
).then((value) {
print(
'ChatroomService##set chatroom announcement: ${value.code} ${value.errorDetails}');
});
聊天室成员管理
聊天室成员概述
关于聊天室成员:
- 聊天室成员包括固定成员和非固定成员(临时成员/游客)。固定成员上限是 1000 个。
- 固定成员包括四种类型:创建者、管理员、普通用户、受限用户。受限用户又包括:黑名单用户和永久禁言用户。
- 除了创建者,其他成员刚加入时,默认都是游客。
- 如果游客被设置为管理员,再被取消管理员,则变为普通用户(而不是游客)。
- 要将管理员变成普通用户,直接取消其管理员权限即可。不能直接将管理员设置为普通成员。
- 只有创建者可以对管理员进行操作,管理员不能对创建者和其他管理员进行操作。
- 普通用户被取消身份后变为游客。
- 游客被设置为黑名单用户后变为固定成员(同时会被服务器断开连接并且无法进入聊天室,除非被解除黑名单)。解除黑名单后变为游客。
- 永久禁言后,身份变为固定成员。解除永久禁言后,身份变为游客。解除永久禁言后,不影响临时禁言的到期时间。
- 临时禁言的设置和解除不会改变成员的身份。如果重复设置临时禁言,则后一次设置会覆盖前一次设置的到期时间(不会累积)。
- 游客只有在线时才属于聊天室的非固定成员;游客进入聊天室又退出后,不属于聊天室的任何成员(和聊天室没有任何关系)。
聊天室成员原型:
类型 | NIMChatroomMember 属性 | 说明 |
---|---|---|
String | roomId | 获取聊天室 id |
String | account | 获取成员帐号 |
String? | avatar | 获取头像。可从 NimUserInfo 中取 avatar,可以由用户进聊天室时提交 |
int? | enterTime | 获取进入聊天室时间。对于离线成员该字段为空 |
Map<String, dynamic>? | extension | 获取扩展字段。长度限制 4k,可以由用户进聊天室时提交 |
NIMChatroomMemberType | memberType | 获取成员类型。成员类型:主要分为游客和非游客 |
String? | nickname | 获取昵称。可从 NimUserInfo 中取,也可以由用户进聊天室时提交 |
int? | tempMuteDuration | 获取临时禁言解除时长,单位秒 |
bool | isInBlackList | 判断用户是否在黑名单中 |
bool | isMuted | 判断用户是否被禁言 |
bool | isOnline | 判断用户是否处于在线状态 仅特殊成员才可能离线,对游客/匿名用户而言只能是在线 |
bool | isTempMuted | 判断用户是否被临时禁言 |
bool | isValid | 判断是否有效 |
关于 NIMChatroomMemberType 成员类型说明:
NIMChatroomMemberType 属性 | 说明 |
---|---|
unknown | 未知 |
guest | 游客 |
restricted | 受限用户(非游客)= 被禁言 + 被拉黑的用户 |
normal | 普通成员(非游客) |
creator | 创建者(非游客) |
manager | 管理员(非游客) |
anonymous | 匿名游客 |
获取聊天室成员
分页获取聊天室成员
此接口可以远程获取聊天室成员列表,SDK 不会缓存聊天室成员列表,开发者需要根据业务自己做好缓存。
- API 原型
dartclass ChatroomService {
/// 获取当前聊天室成员
///
/// [roomId] 聊天室id <p>
/// [queryType] 查询的类型, [NIMChatroomMemberQueryType]
/// [limit] 可拉取的消息数量 <p>
/// [lastMemberAccount] 最后一位锚点的成员账号,不包括此成员。如果为空会使用当前服务器最新时间开始查询,即第一页。 <p>
Future<NIMResult<List<NIMChatroomMember>>> fetchChatroomMembers({
required String roomId,
required NIMChatroomMemberQueryType queryType,
required int limit,
String? lastMemberAccount,
});
}
- 参数说明
参数 | 说明 |
---|---|
roomId | 聊天室 id |
queryType | 成员查询类型。见 NIMChatroomMemberQueryType |
lastMemberAccount | 最后一位锚点的成员账号,不包括此成员。如果为空会使用当前服务器最新时间开始查询,即第一页。 |
limit | 人数限制 |
NIMChatroomMemberQueryType | 说明 |
:------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
allNormalMember | 固定成员 (包括创建者,管理员,普通等级用户,受限用户(禁言+黑名单), 即使非在线也可以在列表中看到,有数量限制 ) |
onlineNormalMember | 仅在线的固定成员 |
onlineGuestMemberByEnterTimeDesc | 非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间倒序排序,进入时间越晚的越靠前 |
onlineGuestMemberByEnterTimeAsc | 非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间顺序排序,进入时间越早的越靠前 |
- 示例
dart
NimCore.instance.chatroomService.fetchChatroomMembers(
roomId: chatroomId,
queryType: NIMChatroomMemberQueryType.allNormalMember,
limit: 10,
).then((result) {
var index = 0;
result.data?.forEach((member) {
print(
'ChatroomService fetchChatroomMembers ##member_${index++}: ${member.account} ${member.nickname} ${member.memberType}');
});
});
获取指定聊天室成员
dartclass ChatroomService {
/// 获取当前聊天室成员
///
/// [roomId] 聊天室id <p>
/// [accountList] 成员账号列表 <p>
Future<NIMResult<List<NIMChatroomMember>>> fetchChatroomMembersByAccount({
required String roomId,
required List<String> accountList,
});
}
- 示例
dart NimCore.instance.chatroomService.fetchChatroomMembersByAccount(
roomId: chatroomId,
accountList: ['account1', 'account2'],
).then((result) {
var index = 0;
result.data?.forEach((member) {
print(
'ChatroomService fetchChatroomMembers ##member_${index++}: ${member.account} ${member.nickname} ${member.memberType}');
});
});
修改自身信息
支持更新本人聊天室成员信息。目前只支持昵称,头像和扩展字段的更新。可以设置更新是否通知,若设置通知,聊天室内会收到类型为NIMChatroomNotificationTypes#chatroomMyRoomRoleUpdated
的消息。
dartclass ChatroomService {
/// 更新聊天室内的自身信息
/// [roomId] 聊天室id
/// [request] 可更新的本人角色信息
/// [needNotify] 是否通知
/// [notifyExtension] 更新聊天室信息扩展字段,这个字段会放到更新聊天室信息通知的扩展字段中
Future<NIMResult<void>> updateChatroomMyMemberInfo({
required String roomId,
required NIMChatroomUpdateMyMemberInfoRequest request,
bool needNotify = true,
Map<String, dynamic>? notifyExtension,
});
}
- 参数说明
参数 | 说明 |
---|---|
roomId | 聊天室 id |
request | 可更新的本人角色信息 |
needNotify | 是否通知 |
notifyExtension | 更新操作扩展字段,这个字段会放到更新聊天室信息通知的扩展字段中 |
NIMChatroomUpdateMyMemberInfoRequest 接口说明
类型 | NIMChatroomUpdateMyMemberInfoRequest 接口 | 说明 |
---|---|---|
String? | avatar | 获取聊天室内的头像 |
Map<String, dynamic>? | extension | 获取扩展字段 |
String? | nickname | 获取聊天室内的昵称 |
bool | needSave | 更新的信息是否需要做持久化,只对固定成员生效,默认 false |
- 示例
dart /// 以更新自己的昵称为例
NimCore.instance.chatroomService
.updateChatroomMyMemberInfo(
roomId: chatroomId,
request: NIMChatroomUpdateMyMemberInfoRequest(
nickname: '新昵称',
needSave: true,
),
).then((value) {
print(
'ChatroomService##update chatroom my info: ${value.code} ${value.errorDetails}');
});
添加/移除管理员
dartclass ChatroomService {
///
/// 设置/取消设置聊天室管理员
///
/// [isAdd] true:设置, false:取消设置
/// [memberOption] 请求参数,包含聊天室id,帐号id以及可选的扩展字段
Future<NIMResult<NIMChatroomMember>> markChatroomMemberBeManager({
required bool isAdd,
required NIMChatroomMemberOptions options,
});
}
- 参数说明
返回值 | NIMChatroomMemberOptions 接口 | 说明 |
---|---|---|
String | roomId | 获取聊天室 id |
String | account | 获取成员帐号 |
Map<String, dynamic>? | getNotifyExtension() | 获取通知事件中开发者定义的扩展字段 |
- 示例
dart /// 以设置为管理员为例
NimCore.instance.chatroomService
.markChatroomMemberBeManager(
isAdd: true,
options: NIMChatroomMemberOptions(
roomId: '123456',
account: 'account',
),
).then((value) {
print(
'ChatroomService##markChatroomMemberBeManager: ${value.code} ${value.errorDetails}');
});
添加/移除普通成员
dartclass ChatroomService {
///
/// 设置/取消设置聊天室普通成员
///
/// [isAdd] true:设置, false:取消设置
/// [memberOption] 请求参数,包含聊天室id,帐号id以及可选的扩展字段
Future<NIMResult<NIMChatroomMember>> markChatroomMemberBeNormal({
required bool isAdd,
required NIMChatroomMemberOptions options,
});
}
- 示例
java/// 以设为普通成员为例
NimCore.instance.chatroomService
.markChatroomMemberBeNormal(
isAdd: true,
options: NIMChatroomMemberOptions(
roomId: '123456',
account: 'account',
),
).then((value) {
print(
'ChatroomService##markChatroomMemberBeNormal: ${value.code} ${value.errorDetails}');
});
添加/移除黑名单用户
dartclass ChatroomService {
///
/// 添加/移出聊天室黑名单
///
/// [isAdd] true:设置, false:取消设置
/// [memberOption] 请求参数,包含聊天室id,帐号id以及可选的扩展字段
Future<NIMResult<NIMChatroomMember>> markChatroomMemberInBlackList({
required bool isAdd,
required NIMChatroomMemberOptions options,
});
}
- 示例
dart /// 以添加到黑名单为例
NimCore.instance.chatroomService
.markChatroomMemberInBlackList(
isAdd: true,
options: NIMChatroomMemberOptions(
roomId: '123456',
account: 'account',
),
).then((value) {
print(
'ChatroomService##markChatroomMemberInBlackList: ${value.code} ${value.errorDetails}');
});
添加/移除禁言用户
添加到禁言名单时, 会收到类型为 chatRoomMemberMuteAdd
的聊天室通知消息。
取消禁言时, 会收到类型为 chatRoomMemberMuteRemove
的聊天室通知消息。
dartclass ChatroomService {
///
/// 添加/解除禁言聊天室成员
///
/// [isAdd] true:设置, false:取消设置
/// [memberOption] 请求参数,包含聊天室id,帐号id以及可选的扩展字段
Future<NIMResult<NIMChatroomMember>> markChatroomMemberMuted({
required bool isAdd,
required NIMChatroomMemberOptions options,
});
}
- 示例
dart/// 以添加到禁言名单为例
NimCore.instance.chatroomService
.markChatroomMemberMuted(
isAdd: true,
options: NIMChatroomMemberOptions(
roomId: '123456',
account: 'account',
),
).then((value) {
print(
'ChatroomService##markChatroomMemberMuted: ${value.code} ${value.errorDetails}');
});
踢出成员
踢出成员。仅管理员可以踢;如目标是管理员,仅创建者可以踢。
当有人被踢出聊天室时,会收到类型为 chatRoomMemberKicked
的聊天室通知消息。
可以添加被踢通知扩展字段,这个字段会放到被踢通知的扩展字段中。通知扩展字段最长 1K;扩展字段类型为 Map<String, dynamic>。
dartclass ChatroomService {
///
/// 踢掉聊天室特定成员
///
/// [memberOption] 请求参数,包含聊天室id,帐号id以及可选的扩展字段
Future<NIMResult<void>> kickChatroomMember(NIMChatroomMemberOptions options);
}
- 示例
dart NimCore.instance.chatroomService
.kickChatroomMember(
NIMChatroomMemberOptions(
roomId: '123456',
account: 'account',
),
).then((value) {
print(
'ChatroomService##kickChatroomMember: ${value.code} ${value.errorDetails}');
});
临时禁言成员
设置临时禁言时, 会收到类型为 chatRoomMemberTempMuteAdd
的聊天室通知消息。
取消临时禁言时, 会收到类型为 chatRoomMemberTempMuteRemove
的聊天室通知消息。
聊天室支持设置临时禁言,禁言时长时间到了,自动取消禁言。设置临时禁言成功后的通知消息中,包含的时长是禁言剩余时长。若设置禁言时长为 0,表示取消临时禁言。若第一次设置的禁言时长还没结束,又设置第二次临时禁言,以第二次设置的时间开始计时。
dartclass ChatroomService {
///
/// 添加/解除临时禁言聊天室成员
///
/// [duration] 禁言时长,单位ms。设置为 0 会取消禁言
/// [memberOption] 请求参数,包含聊天室id,帐号id以及可选的扩展字段
/// [needNotify] 是否需要发送广播通知,true:通知,false:不通知
Future<NIMResult<void>> markChatroomMemberTempMuted({
required int duration,
required NIMChatroomMemberOptions options,
bool needNotify = false,
});
}
- 参数说明
参数 | 说明 |
---|---|
duration | 禁言时长,单位秒 |
memberOption | 请求参数,包含聊天室 id,帐号 id 以及可选的扩展字段 |
needNotify | 是否需要发送广播通知,true:通知,false:不通知 |
- 示例
dart/// 以发送广播通知,并且临时禁言10秒为例
NimCore.instance.chatroomService
.markChatroomMemberTempMuted(
duration: 10 * 1000,
options: NIMChatroomMemberOptions(
roomId: '123456',
account: 'account',
),
needNotify: true,
).then((value) {
print(
'ChatroomService##markChatroomMemberTempMuted: ${value.code} ${value.errorDetails}');
});
聊天室队列
聊天室提供队列服务,可结合互动直播连麦场景中的麦位管理使用。权限由 NIMChatroomInfo.queueModificationLevel
决定,可以通过 updateChatroomInfo 进行修改。默认情况下,所有用户都可以调用接口修改队列内容。
获取聊天室队列
dartclass ChatroomService {
/// 获取聊天室队列
///
/// [roomId] 聊天室ID <p>
Future<NIMResult<List<NIMChatroomQueueEntry>>> fetchChatroomQueue(
String roomId);
}
- 示例
dart NimCore.instance.chatroomService
.fetchChatroomQueue('123456')
.then((value) {
print('ChatroomService##poll queue: ${value.code} ${value.errorDetails} '
'${value.data?.map((e) => '${e.key}:${e.value}').toList()}');
});
加入或者更新队列元素
用户使用该接口加入或更新的元素,当 isTransient 参数为 true 时,表示当该用户掉线或退出聊天室时,服务器会自动删除该用户加入或更新的元素。
同时,服务器将发出聊天室通知消息,通知消息的类型为 NIMChatroomNotificationTypes#chatRoomQueueBatchChange
,通知消息的附件类型为 NIMChatroomQueueChangeAttachment
,该通知消息属于队列变更通知,所以附件类型中包含了队列变更类型 NIMChatroomQueueChangeType#partialClear
。
dartclass ChatroomService {
/// 更新聊天室队列
///
/// [roomId] 聊天室ID <p>
/// [entry] 要更新的队列项 <p>
/// [isTransient] (可选参数,不传默认false)。true表示当提交这个新元素的用户从聊天室掉线或退出的时候,需要删除这个元素;默认false表示不删除
Future<NIMResult<void>> updateChatroomQueueEntry({
required String roomId,
required NIMChatroomQueueEntry entry,
bool isTransient = false,
});
}
- 参数说明
参数 | 说明 |
---|---|
roomId | 聊天室 id |
entry | 新元素 |
isTransient | (可选参数) true 表示当提交这个新元素的用户从聊天室掉线或退出的时候,需要删除这个元素;默认 false 表示不删除 |
NIMChatroomQueueEntry 说明:
参数 | 说明 |
---|---|
key | 新元素(或待更新元素)的唯一键 |
value | 新元素(待待更新元素)的内容 |
NIMChatroomQueueChangeAttachment 说明
类型 | NIMChatroomQueueChangeAttachment 接口 | 说明 |
---|---|---|
NIMChatroomQueueChangeType | queueChangeType | 返回队列变更类型,值为 NIMChatroomQueueChangeType |
Map<String, String>? | contentMap | 当用户掉线或退出聊天室时,返回用户使用 updateQueueEx 接口,并设置 isTransient 参数为 true 时,加入或更新的元素 |
- 示例
dartNimCore.instance.chatroomService
.updateChatroomQueueEntry(
roomId: chatroomId,
entry: NIMChatroomQueueEntry(
key: 'key',
value: 'value',
),
).then((value) {
print(
'ChatroomService##updateChatroomQueueEntry: ${value.code} ${value.errorDetails}');
});
批量更新队列元素
只会更新已经存在的 key,不会加入新元素。
dartclass ChatroomService {
/// 批量更新聊天室队列
///
/// [roomId] 聊天室ID <p>
/// [entry] 要更新的队列项列表 <p>
/// [needNotify] 是否需要发送广播通知 <p>
/// [notifyExtension] 通知中的自定义字段 <p>
/// 返回不在队列中的元素列表
Future<NIMResult<List<String>>> batchUpdateChatroomQueue({
required String roomId,
required List<NIMChatroomQueueEntry> entryList,
bool needNotify = true,
Map<String, Object>? notifyExtension,
});
}
- 示例
dartNimCore.instance.chatroomService
.batchUpdateChatroomQueue(
roomId: chatroomId,
entryList: [
NIMChatroomQueueEntry(
key: 'key',
value: 'value',
)],
).then((value) {
print(
'ChatroomService##batchUpdateChatroomQueue: ${value.code} ${value.errorDetails}');
});
移除指定队列元素
key 是唯一键。key 若为 null, 则表示取出头元素。若不为 null, 则表示取出指定元素。
dartclass ChatroomService {
/// 从列表中删除某个元素
///
/// [roomId] 聊天室ID <p>
/// [key] 要删除的key,null表示移除队头元素 <p>
Future<NIMResult<NIMChatroomQueueEntry>> pollChatroomQueueEntry(
String roomId, String? key);
}
- 参数说明
参数 | 说明 |
---|---|
roomId | 聊天室 id |
key | 需要取出的元素的唯一键。若为 null,则表示取出队头元素 |
- 示例
dart NimCore.instance.chatroomService
.pollChatroomQueueEntry(
chatroomId,
'key',
).then((value) {
print(
'ChatroomService##batchUpdateChatroomQueue: ${value.code} ${value.errorDetails}');
});
清空队列
dartclass ChatroomService {
/// 清空聊天室队列
Future<NIMResult<void>> clearChatroomQueue(String roomId);
}
- 示例
java NimCore.instance.chatroomService
.clearChatroomQueue(
'123456',
).then((value) {
print(
'ChatroomService##clearChatroomQueue: ${value.code} ${value.errorDetails}');
});