Bilibili 事件实体

约 1669 字大约 6 分钟

2026-03-19

Bilibili 平台的事件实体完整参考。覆盖直播间、私信、评论、动态四大场景。

导入路径： from ncatbot.event.bilibili import DanmuMsgEvent, BiliPrivateMessageEvent, ...

源码： ncatbot/event/bilibili/

直播间事件

所有直播间事件继承自 BiliLiveEvent，自带 GroupScoped trait（group_id 返回 room_id）。

BiliLiveEvent

直播间事件基类。Trait： GroupScoped

属性	类型	说明
`group_id`	`str`	直播间 ID (`room_id`)
`api`	`IBiliAPIClient`	Bilibili API 客户端

DanmuMsgEvent

弹幕消息事件。Traits： Replyable, HasSender, Bannable, GroupScoped

属性	类型	说明
`user_id`	`str`	发送者 UID
`sender`	`BiliSender`	发送者信息

方法	签名	说明
`reply()`	`async (text: str)`	发送弹幕到直播间
`ban()`	`async (duration=1)`	禁言用户（小时）

@bot.on_event(DanmuMsgEvent)
async def handle(event: DanmuMsgEvent):
    await event.reply("已收到弹幕")
    # await event.ban(duration=1)  # 禁言 1 小时

注意： ban() 的 duration 单位是小时（QQ 平台是秒）。

SuperChatEvent

醒目留言 (SC) 事件。Traits： HasSender, GroupScoped

属性	类型	说明
`user_id`	`str`	发送者 UID
`sender`	`BiliSender`	发送者信息

数据层额外字段（通过 event.data 访问）：

字段	类型	说明
`content`	`str`	SC 内容
`price`	`int`	金额
`duration`	`int`	持续时间 (秒)

GiftEvent

礼物事件。Traits： HasSender, GroupScoped

属性	类型	说明
`user_id`	`str`	发送者 UID
`sender`	`BiliSender`	发送者信息

数据层额外字段：

字段	类型	说明
`gift_name`	`str`	礼物名称
`gift_id`	`str`	礼物 ID
`num`	`int`	数量
`price`	`int`	价格
`coin_type`	`str`	币种（`"gold"` / `"silver"`）

GuardBuyEvent

大航海购买事件。Traits： HasSender, GroupScoped

属性	类型	说明
`user_id`	`str`	购买者 UID
`sender`	`BiliSender`	购买者信息

数据层额外字段：

字段	类型	说明
`guard_level`	`int`	等级（`1`=总督, `2`=提督, `3`=舰长）
`price`	`int`	价格

InteractEvent

互动事件（进入直播间 / 关注 / 分享）。Traits： HasSender, GroupScoped

属性	类型	说明
`user_id`	`str`	用户 UID
`sender`	`BiliSender`	用户信息

数据层额外字段：

字段	类型	说明
`interact_type`	`int`	互动类型

LikeEvent

点赞事件。Traits： HasSender, GroupScoped

属性	类型	说明
`user_id`	`str`	用户 UID
`sender`	`BiliSender`	用户信息

数据层额外字段：

字段	类型	说明
`like_count`	`int`	点赞数

LiveNoticeEvent

直播间通知事件（兜底）。Trait： GroupScoped

用于没有专属实体类的直播间通知，以及开播/下播状态事件。通过 event.data（或 event._data）访问具体字段。

LiveStatusEventData

开播/下播状态事件。live_event_type = "LIVE" 或 "PREPARING"

字段	类型	说明
`status`	`str`	状态字符串（`"live"` = 开播，`"preparing"` = 下播）
`live_time`	`int`	开播时间戳（秒）。同一场直播的重复 `LIVE` 事件值相同；上游缺失时为 `0`
`room_info`	`Optional[LiveRoomInfo]`	完整直播间信息（仅开播时填充，下播为 `None`）

推荐使用 registrar.bilibili.on_live_start() / on_live_end() 而不是原始事件路由。详见事件注册指南。

from ncatbot.event.bilibili import LiveNoticeEvent

@registrar.bilibili.on_live_start()
async def on_start(self, event: LiveNoticeEvent):
    data = event._data  # LiveStatusEventData
    print(f"本场直播开播时间戳: {data.live_time}")
    if data.room_info:
        title = data.room_info.room_info.title
        anchor = data.room_info.anchor_info.name
        print(f"[开播] {anchor}: {title}")

