Web 扩展接口 web

lumen.web 让子插件能扩展 WebUI，提供三种能力：

1. 配置表单 createConfig

声明配置 Schema，WebUI 自动渲染表单；用户保存时触发 config.update.<name> 事件：

def on_load(lumen):
    builder = lumen.web.createConfig("我的插件配置")
    builder.text("welcome", "欢迎进服！", desc="进服欢迎语")
    builder.number("max_players", 20, desc="最大玩家数")
    builder.switch("enable_notify", True, desc="是否开启通知")
    builder.select("mode", "daily", ["daily", "weekly", "monthly"], desc="统计模式")
    builder.array("blacklist", [], desc="黑名单 QQ 列表")
    builder.textarea("rules", "规则1\n规则2", desc="规则列表，每行一条")
    builder.register()

    # 监听保存事件
    def on_config_update(key, value):
        lumen.logger.info(f"配置变更: {key} = {value}")
        lumen.storage.write("config.json", {key: value})  # 自行持久化
    lumen.on("config.update.我的插件配置", on_config_update)

字段类型：text / number / switch / select / array / textarea

2. 自定义 API registerApi

注册 REST 接口，路径前缀 /api/plugin/：

def on_load(lumen):
    # 注册 GET /api/plugin/my_plugin/status
    def handle_status(request):
        # request = {"query": dict, "body": Any, "path": str}
        return {"code": 200, "data": {"online": len(lumen.mc.online_players)}}
    lumen.web.registerApi("GET", "/status", handle_status, need_auth=True)

    # 注册 POST /api/plugin/my_plugin/kick
    def handle_kick(request):
        name = request["body"].get("name")
        lumen.mc.runcmd(f"kick {name}")
        return {"code": 200, "msg": f"已踢出 {name}"}
    lumen.web.registerApi("POST", "/kick", handle_kick, need_auth=True)

need_auth=True 时需带 Bearer Token；设为 False 可公开访问（慎用）。

3. 自定义页面 registerPage

挂载子插件目录内的静态 HTML 页面到 WebUI 侧边栏：

def on_load(lumen):
    # 挂载 assets/dashboard.html，侧边栏标题"我的面板"
    lumen.web.registerPage("我的面板", "assets/dashboard.html")

访问路径：/plugin-views/<子插件目录名>/assets/dashboard.html，URL 自动附带 ?token=<TOKEN> 供鉴权。

在移动端竖屏下，子插件注册的侧边栏按钮会自动收纳到底部「其它」弹层中，避免底栏溢出。

---