iOS
圈组临时禁言
更新时间： 2024/07/08 15:01:28
云信圈组支持通过身份组实现成员全局禁言的能力，但部分场景下，需要临时禁言某些用户。为了满足用户管理成员更加灵活和精准，自 V9.17.0 起，云信圈组支持临时禁言功能。
功能介绍
云信圈组可以通过不同维度对指定用户进行临时禁言或解除临时禁言。
- 圈组服务器维度：对指定 服务器 中的单个用户或多个用户进行临时禁言或解除临时禁言。
- 圈组频道维度：在指定服务器中指定 频道 中，对单个用户或多个用户进行临时禁言或解除临时禁言。
对于同一用户而言，在不同维度下的禁言操作，互不覆盖，整体的禁言状态取 并集。在用户发送消息时，会检验该用户的整体禁言状态。但是对于同一用户、同一维度下的同一禁言操作（重复禁言），后续的操作都将覆盖前一次的操作，即禁言时间将会延长、缩短或者取消禁言。
如果成员退出服务器/频道后重新进入，则该成员的禁言状态将会重置。
当前支持的临时禁言时间范围为：60s ～ 30天（30* 24* 60* 60=2592000s），单位为秒，时间范围不支持扩展。
若需要实现整体成员的临时禁言，您可以通过身份组统一设置禁言和解除禁言。具体请参考 身份组应用场景。
前提限制
-
使用圈组临时禁言功能需要相关权限，请提前开启身份组权限项中的 禁言/临时禁言管理（
NIMQChatPermissionType.NIMQChatPermissionTypeMute）。只有开启该权限项的用户才能在具体维度中对其他用户进行禁言/解除禁言，以及查询禁言列表操作。
-
已注册
observeReceiveSystemNotification监听圈组的系统通知。与圈组临时禁言相关的系统通知类型，请参见本文末尾的 相关系统通知。
实现方法
服务器维度临时禁言
调用 NIMQChatServerManager.mute 方法在指定圈组服务器中对指定成员进行临时禁言或解除临时禁言。
设置临时禁言时可预先设置禁言时间，到期后将自动解除禁言。若需要提前解除禁言，可重新调用该接口实现。
临时禁言/解除禁言成功后，会触发成员的禁言状态变更通知。
- 在指定的圈组服务器下，对同一用户重复进行禁言操作，新操作将覆盖前一次的操作，即禁言时间将会延长、缩短或者取消禁言。
- 单次最多对 50 个成员进行临时禁言或解除临时禁言操作，超出将会报错。
- 进行批量禁言操作时，如果部分成功，则返回部分成功和操作失败的成员列表，并返回操作失败的原因。
示例代码如下：
objcid<NIMQChatServerManager> qchatServerManager = [[NIMSDK sharedSDK] qchatServerManager];
NIMQChatServerMuteParam * param = [[NIMQChatServerMuteParam alloc] init];
param.serverId = 12346;
// 禁言操作使用NIMQChatMuteOperateTypeMute
// 解除禁言操作使用NIMQChatMuteOperateTypeUnMute
param.operateType = NIMQChatMuteOperateTypeMute;
// 被禁言用户的账号列表
param.muteAccountIds = @[@"yunxin0",@"yunxin1",@"yunxin2"];
// 临时禁言时长（秒）
param.duration = 60 * 60 * 24;
// 附言
param.postscript = @"禁言";
// 仅通知被操作人：NIMQChatMuteNotifyScopeServerTargetOnly
// 通知所有人：NIMQChatMuteNotifyScopeChannelAll
param.notifyType = NIMQChatMuteNotifyScopeServerTargetOnly;
[qchatServerManager mute:param
completion:^(NSError *__nullable error, NIMQChatMuteResult *__nullable result) {
// your code
}];
查询服务器维度的临时禁言列表
调用 NIMQChatServerManager.getMuteMemberByPage 方法在指定圈组服务器中分页查询被临时禁言的成员列表。
查询结果按照临时禁言的结束时间升序排序。
QChatGetServerMuteMemberByPageParam 参数说明：
| 参数名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
serverId |
Int64 | 是 | 服务器 ID。 |
cursor |
String | 否 | 分页标记。首次查询不填，翻页时传入上次查询返回的 cursor。 |
limit |
Integer | 否 | 单次查询的数量限制。默认和最大值都为 100。 |
示例代码如下：
objcid<NIMQChatServerManager> qchatServerManager = [[NIMSDK sharedSDK] qchatServerManager];
NIMQChatGetServerMuteMemberByPageParam * param = [[NIMQChatGetServerMuteMemberByPageParam alloc] init];
param.serverId = 123456;
// 第一页不填cursor
// param.cursor = @"1234567890.123";
param.limit = 20;
[qchatServerManager getMuteMemberByPage:param
completion:^(NSError *__nullable error, NIMQChatGetServerMuteMemberByPageResult *__nullable result) {
// your code
}];
频道维度临时禁言
调用 NIMQChatChannelManager.mute 方法在指定频道中对指定成员进行临时禁言或解除临时禁言。
设置临时禁言时可预先设置禁言时间，到期后将自动解除禁言。若需要提前解除禁言，可重新调用该接口实现。
临时禁言/解除禁言成功后，会触发成员的禁言状态变更通知。
- 在指定的频道中，对同一用户重复进行禁言操作，新操作将覆盖前一次的操作，即禁言时间将会延长、缩短或者取消禁言。
- 单次最多对 50 个成员进行临时禁言或解除临时禁言操作，超出将会报错。
- 进行批量禁言操作时，如果部分成功，则返回部分成功和操作失败的成员列表，并返回操作失败的原因。
示例代码如下：
objcid<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatChannelMuteParam * param = [[NIMQChatChannelMuteParam alloc] init];
param.serverId = 12346;
param.channelId = 56780;
// 禁言操作使用NIMQChatMuteOperateTypeMute
// 解除禁言操作使用NIMQChatMuteOperateTypeUnMute
param.operateType = NIMQChatMuteOperateTypeMute;
// 被禁言用户的账号列表
param.muteAccountIds = @[@"yunxin0",@"yunxin1",@"yunxin2"];
// 临时禁言时长（秒）
param.duration = 60 * 60 * 24;
// 附言
param.postscript = @"禁言";
// 仅通知被操作人：NIMQChatMuteNotifyScopeServerTargetOnly
// 通知所有人：NIMQChatMuteNotifyScopeChannelAll
param.notifyType = NIMQChatMuteNotifyScopeServerTargetOnly;
[qchatChannelManager mute:param
completion:^(NSError *__nullable error, NIMQChatMuteResult *__nullable result) {
// your code
}];
查询频道维度的临时禁言列表
调用 NIMQChatChannelManager.getMuteMemberByPage 方法在指定频道中分页查询被临时禁言的成员列表。
查询结果按照临时禁言的结束时间升序排序。
QChatGetChannelMuteMemberByPageParam 参数说明：
| 参数名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
serverId |
Int64 | 是 | 服务器 ID。 |
channelId |
Int64 | 是 | 频道 ID。 |
cursor |
String | 否 | 分页标记。首次查询不填，翻页时传入上次查询返回的 cursor。 |
limit |
Integer | 否 | 单次查询的数量限制。默认和最大值都为 100。 |
示例代码如下：
objcid<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
NIMQChatGetChannelMuteMemberByPageParam * param = [[NIMQChatGetChannelMuteMemberByPageParam alloc] init];
param.serverId = 123456;
param.channelId = 56780;
// 第一页不填cursor
// param.cursor = @"1234567890.123";
param.limit = 20;
[qchatChannelManager getMuteMemberByPage:param
completion:^(NSError *__nullable error, NIMQChatGetChannelMuteMemberByPageResult *__nullable result) {
// your code
}];
参考信息
相关系统通知
圈组临时禁言相关事件的系统通知为 SDK 内置系统通知，在 NIMQChatSystemNotificationType 枚举内定义。具体类型及相关的触发和接收条件见下表。
系统通知类型 |
触发条件 |
接收条件 |
|---|---|---|
MUTE_OR_RELEASE |
成员的禁言状态更新时 |
|
临时禁言/解除禁言 的通知类型中根据 operateType（操作类型）分为以下三种：
operateType=1：手动设置临时禁言导致成员的禁言状态变更operateType=2：手动解除临时禁言导致成员的禁言状态变更operateType=3：临时禁言时间到期后自动解除禁言导致成员的禁言状态变更
