界面（表单）概览

任务可以在 ui/ 目录中定义配置界面。界面完全用声明式的表单 schema 描述，你不需要写任何前端代码。

目录与入口

apps/黑猫@我的任务/
└── ui/
    ├── index.lua        # 注册表单
    ├── main.lua         # 主表单模块
    └── form_xxx.lua     # 子表单模块（可选）

ui/index.lua 是界面的入口。它需要定义一个全局函数 Init()，在其中调用 RegisterForm(name, module) 注册各个表单：

apps/黑猫@我的任务/ui/index.lua
local main = require("ui.main")

function Init()
  -- 名为 "main" 的表单就是任务面板上的主配置表单
  RegisterForm("main", main)
end

提示

若 ui/ 下没有 index.lua，助手会回退为「加载目录下所有 .lua」的旧方式。新软件包请统一使用 index.lua + Init()。

表单模块

注册的表单模块是一个 Lua table，可以包含三个函数：

成员	是否必需	说明
`uiSchema(form)`	必需	返回界面的 schema（一个 table）
`validateForm(form)`	可选	校验表单，返回 `nil` 表示通过，返回字符串表示错误信息
`submitForm(form, userArgs)`	可选	提交表单时执行（主要用于子表单）

apps/黑猫@我的任务/ui/main.lua
local main = {}

function main.uiSchema(form)
  return {
    type = "table",
    children = {
      { type = "input", field = "title", label = "任务名称" },
      { type = "number", field = "retry", label = "重试次数", default = 0 },
    },
  }
end

function main.validateForm(form)
  if form.title == nil or form.title == "" then
    return "任务名称不能为空"
  end
  return nil
end

return main

界面如何工作

当你选中一个任务时，前端会与助手的 UI 服务交互：

前端                                      UI 服务（每个任务一份 Lua 环境）
 │  getUISettings  ─────────────────────────▶  取配置：主表单优先读已保存配置，否则取默认值
 │  getUISchema    ─────────────────────────▶  调用 uiSchema(form)，处理 visible/options 等
 │  callUIEvent    ─────────────────────────▶  触发按钮的 click 函数
 │  validateForm   ─────────────────────────▶  调用 validateForm / 字段校验
 │  formSubmit     ─────────────────────────▶  调用 submitForm（子表单）
 │  setUISettings  ─────────────────────────▶  校验并保存主表单配置

面板上的按钮对应这些操作：

按钮	行为
提交	校验主表单并保存配置（`setUISettings`）
启动 / 停止	启动或停止该任务
重载	重新加载 UI 服务（`reloadUIService`），用于调试改动的 Lua
刷新	重新拉取 schema
取值	重新拉取当前表单的值

动态表单

uiSchema(form) 会在每次表单值变化时被调用（前端会带上当前表单值），因此你可以根据已填内容动态生成界面：

用 visible 控制显隐；
用 options 动态生成下拉选项；
用 default 提供默认值（可以是函数）。

function main.uiSchema(form)
  return {
    type = "table",
    children = {
      { type = "checkbox", field = "enableAdvance", label = "高级设置" },
      {
        type = "input",
        field = "advDesc",
        label = "高级说明",
        -- 只有勾选「高级设置」时才显示
        visible = function(f) return f.enableAdvance == true end,
      },
    },
  }
end

按钮通过 event 与 click 绑定，点击时执行 click(form)；在其中可以调用 PushCommand 打开子表单或向前端推送数据。详见事件与命令。

下一步：表单 schema 组件。

目录与入口​

表单模块​

界面如何工作​

动态表单​

目录与入口

表单模块

界面如何工作

动态表单