主题
创意工坊
主播酱「创意工坊」（Creative Workshop）为客户端开放挂件（Widget）扩展机制：任何前端开发者都可以用 一个 manifest.json + 一个 index.html 做出一个挂件，由主播酱通过 iframe 渲染到画布上，与文本、图片、视频等内置元素并列，并随场景一起进入虚拟摄像头推流输出。
不需要懂 Electron、不需要懂客户端代码——会写 HTML / CSS / JavaScript 就够了。
我想…
| 想做的事 | 建议从这里开始 |
|---|---|
| 不想写代码，先直接跑现成示例 | 仓库根目录 demo-widgets/（含 README）— 5 个可直接装入挂件库的示例 |
| 5 分钟做出第一个挂件，看到效果 | 快速开始 |
| 跟着教程做一个完整可用的礼物滚动榜 | 完整教程 |
| 看挂件、宿主、虚拟摄像头之间是什么关系 | 架构设计 |
查清单字段（manifest.json 怎么写） | manifest 规范 |
| 让挂件出现在「素材 → 加班机」这类菜单与内置元素并列 | manifest §2.1 元素分类 category |
查代码接口（window.ZBJ 有什么 API） | Widget SDK API |
| 看礼物 / 弹幕 / 进场等事件的字段 | 平台事件 |
| 怎么打包发给别人 | 打包与发布 |
| 调试时白屏 / SDK 没加载 / 收不到事件 | 调试与排错 |
| 看 SDK 版本承诺与未支持能力 | 版本策略 |
关键约定
读后续任一篇文档之前，先记住四件事：
- 挂件运行在 iframe 内，与主播酱本体内存隔离，通过
window.ZBJ与宿主通信。 - 挂件 UI 不接收鼠标键盘——画布上的挂件 iframe 恒
pointer-events: none，交互通过事件流（礼物 / 弹幕等）和宿主的配置面板表达。 - 挂件背景必须透明，与下层画布合成；不透明背景会盖住其他元素。
- 生命周期入口是
ZBJ.ready(() => …)，业务代码应包在 ready 回调内运行；ready 之前ZBJ.config是空对象。
详细规则见 开发约定。
术语
| 术语 | 含义 |
|---|---|
| 挂件（Widget） | 一个静态页面包（目录或 .zip），在画布上以一个挂件元素呈现 |
| 宿主（Host） | 主播酱客户端运行挂件 iframe 的环境，负责加载、配置面板渲染、与 SDK 通信 |
| SDK | zbj-widget-sdk.js，挂件页面引入后在 window.ZBJ 暴露 API |
| 实例（Instance） | 画布上的一个挂件元素；同一挂件可被多次添加，各实例 instanceId 不同 |
| 模式（Mode） | iframe 当前所处的窗口类型：edit（编辑窗）/ preview（预览窗）/ virtualcam（虚拟摄像头窗） |
| 面（Surface） | 挂件的渲染入口；当前 v1 只定义 canvas（直播画面展示面，纯展示） |
支持的直播平台
清单中 platforms 字段、SDK ZBJ.platform 与平台事件归一化共用以下平台标识：
bilibili— 哔哩哔哩douyin— 抖音kuaishou— 快手shipinhao— 视频号xiaohongshu— 小红书
各平台事件能力差异详见 平台事件。
文档读法建议
| 你是 | 阅读顺序 |
|---|---|
| 第一次接触，想动手做 | 快速开始 → 完整教程 → 调试与排错 → 打包与发布，按需回查 manifest / SDK |
| 想全面了解能力 | 架构设计 → manifest 规范 → SDK API → 平台事件 → 开发约定 |