@registrar.bilibili.on_live_end()
async def on_end(self, event: LiveNoticeEvent):
    print("[下播]")

以下数据模型也降级为 LiveNoticeEvent：

WatchedChangeEventData

观看人数变化。live_event_type = "WATCHED_CHANGE"

字段	类型	说明
`num`	`int`	观看人数
`text_small`	`str`	简短文本（如 `"2.3万"`）
`text_large`	`str`	完整文本（如 `"2.3万人看过"`）

LikeUpdateEventData

点赞数更新（全局累计）。live_event_type = "LIKE_INFO_V3_UPDATE"

字段	类型	说明
`click_count`	`int`	累计点赞数

OnlineRankCountEventData

在线排名人数。live_event_type = "ONLINE_RANK_COUNT"

字段	类型	说明
`count`	`int`	在线人数

OnlineRankV3EventData

在线排名列表。live_event_type = "ONLINE_RANK_V3"

字段	类型	说明
`online_list`	`list`	排名列表（uid、score、uname 等）

DanmuAggregationEventData

弹幕聚合（节日/活动弹幕）。live_event_type = "DANMU_AGGREGATION"

字段	类型	说明
`activity_identity`	`str`	活动 ID
`msg`	`str`	聚合弹幕内容
`aggregation_num`	`int`	参与人数

DmInteractionEventData

互动消息（分享直播间等）。live_event_type = "DM_INTERACTION"

字段	类型	说明
`interaction_type`	`int`	互动类型
`suffix_text`	`str`	描述文本

EntryEffectEventData

进场特效。live_event_type = "ENTRY_EFFECT"

字段	类型	说明
`user_id`	`str`	进场用户 UID
`user_name`	`str`	用户名
`sender`	`BiliSender`	发送者信息

@registrar.on("live", platform="bilibili")
async def on_notice(event):
    from ncatbot.types.bilibili.events import WatchedChangeEventData
    if isinstance(event.data, WatchedChangeEventData):
        print(f"观看人数: {event.data.text_large}")

静默忽略的事件： STOP_LIVE_ROOM_LIST（停播房间列表推送，无业务价值）。

私信事件

BiliPrivateMessageEvent

B 站私信消息事件。Traits： Replyable, HasSender

属性	类型	说明
`user_id`	`str`	发送者 UID
`sender`	`BiliSender`	发送者信息

方法	签名	说明
`reply()`	`async (text: str)`	回复私信

数据层额外字段：

字段	类型	说明
`message`	`MessageArray`	消息内容
`msg_type`	`str`	消息类型
`msg_key`	`str`	消息 key
`receiver_id`	`str`	接收者 ID

@bot.on_event(BiliPrivateMessageEvent)
async def handle(event: BiliPrivateMessageEvent):
    await event.reply("收到你的私信")

BiliPrivateMessageWithdrawEvent

B 站私信撤回事件。无额外 Trait。

数据层字段：

字段	类型	说明
`user_id`	`str`	撤回者 UID
`msg_key`	`str`	被撤回消息的 key

评论事件

BiliCommentEvent

B 站评论事件。Traits： Replyable, HasSender, Deletable

属性	类型	说明
`user_id`	`str`	评论者 UID
`sender`	`BiliSender`	评论者信息

方法	签名	说明
`reply()`	`async (text: str)`	回复评论
`delete()`	`async ()`	删除评论

数据层额外字段：

字段	类型	说明
`resource_id`	`str`	资源 ID
`resource_type`	`str`	资源类型
`comment_id`	`str`	评论 ID
`content`	`str`	评论内容
`root_id`	`str`	根评论 ID
`parent_id`	`str`	父评论 ID
`like_count`	`int`	点赞数

@bot.on_event(BiliCommentEvent)
async def handle(event: BiliCommentEvent):
    await event.reply("感谢评论")
    # await event.delete()  # 删除评论

动态事件

BiliDynamicEvent

B 站用户动态事件（新动态发布 / 动态被删除）。Traits： HasSender

属性	类型	说明
`user_id`	`str`	发布者 UID
`sender`	`BiliSender`	发布者信息
`dynamic_id`	`str`	动态 ID
`dynamic_type`	`str`	动态类型（`DYNAMIC_TYPE_DRAW`、`DYNAMIC_TYPE_AV` 等）
`text`	`str?`	动态文本内容（可能为空）

