平台事件

挂件通过 ZBJ.on(event, callback) 订阅平台事件。SDK 将每个平台的原始消息归一化为统一结构后分发，作者无需关心各平台格式差异。

1. 事件类型

1.1 基础字段

export interface ZBJBaseEvent {
  /** 当前直播平台标识 */
  platform: ZBJPlatform;
  /** 事件时间戳（毫秒） */
  timestamp: number;
  /** 事件唯一 id；来自平台原始消息的 id，转字符串。命名为 `msgId` 以区别于挂件 `instanceId` */
  msgId: string;
  /** 触发用户昵称 */
  nickname: string;
  /** 触发用户头像 URL */
  avatar: string;
  /** 触发用户 userId（可能为空字符串） */
  userId: string;
  /** 用户在直播间的等级；平台未提供时为 `undefined` */
  userLevel?: number;
}

平台原始数据中昵称字段为 nickName（驼峰大小写），SDK 在归一化时统一改写为更通用的 nickname。事件 id 字段则在归一化中改名为 msgId，避免与挂件实例 instanceId / 挂件 widgetId 混淆。

1.2 事件列表

export interface ZBJGiftEvent extends ZBJBaseEvent {
  type: "gift";
  /** 平台礼物 id（字符串） */
  giftId: string;
  giftName: string;
  giftIcon: string;
  giftCount: number;
  /** 单个礼物折合钻石数（单位与平台礼物表对齐，通常为分） */
  diamondCount: number;
  comboGift: boolean;
}

export interface ZBJLikeEvent extends ZBJBaseEvent {
  type: "like";
  likeCount: number;
}

export interface ZBJChatEvent extends ZBJBaseEvent {
  type: "chat";
  content: string;
}

export interface ZBJEnterEvent extends ZBJBaseEvent {
  type: "enter";
}

export interface ZBJSocialEvent extends ZBJBaseEvent {
  type: "social";
  /** 取自平台原始 content / 子类型，可能值如 "follow" / "share" 等 */
  content: string;
}

export interface ZBJSubscribeEvent extends ZBJBaseEvent {
  type: "subscribe";
  /** 哔哩哔哩大航海 / 抖音专属会员等订阅类事件标记 */
  isMember: boolean;
  /** 哔哩哔哩大航海等级 1=总督 2=提督 3=舰长；抖音 subscribe.level */
  subscribeLevel?: number;
  memberType?: number;
}

/** 房间状态事件不含用户身份字段，仅描述房间快照 */
export interface ZBJRoomEvent {
  platform: ZBJPlatform;
  timestamp: number;
  type: "room";
  memberCount: number;
  totalUserCount: number;
  followCount: number;
  rank: { nickname: string; avatar: string; rank: number }[];
}

export type ZBJAnyEvent =
  | ZBJGiftEvent | ZBJLikeEvent | ZBJChatEvent
  | ZBJEnterEvent | ZBJSocialEvent | ZBJSubscribeEvent | ZBJRoomEvent;

1.3 message 总线

任意类型事件都会额外触发一次 message，用于需要原始全量流的高级场景：

ZBJ.on("message", (e: ZBJAnyEvent) => {
  if (e.type === "gift" && e.diamondCount > 1000) {
    /* 大额礼物处理 */
  }
});

2. 平台事件归一化映射

主播酱内部以 PlatformMessage.type 区分平台原始消息类型，下表为各类型到 SDK 归一化事件的映射：

所有事件先经基础字段映射（raw.id → msgId、raw.nickName → nickname、raw.userId / raw.avatar / raw.userLevel / raw.timestamp 原样、ctx.platform 填入 platform），再按 type 追加各自字段：

PlatformMessage.type	SDK 事件	额外字段映射
gift	gift	gift.id → giftId（字符串）、gift.name → giftName、gift.url → giftIcon、gift.count → giftCount、gift.diamondCount → diamondCount、gift.comboGift → comboGift
like	like	likeCount 原样
chat	chat	content 原样
enter	enter	仅基础字段
social	social	content 原样
subscribe	subscribe	isMember 原样、subscribeLevel 原样、memberType 原样
room	room	不附带基础字段；memberCount / totalUserCount / followCount / rank 原样
其他 / 未识别	—	不向挂件分发

非 "message" 类型的 WS 帧（如 "status" 心跳）也不向挂件分发。

3. 平台标识

ZBJ.platform 与 manifest 的 platforms 字段共用以下取值：

platform	中文名
bilibili	哔哩哔哩
douyin	抖音
kuaishou	快手
shipinhao	视频号
xiaohongshu	小红书

4. 平台事件能力差异

下表为各平台当前实测的事件覆盖情况，仅供挂件作者判断哪些玩法在哪些平台可用，非契约。SDK 不会因平台不支持而抛错，仅是某些事件「永不到达」。

事件	bilibili	douyin	kuaishou	shipinhao	xiaohongshu
gift	✅	✅	✅	✅	✅
chat	✅	✅	✅	✅	✅
enter	✅	✅	✅	✅	✅
like	✅	✅	⚠️ 视平台开放	⚠️ 视平台开放	⚠️ 视平台开放
subscribe	✅ 大航海	✅ 专属会员	—	—	—
social	✅ 关注 / 分享	✅	✅	⚠️	⚠️
room	⚠️	✅ RoomUserSeqMessage	⚠️	⚠️	⚠️

若挂件要求平台支持某事件才能工作，应在 manifest.platforms 限定可用平台；详见 manifest 规范 §2。

5. 测试事件

宿主在配置面板提供「发送测试事件」按钮，会通过 test-event 消息 下发一个伪造的归一化事件给 iframe。挂件按真实事件处理即可，无需特殊判定。

// 宿主下发的测试礼物事件示例
{
  type: "gift",
  platform: "douyin",
  timestamp: Date.now(),
  msgId: "test_gift_1",
  userId: "test_user",
  nickname: "测试用户",
  avatar: "https://.../default.png",
  giftId: "rose",
  giftName: "玫瑰",
  giftIcon: "https://.../rose.png",
  giftCount: 1,
  diamondCount: 1,
  comboGift: false
}

未连接真实直播间时，挂件作者通过测试事件按钮覆盖大多数调试场景；接入真实直播间后，事件流由主播酱实时推送。