Skip to content

自定义控制台页面(ui/ 目录) ​

settings_schema 是声明式表单、console_resources 是声明式数据表格——两者都不够用的时候(相册管理、商品橱窗、可视化看板、复杂交互流程),插件包可以携带一个 ui/ 目录:你用任意 HTML / CSS / JavaScript 写真正的控制台页面,平台负责托管和沙箱隔离,安装者在「我的插件 → 配置插件」弹窗的「控制台」标签页里使用。

工作原理 ​

.wwp 包
├── plugin.json        ← 声明 console_pages(可选)
├── index.js           ← 插件代码
└── ui/                ← 控制台页面(跟随版本一起审核)
    ├── index.html     ← 入口(必须)
    ├── stats.html
    └── assets/app.css

审核通过后:
  https://平台域名/plugin-ui/<slug>/index.html   ← 平台托管
安装者控制台:sandbox iframe 加载(隔离登录态)+ __bridge.js 与平台通信
  • 页面跑在 opaque origin 沙箱 iframe 里:拿不到平台 cookie / localStorage / 父页面 DOM,fetch 直连平台 API 也会被拦截。这是刻意设计——页面代码即使有漏洞,也偷不走安装者的登录态。
  • 页面与平台的唯一通道是平台托管的桥脚本 /plugin-ui/__bridge.js,通过 window.wwp 读写本安装实例的数据。
  • 页面代码随版本一起走审核,未审核通过的版本不会被托管。

约束(不满足直接拒绝提交) ​

项目限制
入口文件必须有 ui/index.html
文件数量≤ 50 个
单文件≤ 1MB
总体积≤ 4MB(解压后)
扩展名白名单html htm js mjs css json txt md svg png jpg jpeg gif webp ico woff woff2 ttf
路径禁止 .. / 绝对路径 / 反斜杠

声明页面(可选) ​

plugin.json 里用 console_pages 声明每个页面在控制台左侧的名字与顺序:

json
{
  "console_pages": [
    { "key": "album", "label": "相册管理", "path": "index.html" },
    { "key": "stats", "label": "数据统计", "path": "stats.html" }
  ]
}
  • key:[A-Za-z0-9._-],页签标识;label ≤ 30 字;path 必须是 ui/ 里真实存在的文件。
  • 不声明时平台自动从 ui/ 顶层 html 推导(key = 文件名去扩展名)。
  • 升级插件时随版本一起更新,无需安装者重装。

纯控制台模式(standalone) ​

如果插件的管理功能复杂到连「左侧平台导航 + 内嵌页面」都不需要,可以在 plugin.json 里声明:

json
{
  "console_mode": "standalone"
}

声明后(必须同时携带 ui/ 页面,否则提交被拒),安装者点「配置」不再打开配置弹窗,而是直接进入一个全屏控制台页面:

  • 平台不再渲染 settings_schema 表单、console_resources 数据面板和「保存配置」按钮;
  • 整个界面就是插件自己的页面,配置读写通过 wwp.getSettings / wwp.setSettings 在页面内完成(历史配置值仍可读到);
  • wwp 其余 API(kv、console 数据增删改)全部可用;
  • 适合宠物/商城这类「管理后台」型插件;普通插件不建议用,保留默认弹窗体验更简单。

声明 console_mode 后 console_pages 仍可声明,但全屏页固定展示入口页(index.html),多页导航由插件页面内部自己实现。

桥脚本 API(window.wwp) ​

页面 <head> 加一行即可接入:

html
<script src="/plugin-ui/__bridge.js"></script>

所有 API 都是 Promise 风格,失败时 reject 一个 Error:

API说明
wwp.getSettings()读本安装实例的配置表单值(与配置弹窗同一份数据)
wwp.setSettings(patch)部分更新配置(只传要改的键),控制台表单同步刷新
wwp.kvGet(key) / wwp.kvSet(key, value) / wwp.kvDelete(key)插件 KV,与 ctx.kv 同一份存储;value 必须是 string,单键 ≤ 100KB
wwp.kvKeys()列出本实例全部 kv 键名
wwp.listItems(resourceKey, opts?)读 console_resources 声明的数据表,opts: { search, page, size, parent }
wwp.createItem(resourceKey, item, parent?)新增数据项
wwp.updateItem(resourceKey, itemId, item, parent?)更新数据项
wwp.deleteItem(resourceKey, itemId, parent?)删除数据项

数据同步语义:你在页面里 kvSet 的数据,插件代码 ctx.kv.get(key) 立即可读,反之亦然——群里指令改的和控制台页面改的是同一份数据。

完整示例:相册管理页 ​

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>群相册</title>
  <script src="/plugin-ui/__bridge.js"></script>
  <style>
    body { font: 14px/1.6 system-ui, sans-serif; margin: 16px; color: #1d342a; }
    .grid { display: flex; flex-wrap: wrap; gap: 12px; }
    img { width: 140px; height: 140px; object-fit: cover; border-radius: 8px; cursor: pointer; }
    .bar { display: flex; gap: 8px; margin-bottom: 14px; }
  </style>
</head>
<body>
  <h3>群相册</h3>
  <div class="bar">
    <input id="url" placeholder="粘贴图片 URL" style="flex:1">
    <button onclick="add()">添加</button>
  </div>
  <div id="grid" class="grid"></div>
  <script>
    const KEY = 'album:photos';
    async function render() {
      const { value } = await wwp.kvGet(KEY);
      const list = JSON.parse(value || '[]');
      document.getElementById('grid').innerHTML =
        list.map(u => `<img src="${u}" onclick="del('${u}')">`).join('');
    }
    async function add() {
      const url = document.getElementById('url').value.trim();
      if (!url) return;
      const list = JSON.parse((await wwp.kvGet(KEY)).value || '[]');
      list.push(url);
      await wwp.kvSet(KEY, JSON.stringify(list));
      document.getElementById('url').value = '';
      render();
    }
    async function del(url) {
      const list = JSON.parse((await wwp.kvGet(KEY)).value || '[]');
      await wwp.kvSet(KEY, JSON.stringify(list.filter(u => u !== url)));
      render();
    }
    render();
  </script>
</body>
</html>

插件代码侧照常读同一份数据:

js
async onMessage(ctx) {
  if (ctx.content !== '看相册') return false;
  const list = JSON.parse(ctx.kv.get('album:photos') || '[]');
  for (const url of list) await ctx.replyImage(url);
  return true;
}

实战参考 ​

平台自带插件 ZL-官机售卡系统 的 ui/ 目录是一个更完整的样板:总览统计、商品管理、卡密库存(批量导入 + 可用/已用/作废筛选)、订单查询四个视图,全部基于 wwp.kvGet/kvSet 操作 zlcs:* 系列键,可直接参照它的源码改造成你自己的控制台。

安全边界与审核要点 ​

  • 页面能力仅限本安装实例的 kv / settings / console 数据:发不了消息、碰不到别的插件数据、看不到平台用户信息。
  • 不要在页面里硬编码敏感信息(卡密内容会随页面进审核);动态展示的敏感数据建议用 kvGet 现取现显。
  • 页面里写 fetch / XMLHttpRequest / localStorage / 外链 script 在沙箱里跑不了,也会被审核驳回。
  • 图片资源可以用平台 /uploads/ 的 URL(安装者通过配置表单上传后经 wwp.getSettings() 拿到)。

薇薇官机平台 · ZL 系列插件