Skip to content

自定义配置页面 ​

用户插件可以拥有和平台内置插件(例如「群管家」)一样独立的配置入口。开发者不需要写任何前端代码,只要在 plugin.json 里声明 settings_schema,平台就会渲染出配置表单、做前后端双重校验、按「用户 + 机器人」分别保存,并在运行时把结果放进 ctx.settings。

先看这一条

配置页只支持 .wwp / .zip 包(内含 plugin.json)。直接上传单个 .js 文件不会带上 settings_schema,这也是"我写了 schema 但配置入口不出现"最常见的原因。打包方式见插件包与清单。

一、5 分钟做出第一个配置页 ​

1. 目录结构 ​

text
my-plugin.wwp
├─ plugin.json      ← 配置页 schema 写在这里
└─ index.js         ← 插件逻辑,读 ctx.settings

2. plugin.json ​

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 ​

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. 用户在哪里配置 ​

text
插件商店 → 我的插件 → 找到插件 → 点「配置」

只有声明了 settings_schema 的插件才会出现「配置」按钮。用户保存后立即生效,无需重启机器人。

二、配置是怎么生效的 ​

环节平台行为
渲染按 section 分组渲染成卡片,width: "half" 的字段两列排布,其余整行
校验前端按 required / min / max / 枚举即时校验;后端保存时再完整校验一次,前端绕过也提交不了非法值
存储按「用户 + 机器人 + 插件」独立保存,同一插件在 A 机器人的配置不影响 B 机器人
读取运行时注入 ctx.settings,onMessage、onMessage 之外的事件(如 onRelayEvent)都能读
默认值用户没保存过也会按 default 自动补齐(运行时用"允许缺省"模式做一次归一化)
版本schema 跟随已审核安装的版本,待审新版本不会提前改变线上用户的配置结构

ctx.settings 是只读快照。 插件不能自己改写用户配置——需要可变状态请用 ctx.kv。

三、字段类型全表 ​

type运行时值类型适用场景额外属性
textstring单行文本、链接、短模板placeholder hint
passwordstringAPI Key、Token(界面遮罩)placeholder hint
textareastring多行规则、提示词、长模板rows(2–12,默认 4)
numbernumber次数、时长、阈值min max step
switchboolean功能开关—
selectstring / number / boolean单选options(必填)
checkbox-grouparray多选options(必填)
imagestring单图上传(预览 / 更换 / 删除):封面、背景图、横幅—
image-liststring[]多图相册,九宫格上传max(上限,硬顶 9)
info—纯说明区块(只展示 label + hint),不产生用户输入—
colorstring颜色选择,存 #RRGGBB—
datestring日期选择,存 YYYY-MM-DD—

options 每一项:

json
{ "label": "显示名", "value": "实际值", "disabled": false }

value 只能是字符串、数字或布尔值。

password 不是加密

password 只做界面遮罩,保存后仍是明文存在安装配置里。绝对不要把 QQ AppSecret、平台账号密码这类平台级凭据放进插件配置。 第三方 API Token 也请按最小权限申请、支持随时重置。

四、字段属性参考 ​

属性类型说明
keystring必填。字母开头,2–64 位,可含字母数字和 . _ -;同一插件内不可重复
labelstring必填。显示名,最长 80 字
typestring必填。必须是上表 12 种之一,写错该字段会被整条丢弃
default与类型一致默认值;不写时 switch 为 false、number 为 min 或 0、多选为 []、其余为空字符串
requiredboolean必填;保存时为空会报「请填写「字段名」」
placeholderstring输入框占位文字,最长 200 字
hintstring字段下方灰色说明,最长 500 字
sectionstring分组标题,默认「基础配置」;相邻同名字段会归到同一张卡片
section_hintstring分组说明,只在该组第一个字段上写即可(也兼容 sectionHint)
width"full" | "half"桌面端整行或半行,默认 full
min maxnumber仅 number;保存时超出范围会被自动夹到边界值,不报错
stepnumber仅 number,必须大于 0
rowsnumber仅 textarea,2–12
show_whenobject条件显示,见下

条件显示 show_when ​

字段可以跟随另一个字段的取值显示或隐藏:

json
{
  "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 只影响界面显示,被隐藏的字段依然会按默认值保存(这也是"用户没填却拿到了值"的原因)。

五、一个像「群管家」那样的完整示例 ​

多分组、半宽排布、开关联动、多选,一份可直接改用:

json
{
  "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": "生效范围" }
  ]
}

对应运行时读取:

js
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;
  },
};

六、后端校验规则(精确行为) ​

保存时平台按顺序处理每个字段,理解它就不会踩坑:

类型处理方式
switchtrue / 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 重新上传并升版本

八、版本与审核规则 ​

  1. 修改 settings_schema 必须提升版本号重新提交审核。
  2. 审核通过前,已安装用户仍看到并使用旧版本的配置结构。
  3. 升级插件不会清空用户已有配置;新增字段用 default 自动补齐。
  4. 删除字段后,该字段不再出现在用户配置里,也不会进入 ctx.settings。
  5. 用户可以在配置页点「恢复默认」,只重置当前机器人上的这份配置。
  6. 付费插件、作者本人安装同样走这套校验,没有例外。

九、发布前自检清单 ​

  • [ ] settings_schema 在 plugin.json 里,不是 index.js
  • [ ] 打包成 .wwp 上传,不是单文件 .js
  • [ ] 每个字段的 key 唯一、字母开头、2–64 位
  • [ ] select / checkbox-group 都写了 options,且 default 能在 options 里找到
  • [ ] 必填字段都有合理默认值,避免用户第一次打开就保存失败
  • [ ] 代码里读了 ctx.settings 的字段名与 schema 完全一致(大小写敏感)
  • [ ] 没有把平台级密钥放进配置,敏感信息提示用户用 password
  • [ ] 升了版本号,changelog 写清这次改了哪些配置项

十、延伸阅读 ​

需要编辑器类型提示可下载 SDK 声明:weiwei-plugin-sdk.d.ts。

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