自定义配置页面
用户插件可以拥有和平台内置插件(例如「群管家」)一样独立的配置入口。开发者不需要写任何前端代码,只要在 plugin.json 里声明 settings_schema,平台就会渲染出配置表单、做前后端双重校验、按「用户 + 机器人」分别保存,并在运行时把结果放进 ctx.settings。
先看这一条
配置页只支持 .wwp / .zip 包(内含 plugin.json)。直接上传单个 .js 文件不会带上 settings_schema,这也是"我写了 schema 但配置入口不出现"最常见的原因。打包方式见插件包与清单。
一、5 分钟做出第一个配置页
1. 目录结构
my-plugin.wwp
├─ plugin.json ← 配置页 schema 写在这里
└─ index.js ← 插件逻辑,读 ctx.settings2. plugin.json
{
"slug": "greet-config",
"name": "问候助手",
"version": "1.0.0",
"entry": "index.js",
"description": "带配置页的示例插件",
"commands": ["问候"],
"settings_schema": [
{
"key": "enabled",
"label": "启用自动问候",
"type": "switch",
"default": true,
"section": "基础设置",
"section_hint": "关闭后插件不再响应任何消息"
},
{
"key": "greet_text",
"label": "问候语",
"type": "text",
"default": "你好呀",
"required": true,
"placeholder": "例如:早上好",
"hint": "支持 {name} 占位符,运行时替换为对方昵称",
"section": "基础设置"
},
{
"key": "tone",
"label": "语气",
"type": "select",
"default": "friendly",
"width": "half",
"section": "基础设置",
"options": [
{ "label": "亲切", "value": "friendly" },
{ "label": "正式", "value": "formal" }
]
}
]
}3. index.js
module.exports = {
name: '问候助手',
async onMessage(ctx) {
if (ctx.settings.enabled === false) return false;
if (!String(ctx.content || '').startsWith('问候')) return false;
const name = ctx.userName || '群友';
const text = String(ctx.settings.greet_text || '你好呀');
await ctx.reply(text.replaceAll('{name}', name));
return true;
},
};4. 打包、上传、安装
打包成 .wwp → 开发者中心上传 → 审核通过 → 插件商店安装到某台机器人。
5. 用户在哪里配置
插件商店 → 我的插件 → 找到插件 → 点「配置」只有声明了 settings_schema 的插件才会出现「配置」按钮。用户保存后立即生效,无需重启机器人。
二、配置是怎么生效的
| 环节 | 平台行为 |
|---|---|
| 渲染 | 按 section 分组渲染成卡片,width: "half" 的字段两列排布,其余整行 |
| 校验 | 前端按 required / min / max / 枚举即时校验;后端保存时再完整校验一次,前端绕过也提交不了非法值 |
| 存储 | 按「用户 + 机器人 + 插件」独立保存,同一插件在 A 机器人的配置不影响 B 机器人 |
| 读取 | 运行时注入 ctx.settings,onMessage、onMessage 之外的事件(如 onRelayEvent)都能读 |
| 默认值 | 用户没保存过也会按 default 自动补齐(运行时用"允许缺省"模式做一次归一化) |
| 版本 | schema 跟随已审核安装的版本,待审新版本不会提前改变线上用户的配置结构 |
ctx.settings 是只读快照。 插件不能自己改写用户配置——需要可变状态请用 ctx.kv。
三、字段类型全表
| type | 运行时值类型 | 适用场景 | 额外属性 |
|---|---|---|---|
text | string | 单行文本、链接、短模板 | placeholder hint |
password | string | API Key、Token(界面遮罩) | placeholder hint |
textarea | string | 多行规则、提示词、长模板 | rows(2–12,默认 4) |
number | number | 次数、时长、阈值 | min max step |
switch | boolean | 功能开关 | — |
select | string / number / boolean | 单选 | options(必填) |
checkbox-group | array | 多选 | options(必填) |
image | string | 单图上传(预览 / 更换 / 删除):封面、背景图、横幅 | — |
image-list | string[] | 多图相册,九宫格上传 | max(上限,硬顶 9) |
info | — | 纯说明区块(只展示 label + hint),不产生用户输入 | — |
color | string | 颜色选择,存 #RRGGBB | — |
date | string | 日期选择,存 YYYY-MM-DD | — |
options 每一项:
{ "label": "显示名", "value": "实际值", "disabled": false }value 只能是字符串、数字或布尔值。
password 不是加密
password 只做界面遮罩,保存后仍是明文存在安装配置里。绝对不要把 QQ AppSecret、平台账号密码这类平台级凭据放进插件配置。 第三方 API Token 也请按最小权限申请、支持随时重置。
四、字段属性参考
| 属性 | 类型 | 说明 |
|---|---|---|
key | string | 必填。字母开头,2–64 位,可含字母数字和 . _ -;同一插件内不可重复 |
label | string | 必填。显示名,最长 80 字 |
type | string | 必填。必须是上表 12 种之一,写错该字段会被整条丢弃 |
default | 与类型一致 | 默认值;不写时 switch 为 false、number 为 min 或 0、多选为 []、其余为空字符串 |
required | boolean | 必填;保存时为空会报「请填写「字段名」」 |
placeholder | string | 输入框占位文字,最长 200 字 |
hint | string | 字段下方灰色说明,最长 500 字 |
section | string | 分组标题,默认「基础配置」;相邻同名字段会归到同一张卡片 |
section_hint | string | 分组说明,只在该组第一个字段上写即可(也兼容 sectionHint) |
width | "full" | "half" | 桌面端整行或半行,默认 full |
min max | number | 仅 number;保存时超出范围会被自动夹到边界值,不报错 |
step | number | 仅 number,必须大于 0 |
rows | number | 仅 textarea,2–12 |
show_when | object | 条件显示,见下 |
条件显示 show_when
字段可以跟随另一个字段的取值显示或隐藏:
{
"key": "mute_minutes",
"label": "禁言时长(分钟)",
"type": "number",
"min": 1,
"max": 4320,
"default": 10,
"section": "群管策略",
"show_when": { "key": "punish_mute", "equals": true }
}支持两种判断:
| 写法 | 含义 |
|---|---|
{ "key": "a", "equals": 值 } | 字段 a 等于该值时显示 |
{ "key": "a", "not_equals": 值 } | 字段 a 不等于该值时显示 |
show_when 只影响界面显示,被隐藏的字段依然会按默认值保存(这也是"用户没填却拿到了值"的原因)。
五、一个像「群管家」那样的完整示例
多分组、半宽排布、开关联动、多选,一份可直接改用:
{
"slug": "group-helper",
"name": "群管助手",
"version": "2.0.0",
"entry": "index.js",
"settings_schema": [
{ "key": "enabled", "label": "启用群管", "type": "switch", "default": true, "section": "总开关", "section_hint": "关闭后所有群管策略都不生效" },
{ "key": "punish_mute", "label": "违规禁言", "type": "switch", "default": true, "width": "half", "section": "违规处理" },
{ "key": "mute_minutes", "label": "禁言时长(分钟)", "type": "number", "min": 1, "max": 4320, "step": 1, "default": 10, "width": "half", "section": "违规处理", "show_when": { "key": "punish_mute", "equals": true } },
{ "key": "punish_kick", "label": "累计违规踢出", "type": "switch", "default": false, "width": "half", "section": "违规处理" },
{ "key": "kick_after", "label": "第几次违规踢出", "type": "number", "min": 2, "max": 20, "default": 3, "width": "half", "section": "违规处理", "show_when": { "key": "punish_kick", "equals": true } },
{ "key": "warn_template", "label": "警告文案", "type": "textarea", "rows": 4, "default": "检测到违规内容,请遵守群规(第 {count} 次)", "hint": "支持 {user} {count} {rule} 占位符", "section": "违规处理" },
{ "key": "scenes", "label": "生效场景", "type": "checkbox-group", "default": ["group"], "section": "生效范围", "options": [
{ "label": "群聊", "value": "group" },
{ "label": "私聊", "value": "c2c" },
{ "label": "临时会话", "value": "temp" }
] },
{ "key": "log_channel", "label": "违规日志推送群", "type": "text", "placeholder": "真实群号,留空则不推送", "section": "生效范围" }
]
}对应运行时读取:
module.exports = {
async onMessage(ctx) {
const s = ctx.settings;
if (s.enabled === false) return false;
if (!(s.scenes || []).includes('group')) return false;
const hit = checkRule(ctx.content);
if (!hit) return false;
const count = bumpCount(ctx.kv, ctx.userId);
if (s.punish_kick && count >= Number(s.kick_after || 3)) {
await ctx.requestUniqqAction('group.member.kick', { memberOpenid: ctx.userId });
return true;
}
if (s.punish_mute) {
await ctx.muteMember(ctx.userId, Number(s.mute_minutes || 10) * 60);
}
await ctx.reply(String(s.warn_template || '').replaceAll('{count}', String(count)));
return true;
},
};六、后端校验规则(精确行为)
保存时平台按顺序处理每个字段,理解它就不会踩坑:
| 类型 | 处理方式 |
|---|---|
switch | true / 1 / "1" / "true" 记为 true,其余为 false |
number | 不是数字直接报错「「字段名」必须是数字」;合法则夹在 [min, max] 区间内 |
select | 值不在 options 里时回退到 default,default 也不合法则取第一个选项 |
checkbox-group | 过滤掉不在 options 里的值、去重,最多保留 50 项 |
image | 只接受平台 /uploads/ 地址或 https 外链;非法值回退空串,required 且为空时报「请上传「字段名」的图片」 |
image-list | 逐项 URL 白名单校验 + 去重,最多保留 9 张;required 且为空时报「请至少上传 1 张「字段名」的图片」 |
info | 值固定为空串(纯展示,不存用户输入) |
color | 必须是 #RRGGBB,非法回退空串 |
date | 必须是 YYYY-MM-DD,非法回退空串 |
text / password | 转字符串,超长截断到 4000 字 |
textarea | 转字符串,超长截断到 20000 字 |
| 任意 | required 且为空(空串 / null / 空数组)时报「请填写「字段名」」 |
上限:单插件最多 120 个字段,单个 select/checkbox-group 最多 50 个选项。
图片字段的值是地址
配置页上传后,ctx.settings 里拿到的是图片地址(/uploads/… 或 https 外链),不是图片本体。配合 ctx.replyImage(url) / ctx.uploadImage(url) / Markdown 图片语法使用。info 字段声明的 required / default / placeholder 会被平台剥掉,别拿它存值。
七、常见问题排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 配置入口根本不出现 | ① 上传的是单个 .js,没走 .wwp 包;② settings_schema 写在 index.js 里而不是 plugin.json;③ 字段 type 拼错导致全部被丢弃;④ key 不符合命名规则;⑤ 插件还没审核通过且你不是作者 | 检查包结构,确认 JSON 合法,key 以字母开头 |
保存后 ctx.settings 没变化 | 改的是待审版本 | 审核通过并更新安装版本后生效 |
| 某个字段就是不显示 | show_when 依赖的字段值不满足条件 | 先把被依赖字段调成触发值 |
| 数字填 999 却被存成 100 | 设置了 max: 100,后端夹边界 | 属预期行为,调大 max 或放宽校验 |
| 用户没填却拿到了值 | default 会自动补齐(含被 show_when 隐藏的字段) | 想区分"未填"请用空字符串默认值 |
| 提示「开发者暂未为该插件提供配置项」 | 该安装版本没有有效 schema | 用 .wwp 重新上传并升版本 |
八、版本与审核规则
- 修改
settings_schema必须提升版本号重新提交审核。 - 审核通过前,已安装用户仍看到并使用旧版本的配置结构。
- 升级插件不会清空用户已有配置;新增字段用
default自动补齐。 - 删除字段后,该字段不再出现在用户配置里,也不会进入
ctx.settings。 - 用户可以在配置页点「恢复默认」,只重置当前机器人上的这份配置。
- 付费插件、作者本人安装同样走这套校验,没有例外。
九、发布前自检清单
- [ ]
settings_schema在plugin.json里,不是index.js - [ ] 打包成
.wwp上传,不是单文件.js - [ ] 每个字段的
key唯一、字母开头、2–64 位 - [ ]
select/checkbox-group都写了options,且default能在options里找到 - [ ] 必填字段都有合理默认值,避免用户第一次打开就保存失败
- [ ] 代码里读了
ctx.settings的字段名与 schema 完全一致(大小写敏感) - [ ] 没有把平台级密钥放进配置,敏感信息提示用户用
password - [ ] 升了版本号,
changelog写清这次改了哪些配置项
十、延伸阅读
- 插件包与清单 ——
plugin.json全部字段 - ctx API 总览 ——
ctx.settings、ctx.kv、ctx.http - 运行时与生命周期 —— 配置在何时被注入
- 安全规范与限制 —— 沙箱能力边界
需要编辑器类型提示可下载 SDK 声明:weiwei-plugin-sdk.d.ts。
