管理聊天室成员
管理聊天室成员
聊天室是支持多人沟通的即时通讯系统。本文介绍如何使用环信即时通讯 IM Flutter SDK 在实时互动 app 中管理聊天室成员,并实现聊天室的相关功能。
技术原理
环信即时通讯 IM Flutter SDK 提供 EMChatRoom
、EMRoomManager
和 EMChatRoomEventHandler
类,支持对聊天室成员的管理,包括添加和移出聊天室成员等,主要方法如下:
- 获取聊天室成员列表
- 退出聊天室
- 管理聊天室黑名单
- 管理聊天室白名单
- 管理聊天室禁言列表
- 开启和关闭聊天室全员禁言
- 管理聊天室所有者及管理员
前提条件
开始前,请确保满足以下条件:
- 完成 SDK 初始化,详见 快速开始;
- 了解环信即时通讯 IM 的 使用限制。
- 了解环信即时通讯 IM 聊天室相关限制,详见 环信即时通讯 IM 价格。
实现方法
本节介绍如何使用环信即时通讯 IM Flutter SDK 提供的 API 实现上述功能。
获取聊天室成员列表
所有聊天室成员均可调用 EMChatRoomManager#fetchChatRoomMembers
方法获取当前聊天室成员列表。
示例代码如下:
//cursor:从该游标位置开始取数据。首次调用 cursor 传空值,从最新数据开始获取。
//pageSize:每页期望返回的成员数,最大值为 1,000。
try {
await EMClient.getInstance.chatRoomManager.fetchChatRoomMembers(
roomId,
pageSize: pageSize,
cursor: cursor,
);
} on EMError catch (e) {
}
退出聊天室
主动退出
聊天室所有成员均可以调用 EMChatRoomEventHandler#leaveChatRoom
方法退出当前聊天室。成员退出聊天室时,其他成员收到 onMemberExitedFromChatRoom
回调。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.leaveChatRoom(roomId);
} on EMError catch (e) {
}
退出聊天室时,SDK 默认删除该聊天室的所有本地消息,若要保留这些消息,可在 SDK 初始化时将 EMOptions#deleteMessagesAsExitChatRoom
设置为 false
。
示例代码如下:
EMOptions options = EMOptions(
appKey: APPKEY,
deleteMessagesAsExitChatRoom: false,
);
与群主无法退出群组不同,聊天室所有者可以离开聊天室,离开后重新进入仍是该聊天室的所有者。若 ChatOptions#isChatRoomOwnerLeaveAllowed
参数在初始化时设置为 true
时,聊天室所有者可以离开聊天室;若该参数设置为 false
,聊天室所有者调用 leaveChatRoom
方法离开聊天室时会提示错误 706。
被移出
仅聊天室所有者和管理员可调用 EMChatRoomManager#removeChatRoomMembers
方法将单个或多个成员移出聊天室。 被移出后,该成员收到 EMChatRoomEventHandler#onRemovedFromChatRoom
回调,其他成员收到 EMChatRoomEventHandler#onMemberExitedFromChatRoom
回调。
被移出的成员可以重新进入聊天室。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.removeChatRoomMembers(
roomId,
members,
);
} on EMError catch (e) {
}
离线后自动退出
由于网络等原因,聊天室中的成员离线超过 2 分钟会自动退出聊天室。若需调整该时间,需联系环信商务。
以下两类成员即使离线也不会退出聊天室:
- 聊天室白名单中的成员(聊天室所有者和管理员默认加入白名单)。
- 调用 RESTful API 创建聊天室时拉入的用户从未登录过。
管理聊天室黑名单
将成员加入聊天室黑名单
仅聊天室所有者和管理员可调用 EMChatRoomManager#blockChatRoomMembers
方法将指定成员添加至黑名单。
被加入黑名单后,该成员收到 EMChatRoomEventHandler#onRemovedFromChatRoom
事件,其他成员收到 EMChatRoomEventHandler#onMemberExitedFromChatRoom
事件。
被加入黑名单后,该成员无法再收发聊天室消息并被移出聊天室,黑名单中的成员如想再次加入聊天室,聊天室所有者或管理员必须先将其移出黑名单。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.blockChatRoomMembers(
roomId,
members
);
} on EMError catch (e) {
}
将成员移出聊天室黑名单
仅聊天室所有者和管理员可以调用 EMChatRoomManager#unBlockChatRoomMembers
方法将成员移出聊天室黑名单。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.unBlockChatRoomMembers(
roomId,
members
);
} on EMError catch (e) {
}
获取聊天室黑名单列表
仅聊天室所有者和管理员可以调用 EMChatRoomManager#fetchChatRoomBlockList
方法获取当前聊天室黑名单。
示例代码如下:
try {
List<String>? list= await EMClient.getInstance.chatRoomManager.fetchChatRoomBlockList(
roomId,
pageNum: pageNum,
pageSize: pageSize,
);
} on EMError catch (e) {
}
管理聊天室白名单
聊天室所有者和管理员默认会被加入聊天室白名单。
添加成员至聊天室白名单列表
仅聊天室所有者和管理员可以调用 EMChatRoomManager#addMembersToChatRoomAllowList
方法将指定成员添加至聊天室白名单。被添加后,该成员和其他未操作的聊天室管理员或聊天室所有者收到 EMChatRoomEventHandler#onAllowListAddedFromChatRoom
事件。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.addMembersToChatRoomAllowList(
roomId,
members
);
} on EMError catch (e) {
}
将成员移出聊天室白名单列表
仅聊天室所有者和管理员可以调用 EMChatRoomManager#removeMembersFromChatRoomAllowList
方法将成员移出聊天室禁言列表。被解除禁言后,该成员和其他未操作的聊天室管理员或聊天室所有者收到 EMChatRoomEventHandler#onAllowListRemovedFromChatRoom
事件。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.removeMembersFromChatRoomAllowList(
roomId,
members
);
} on EMError catch (e) {
}
检查自己是否在聊天室白名单中
所有聊天室成员可以调用 EMChatRoomManager#isMemberInChatRoomAllowList
方法检查自己是否在白名单中,示例代码如下:
try {
bool isInAllowList = await EMClient.getInstance.chatRoomManager.isMemberInChatRoomAllowList(roomId);
} on EMError catch (e) {
}
管理聊天室禁言列表
添加成员至聊天室禁言列表
仅聊天室所有者和管理员可以调用 EMChatRoomManager#muteChatRoomMembers
方法将指定成员添加至聊天室禁言列表。被禁言后,该成员和其他未操作的聊天室管理员或聊天室所有者收到 EMChatRoomEventHandler#onMuteListAddedFromChatRoom
事件。
提示
聊天室所有者可禁言聊天室所有成员,聊天室管理员可禁言聊天室普通成员。
示例代码如下:
// duration:禁言时间。若传 -1,表示永久禁言。
try {
await EMClient.getInstance.chatRoomManager.muteChatRoomMembers(
roomId,
members
);
} on EMError catch (e) {
}
将成员移出聊天室禁言列表
仅聊天室所有者和管理员可以调用 EMChatRoomManager#unMuteChatRoomMembers
方法将成员移出聊天室禁言列表。被解除禁言后,该成员和其他未操作的聊天室管理员或聊天室所有者收到 EMChatRoomEventHandler#onMuteListRemovedFromChatRoom
事件。
提示
聊天室所有者可对聊天室所有成员解除禁言,聊天室管理员可对聊天室普通成员解除禁言。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.unMuteChatRoomMembers(
roomId,
members
);
} on EMError catch (e) {
}
获取聊天室禁言列表
仅聊天室所有者和管理员可以调用 EMChatRoomManager#fetchChatRoomMuteList
方法获取当前聊天室的禁言列表。
示例代码如下:
try {
List<String>? list =
await EMClient.getInstance.chatRoomManager.fetchChatRoomMuteList(
roomId,
pageNum: pageNum,
pageSize: pageSize,
);
} on EMError catch (e) {
}
开启和关闭聊天室全员禁言
为了快捷管理聊天室发言,聊天室所有者和管理员可以开启和关闭聊天室全员禁言。全员禁言和单独的成员禁言不冲突,设置或者解除全员禁言,原禁言列表并不会变化。
开启聊天室全员禁言
仅聊天室所有者和管理员可以调用 EMChatRoomManager#muteAllChatRoomMembers
方法开启全员禁言。全员禁言开启后不会在一段时间内自动解除禁言,需要调用 EMChatRoomManager#unMuteAllChatRoomMembers
方法解除全员禁言。
全员禁言开启后,除了在白名单中的成员,其他成员不能发言。调用成功后,聊天室成员会收到 EMChatRoomEventHandler#onAllChatRoomMemberMuteStateChanged
事件。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.muteAllChatRoomMembers();
} on EMError catch (e) {
}
关闭聊天室全员禁言
仅聊天室所有者和管理员可以调用 EMChatRoomManager#unMuteAllChatRoomMembers
方法取消全员禁言。调用成功后,聊天室成员会收到 EMChatRoomEventHandler#onAllChatRoomMemberMuteStateChanged
事件。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.unMuteAllChatRoomMembers();
} on EMError catch (e) {
}
管理聊天室所有者和管理员
变更聊天室所有者
仅聊天室所有者可以调用 EMChatRoomManager#changeOwner
方法将权限移交给聊天室中指定成员。成功移交后,原聊天室所有者变为聊天室成员,新的聊天室所有者和聊天室管理员收到 EMChatRoomEventHandler#onOwnerChangedFromChatRoom
事件。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.changeOwner(
roomId,
newOwner,
);
} on EMError catch (e) {
}
添加聊天室管理员
仅聊天室所有者可以调用 EMChatRoomManager#addChatRoomAdmin
方法添加聊天室管理员。成功添加后,新管理员及其他管理员收到 EMChatRoomEventHandler#onAdminAddedFromChatRoom
事件。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.addChatRoomAdmin(
roomId,
memberId,
);
} on EMError catch (e) {
}
移除聊天室管理员
仅聊天室所有者可以调用 EMChatRoomManager#removeChatRoomAdmin
方法移除聊天室管理员。成功移除后,被移除的管理员及其他管理员收到 EMChatRoomEventHandler#onAdminRemovedFromChatRoom
事件。
示例代码如下:
try {
await EMClient.getInstance.chatRoomManager.removeChatRoomAdmin(
roomId,
adminId,
);
} on EMError catch (e) {
}
监听聊天室事件
详见 监听聊天室事件。