群聊 QGGroup
QGGroup 是 QQ 群聊对象,实现 simbot 标准库中的 ChatGroup。 它通常来自 QQ 群聊消息事件,例如:
- QGGroupAtMessageCreateEvent
群聊中用户
@机器人时触发的群消息事件,对应 API 模块事件GroupAtMessageCreate。- QGGroupMessageCreateEvent
群聊全量消息事件,对应 API 模块事件
GroupMessageCreate。 自4.3.0开始支持。
这两个事件都实现了标准库的 ChatGroupMessageEvent。 如果只关心“QQ群聊消息”这一抽象,可以监听 ChatGroupMessageEvent; 如果需要区分是否为全量消息,可以监听组件专属类型 QGGroupAtMessageCreateEvent 或 QGGroupMessageCreateEvent。
事件订阅
群聊 @ 机器人消息与群聊全量消息同属 EventIntents.GroupAndC2CEvent。 配置 intents 时需要包含:
或在 bot 配置文件中使用 GROUP_AND_C2C_EVENT。
基本信息
群消息事件只提供有限的群资料,普通 QGGroup 的基础属性如下:
属性或方法 | 结果 |
|---|---|
| 群聊的 |
| 空字符串; |
| 按平台游标分页查询群成员 |
| 查询指定成员,返回 |
|
|
|
|
群成员由 QGGroupMember 表示, id 为成员的 member_openid。 自 5.0 起还提供所属群的 groupId。 群成员不能用于主动发送私聊消息,调用 send(...) 会抛出 UnsupportedOperationException。
自 4.4.0 起,群消息事件的 author() 返回 QGGroupAuthor。 它在 QGGroupMember 的基础上额外提供 memberRole 与 isBot ,可用于判断消息发送者的群内身份和是否为机器人。
查询群资料与机器人状态
方法 | 结果 |
|---|---|
| 查询群基本信息,返回 |
| 查询资料并返回 |
| 已有 |
| 已有 |
| 查询机器人在当前群内的 |
| 查询机器人状态,返回 |
QGGroupWithInfo 提供 groupInfo、 name、 groupFingerMemo、 groupClassText、 groupTags 和 groupMemberNum。 快照保留本次查询的结果,需要刷新时再次调用查询方法。 includeInfo() 会检查响应中的群 OpenID;与当前群 ID 不一致时抛出 IllegalStateException。
QGGroupBotMember 还提供 botState、 joinTime、 allowProactiveMsg 和 recvMsgSetting。 自 5.0 起, botAsMember() 也会请求平台,并返回群成员 OpenID; 需要机器人的 AppID 时使用 bot.id 。这些查询可能因网络或平台权限问题失败。
通过 bot.groupRelation 也可以使用 groupInfo(groupId) 和 groupBotState(groupId)。 groupRelation.group(id) 仍只包装群 ID,不校验群是否存在; groups 仍为空, groupCount() 仍返回 -1。
群成员管理
group.members 获取群成员列表,收集时请求平台 API 并按游标自动翻页,每页最多返回 30 条。
列表中的元素为 QGGroupMemberWithInfo ,包含本次查询得到的成员资料。 已知成员 ID 时,可以通过 member(id) 或 memberWithInfo(id) 查询成员,需要直接获取 API 模型时使用 memberInfo(id)。
QGGroupMemberWithInfo 的 id 为成员 OpenID, groupId 为所属群的 OpenID。 它还提供 isBot 、可空的 unionOpenid 及原始 GroupMemberInfo ,并支持已有的成员禁言操作。 每次调用都会查询最新的信息。
bot.groupRelation 提供 members(groupId)、 memberInfo(groupId, memberId) 和 memberWithInfo(groupId, memberId) ,可用于已知群和成员 ID 的场景。
移除成员与黑名单
removeMembers(memberIds, addToBlacklist) 批量移除群成员,可选择同时加入黑名单。 平台单次最多处理 20 个,数量上限由服务端校验。 返回的 GroupMembersRemoveResult 包含移除状态和同时加入黑名单失败的成员 OpenID。
group.blacklist 查询群黑名单,收集时按游标翻页,元素为 GroupBlacklistUser。 通过 addToBlacklist(memberIds) 和 removeFromBlacklist(memberIds) 添加或移出黑名单, 返回结果中的 failOpenids 为本次操作失败的成员 OpenID。 加入黑名单要求目标用户已不在群内。需要同时移除并拉黑时,可以使用 removeMembers 的 addToBlacklist 参数。
bot.groupRelation 提供带 groupId 的同名方法。 批量请求保留输入顺序及重复项,空列表或空白 ID 在请求前抛出 IllegalArgumentException。
入群申请
group.joinRequests 和 bot.groupRelation.joinRequests(groupId) 返回 Collectable<QGGroupJoinRequest>。 开始收集时才发起请求,并按平台游标自动翻页。
申请提供 joinRequestId、 memberOpenid、 username、 applyAt、 applySource、 bot、 riskTips、 unionOpenid、 invitedBy 和 verifyInfo ,以及底层的 source 快照。 通过 accept() 接受申请,通过 reject(...) 拒绝:
拒绝选项包括 QGGroupJoinRequestRejectOption.reason("理由") 和 QGGroupJoinRequestRejectOption.AddToBlacklist。 多个理由按传入顺序直接拼接,不额外插入分隔符。 已知群、成员和申请 ID 时,也可以调用 groupRelation.approveJoinRequest(...) 或 rejectJoinRequest(...)。 群和管理员权限由平台校验,请求失败时抛出相应异常。
成员禁言
group.muteSetting() 查询完整的 GroupMuteSetting ,包含全员禁言规则和成员的单独禁言记录。 member.muteState() 查询该成员的记录;返回 null 仅表示没有单独记录,仍可能受全员禁言影响。 两者使用相同的群禁言查询 API,可能共享服务端速率限制。
操作 |
|
|
|---|---|---|
增加禁言 |
|
|
更新禁言到期时间 |
|
|
解除单独禁言 |
|
|
expireAt 使用 kotlin.time.Instant 表示绝对到期时间。 也可以使用 addMemberMuteAtMilliseconds(...)、 updateMemberMuteAtMilliseconds(...), 或成员的 addMuteAtMilliseconds(...)、 updateMuteAtMilliseconds(...) ,传入自 Unix epoch 起的毫秒数。 扩展函数 addMuteFor(duration)、 updateMuteFor(duration) 及群和关系对象上的 addMemberMuteFor(...)、 updateMemberMuteFor(...) 支持 kotlin.time.Duration ,可选提供作为起点的 now: Instant ,时长必须为有限的正值。
批量操作使用 group.setMemberMutes(changes) ,每次提交 1~20 项。 变更项通过 QGGroupMemberMuteChange.add(...)、 update(...) 和 remove(...) 创建。 bot.groupRelation 也提供带 groupId 的对应方法。 机器人需要群管理员身份,平台只允许操作普通成员,最长禁言 30 天。 解除成员单独禁言不会修改全员禁言规则;操作失败时抛出平台或参数校验异常。
发送与回复
QGGroup 支持使用 send(...) 向当前 QQ 群发送消息。 当 QGGroup 来自 event.content() 时,组件会自动携带当前消息的 msgId, 用于被动回复场景,不消耗主动消息次数。
也可以直接使用消息事件的 reply(...):
reply(...) 会尝试附加引用回复效果。 对 QGGroupMessageCreateEvent.reply(...) 的发送前、发送后拦截事件分别是 QGGroupMessageCreateEventPreReplyEvent 与 QGGroupMessageCreateEventPostReplyEvent。
群消息事件的 messageContent 自 5.0 起支持撤回当前收到的消息, 而 content().send(...) 与 reply(...) 返回的消息回执也可以撤回对应的机器人消息。 消息时效、群成员权限以及不支持场景的处理方式,参见 消息撤回。
上传群聊媒体
QGGroup.uploadMedia(...) 可上传用于向 QQ 群发送的 QGMedia。 目前上传仅支持链接,QQ 平台会对此链接进行转存。
type 使用 QQ 平台的媒体类型值: 1 图片、 2 视频、 3 语音、 4 文件(暂不开放)。