自定义控制台页面(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()拿到)。
