事件（Event）¶
Matrix 适配器将 homeserver 推送的各类事件映射为 NoneBot Event 子类，供事件处理器使用。
事件类型¶
EventType 是事件的三大分类：
EventType = Literal["message", "notice", "meta"]
message— 消息类事件（房间文本、图片等）。notice— 通知类事件（成员变动、反应、输入状态等）。meta— 元事件（同步状态等）。
事件层次¶
Event (基类)
├── MetaEvent —— 元事件
│ └── SyncMetaEvent —— 同步元事件
├── NoticeEvent —— 通知事件
│ ├── MessageEvent —— ⚠ 注意继承链，见下
│ ├── RoomMemberEvent —— 房间成员变动
│ ├── ReactionEvent —— 表情反应
│ ├── RedactionEvent —— 消息撤回
│ ├── TypingEvent —— 输入状态
│ ├── ReceiptEvent —— 已读回执
│ ├── UnknownRoomEvent—— 未识别的房间事件
│ ├── InviteEvent —— 房间邀请
│ └── LeaveEvent —— 离开房间
└── (NoticeEvent)
├── RoomMessageEvent —— 普通房间消息
└── EncryptedRoomEvent —— Megolm 加密的房间消息
基类 Event¶
所有 Matrix 事件的通用基类，包含以下核心字段：
- Event.type: str¶
- Event.content: dict[str, Any]¶
- Event.event_id: EventId | None¶
- Event.sender: UserId | None¶
- Event.room_id: RoomId | None¶
- Event.origin_server_ts: int | None¶
- Event.to_me: bool¶
- Event.state_key: str | None¶
常用方法：
消息事件 MessageEvent¶
MessageEvent 是插件中最常用的事件类型，表示一条 Matrix 房间消息。
- MessageEvent.reply: EventId | None¶
回复目标事件 ID。
房间消息 RoomMessageEvent¶
普通的 m.room.message 事件。
加密消息 EncryptedRoomEvent¶
m.room.encrypted 事件。解密成功后，content 会被替换为明文内容，原始加密内容保留在 encrypted_content 中。
- EncryptedRoomEvent.encrypted_content: dict[str, Any]¶
通知事件¶
加密事件¶
适配器通过以下类型化事件报告加密状态，事件的 handle 属性提供对应的
异步 SDK 对象和状态操作：
VerificationEvent— 验证请求、SAS 和二维码状态。IdentityEvent— 设备信任和交叉签名身份变化。DecryptionFailureEvent— 解密失败和密钥请求进度。BackupEvent/RecoveryEvent— 备份和恢复进度。AuthenticationEvent— UIA 或 OAuth 身份重置挑战。
matrix_auto_accept_verification 只接受验证请求；插件仍必须比较 SAS 或
二维码后显式调用 confirm()。
成员变动 RoomMemberEvent¶
- RoomMemberEvent.membership¶
成员状态：
"join"/"invite"/"leave"/"ban"。
反应 ReactionEvent¶
- ReactionEvent.relates_to¶
- ReactionEvent.target_event_id¶
- ReactionEvent.key¶
反应 key（如
"👍"）。
撤回 RedactionEvent¶
- RedactionEvent.redacts: EventId | None¶
被撤回的事件 ID。
输入状态 TypingEvent¶
- TypingEvent.user_ids¶
当前房间内正在输入的用户 ID 列表。
邀请 InviteEvent¶
收到新的房间邀请时触发。
离开 LeaveEvent¶
用户离开或被踢出房间时触发。
事件分发映射¶
event_classes 字典将 Matrix 事件类型映射到对应的 Event 子类：
event_classes: dict[str, type[Event]] = {
"m.room.message": RoomMessageEvent,
"m.room.encrypted": EncryptedRoomEvent,
"m.room.member": RoomMemberEvent,
"m.reaction": ReactionEvent,
"m.room.redaction": RedactionEvent,
"m.typing": TypingEvent,
"m.receipt": ReceiptEvent,
}
未在映射表中的事件类型将使用 UnknownRoomEvent。