数据层额外字段（通过 event.data 访问）：

字段	类型	说明
`dynamic_status`	`str`	`"new"` = 新动态，`"deleted"` = 被删除
`dynamic_event_type`	`str`	`"new_dynamic"` / `"deleted_dynamic"`
`pub_ts`	`int`	发布时间戳
`pub_time`	`str`	发布时间文本
`pics_url`	`list?`	图片 URL 列表
`tag`	`str?`	动态话题标签
`stat`	`DynamicStatInfo?`	统计信息（评论/点赞/转发数）
`video`	`DynamicVideoInfo?`	视频动态附带的视频信息
`music`	`DynamicMusicInfo?`	音乐动态附带的音乐信息
`article`	`DynamicArticleInfo?`	专栏动态附带的文章信息
`live_rcmd`	`DynamicLiveRcmdInfo?`	直播推荐动态附带的直播间信息
`forward_dynamic_id`	`str?`	转发动态的原始动态 ID

from ncatbot.event.bilibili import BiliDynamicEvent

@bot.on_event(BiliDynamicEvent)
async def handle(event: BiliDynamicEvent):
    data = event._data
    if data.dynamic_status == "new":
        print(f"用户 {event.user_id} 发布了 {event.dynamic_type} 动态")
        if data.video:
            print(f"视频: {data.video.title}")
    elif data.dynamic_status == "deleted":
        print(f"用户 {event.user_id} 删除了动态 {event.dynamic_id}")

工厂映射

Bilibili 工厂 (create_bili_entity) 的映射规则：

精确映射：

数据模型	→ 实体类
`DanmuMsgEventData`	`DanmuMsgEvent`
`SuperChatEventData`	`SuperChatEvent`
`GiftEventData`	`GiftEvent`
`GuardBuyEventData`	`GuardBuyEvent`
`InteractEventData`	`InteractEvent`
`LikeEventData`	`LikeEvent`
`BiliPrivateMessageEventData`	`BiliPrivateMessageEvent`
`BiliPrivateMessageWithdrawEventData`	`BiliPrivateMessageWithdrawEvent`
`BiliCommentEventData`	`BiliCommentEvent`
`BiliDynamicEventData`	`BiliDynamicEvent`

降级映射：

post_type	→ 降级实体
`live`	`BiliLiveEvent`
`message`	`BaseEvent`
`comment`	`BaseEvent`
`dynamic`	`BaseEvent`
`system`	`BaseEvent`

继承关系

BaseEvent (common)
├── BiliLiveEvent                    GroupScoped
│   ├── DanmuMsgEvent                + Replyable, HasSender, Bannable
│   ├── SuperChatEvent               + HasSender
│   ├── GiftEvent                    + HasSender
│   ├── GuardBuyEvent                + HasSender
│   ├── InteractEvent                + HasSender
│   ├── LikeEvent                    + HasSender
│   └── LiveNoticeEvent              (无额外 trait)
├── BiliPrivateMessageEvent          Replyable, HasSender
├── BiliPrivateMessageWithdrawEvent  (无 trait)
├── BiliCommentEvent                 Replyable, HasSender, Deletable
└── BiliDynamicEvent                 HasSender

交叉引用

通用事件基础 — BaseEvent、Mixin Traits
QQ 事件实体 — QQ 平台事件
Bilibili 平台类型 — BiliSender、枚举、数据模型

版权所有

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)

通用

QQ

Bilibili

GitHub

AI

Misc

Bilibili 事件实体

直播间事件

BiliLiveEvent

DanmuMsgEvent

SuperChatEvent

GiftEvent

GuardBuyEvent

InteractEvent

LikeEvent

LiveNoticeEvent

LiveStatusEventData

WatchedChangeEventData

LikeUpdateEventData

OnlineRankCountEventData

OnlineRankV3EventData

DanmuAggregationEventData

DmInteractionEventData

EntryEffectEventData

私信事件

BiliPrivateMessageEvent

BiliPrivateMessageWithdrawEvent

评论事件

BiliCommentEvent

动态事件

BiliDynamicEvent

工厂映射

继承关系

交叉引用

版权所有