快速开始

本章用 5 分钟 走完一个挂件「Hello, world!」的完整流程：从零起一个目录，写两个文件，在主播酱里看到它出现在画布上，并且能响应礼物事件。

读完本章你会知道：

一个挂件最少由哪些文件组成；
如何在不打包、不安装的情况下让主播酱加载本地挂件；
如何在挂件里用 window.ZBJ 拿到配置和实时事件。

前置条件：本地装有 主播酱客户端（支持创意工坊的版本），以及任意能编辑文本的编辑器即可。开发挂件不需要 Node.js、不需要构建工具——一个 .html 文件足够。

不想从零写？ 仓库根目录 demo-widgets/ 里有五个现成示例：hello-world（本章产物）、gift-roll（完整教程的礼物滚动榜）、danmaku-wall（弹幕墙）、welcome-toast（进场欢迎横幅）、clock（时钟，等比字号自适应）。按下面「第 4 步」直接选 demo-widgets/<目录>/manifest.json 注册即可看到效果。

第 1 步：准备一个目录

随便在硬盘上找个位置建一个文件夹，命名随意：

hello-widget/
├── manifest.json
└── index.html

两个文件，没了。

第 2 步：写 `manifest.json`

manifest.json 是挂件的「身份证」，告诉主播酱：这个挂件叫什么、默认多大、有哪些用户可调的配置项。

json

{
  "manifestVersion": 1,
  "id": "hello-widget",
  "name": "我的第一个挂件",
  "version": "0.1.0",
  "author": "你的名字",
  "sdkVersion": 1,
  "defaultSize": { "width": 320, "height": 120 },
  "category": "custom",
  "config": [
    {
      "key": "text",
      "type": "text",
      "label": "显示文字",
      "default": "Hello, 主播酱!"
    }
  ]
}

字段含义看 manifest 规范，现在只需要知道：

id 全局唯一，建议小写加连字符；
defaultSize 是挂件刚拖到画布时的初始尺寸；
category 决定挂件在素材面板/挂件库/未来市场里的归属分类。取值直接复用 ElementType 字符串："custom"（默认 · 自定义新玩法）/ "Text" / "Image" / "Video" / "GiftMenu" / "OvertimeMachine" / "LikeRank" / "WishList" / "ChatRenderer"。声明对应分类后，挂件会出现在「素材 → 加班机」这类菜单与内置元素并列。不影响实现，挂件运行时始终是 CustomWidget + iframe。详见 manifest §2.1；
config 数组里每一项都会自动在主播酱的元素配置面板里渲染成一个表单控件——这里我们只声明了一个文本框 text。

第 3 步：写 `index.html`

挂件本质上就是一个网页。主播酱用 iframe 把它嵌进画布。

html

<!doctype html>
<html lang="zh">
<head>
  <meta charset="utf-8" />
  <style>
    html, body {
      margin: 0; height: 100%;
      background: transparent;     /* 必须透明，与画布合成 */
      display: flex; align-items: center; justify-content: center;
      font: 600 32px/1.2 system-ui, sans-serif;
      color: #fff;
      text-shadow: 0 2px 6px rgba(0, 0, 0, .4);
    }
  </style>
</head>
<body>
  <div id="app">…</div>

  <script src="http://127.0.0.1:9855/widget-sdk/zbj-widget-sdk.js"></script>
  <script>
    ZBJ.ready(() => {
      const el = document.getElementById("app");

      // 初次渲染
      el.textContent = ZBJ.config.text;

      // 配置面板改了文字，自动同步
      ZBJ.onConfigChange(cfg => {
        el.textContent = cfg.text;
      });
    });
  </script>
</body>
</html>

三个细节解释一下：

写法	为什么
`background: transparent`	挂件在直播画面上叠加显示，不透明背景会挡住下层内容。详见开发约定 §1
`<script src="http://127.0.0.1:9855/widget-sdk/zbj-widget-sdk.js">`	SDK 由主播酱内嵌的 Fastify 服务托管，端口固定 `9855`。开发阶段直接用绝对地址即可
`ZBJ.ready(cb)`	SDK 从 URL hash 拿到 init、`config` / `theme` 都填好后才会执行 `cb`；之前读 `ZBJ.config` 是空对象

第 4 步：在主播酱里注册（开发者模式）

主播酱提供了「开发者模式」直接加载本地目录里的挂件，不需要打包安装。

打开主播酱，进入主界面；
在 素材面板 切换到「挂件」分类，点击「创意工坊」按钮，弹出工坊窗口；
切换到 「开发者」 标签页；
填写：
- manifest 路径：选中你刚刚的 hello-widget/manifest.json；
- 挂件源 URL（可选）：留空时由主播酱内嵌服务直接托管 manifest.json 同级目录下的静态文件（URL 形如 http://127.0.0.1:9855/dev-widgets/<id>/index.html）；如果你用了 Vite/Webpack dev server，填写 dev server 地址（如 http://localhost:5173）以接管资源加载。
点「注册」。

注册成功后挂件会出现在「我的挂件」列表里，缩略图位置显示默认占位图（manifest 没指定 thumbnail 时）。

第 5 步：拖到画布

回到主界面：

在「我的挂件」里点中「我的第一个挂件」；
点击「添加到画布」（或直接双击）；
画布中央出现一个 320 × 120 的元素，显示 「Hello, 主播酱!」。

选中这个元素，右侧配置面板会出现「显示文字」输入框（就是 manifest 里声明的 config.text）。改一个字看看——挂件里的文字会实时跟着变。

到这里，最小闭环已经跑通：

manifest.json → 配置面板表单
config.text   → ZBJ.config.text → 页面文本

第 6 步（可选）：响应礼物事件

挂件不止能显示静态内容，还能直连平台事件流。在 <script> 里加一段：

ZBJ.on("gift", e => {
  el.textContent = `${e.nickname} 送出 ${e.giftName} ×${e.giftCount}`;
});

保存、回到主播酱（开发者模式下 index.html 会自动重载），随便测试一条礼物消息（可通过主播酱的「测试事件」功能模拟，或连接真实直播间），就能在挂件上看到弹幕级别的实时数据。

所有可用事件类型见平台事件。

下一步

我想…	看这里
跟着做一个完整的礼物滚动榜（含主题、动画、持久化、打包）	完整教程
知道 manifest 都能写些什么字段	manifest 规范
查 `window.ZBJ` 的所有接口	Widget SDK API
调试时打开 DevTools、看日志、排查白屏	调试与排错
打包成 `.zip` 分享给别人	打包与发布
看更多代码片段（弹幕墙、RPC、storage）	示例集

快速开始 ​

第 1 步：准备一个目录 ​

第 2 步：写 manifest.json ​

第 3 步：写 index.html ​

第 4 步：在主播酱里注册（开发者模式） ​

第 5 步：拖到画布 ​

第 6 步（可选）：响应礼物事件 ​

下一步 ​