表单 schema 组件

uiSchema(form) 返回一个 schema table，描述界面的布局与字段。前端会把它渲染成 Vuetify 组件。

通用字段

所有组件都支持以下字段：

字段	类型	说明
`type`	string	组件类型，见下表
`label`	string	显示文本
`field`	string	绑定到表单数据的字段名（表单值以它为键）
`default`	any \| function	默认值；可以是函数，`default()` 的返回值作为默认值
`visible`	boolean \| function	是否显示；函数形式为 `visible(form)`
`enable`	boolean \| function	是否可用；函数形式为 `enable(form)`
`class`	string	附加到组件的 CSS 类
`props`	table	透传给底层 Vuetify 组件的属性

备注

visible 与 enable 若为函数，会在框架处理 schema 时以当前表单值调用，转换为布尔值。

组件类型一览

`type`	用途
`table`	纵向容器
`flex`	弹性布局容器
`group`	可折叠分组
`text`	纯文本
`input`	单行文本输入
`number`	数字输入
`select`	下拉选择
`autocomplete`	自动补全输入
`combobox`	可输入的下拉
`checkbox`	复选框
`radio`	单选
`list`	列表（只读展示 + 删除）
`checkboxSelectList`	多选列表
`tableData`	表格数据
`button`	按钮

table

纵向容器，把子组件从上到下排列。

字段	说明
`children`	子组件数组

{ type = "table", children = {
  { type = "input", field = "a", label = "字段 A" },
  { type = "input", field = "b", label = "字段 B" },
} }

flex

弹性布局容器，适合横向排列多个组件。

字段	类型	说明
`direction`	`"row"` \| `"column"`	排列方向，默认 `row`
`wrap`	boolean	是否换行
`gap`	number	间距（像素）
`children`	array	子组件数组

flex 的子组件还可以设置布局尺寸：

字段	类型	说明
`width`	number \| string	固定宽度（同时设置 min/max）
`height`	number \| string	固定高度
`flex`	number	弹性比例

{ type = "flex", direction = "row", wrap = true, gap = 8, children = {
  { type = "checkbox", field = "f1", label = "F1", width = 50, default = false },
  { type = "checkbox", field = "f2", label = "F2", width = 50, default = false },
} }

备注

schema 类型中还声明了 cols、align、justify 等布局提示，当前渲染层暂未使用，可留待后续扩展。

group

可折叠分组，content 中放单个子组件。

字段	说明
`label`	分组标题
`content`	单个子组件

{ type = "group", label = "高级设置", content = {
  type = "flex", direction = "column", children = {
    { type = "checkbox", field = "debug", label = "调试模式" },
  },
} }

text

纯文本展示。

字段	类型	说明
`label`	string	文本内容
`fontSize`	number	字号（像素）

{ type = "text", label = "请先选择挂机点", fontSize = 13 }

input

单行文本输入。

{ type = "input", field = "title", label = "任务名称", default = "" }

number

数字输入。

字段	类型	说明
`controlVariant`	string	控件样式：`"default"`、`"split"`、`"hidden"`、`"stacked"`，默认 `"hidden"`

{ type = "number", field = "retry", label = "重试次数", default = 0 }

select / autocomplete / combobox

三种选择型输入，均需提供 options。

字段	类型	说明
`options`	array \| function	选项数组，或返回选项数组的函数 `options(form)`
`clearable`	boolean	是否可清空

选项格式为 { label = ..., value = ... } 的数组。

{ type = "radio", field = "mode", label = "模式", options = {
  { label = "打死换怪", value = "打死换怪" },
  { label = "打红换怪", value = "打红换怪" },
}, default = "打死换怪" }

动态选项（根据当前表单值生成）：

{ type = "select", field = "scene", label = "场景",
  options = function(form)
    local list = {}
    for _, v in ipairs(getScenes()) do
      table.insert(list, { label = v.name, value = v.id })
    end
    return list
  end,
}

checkbox

复选框。

{ type = "checkbox", field = "enable", label = "启用", default = false }

radio

单选，需要 options。

{ type = "radio", field = "mode", label = "模式", options = {
  { label = "模式一", value = 1 },
  { label = "模式二", value = 2 },
} }

list

只读列表，用于展示已经添加的条目，支持删除。常与 PushCommand 的 addItems 搭配。

字段	类型	说明
`field`	string	绑定的字段（数组）
`titleKey`	string	每行取哪个键显示，默认 `label`
`height`	number \| string	列表高度
`deleteEnable`	boolean	是否显示删除按钮，默认显示

{ type = "list", field = "points", label = "挂机点列表",
  deleteEnable = true, height = 200, default = {} }

checkboxSelectList

多选列表，用于从候选项中勾选若干项。

字段	类型	说明
`field`	string	绑定的字段（选中值数组）
`options`	array \| function	候选项 `{ label, value }`
`height`	number \| string	列表高度

{ type = "checkboxSelectList", field = "selectedItems", options = itemOptions }

tableData

表格数据，按列展示数组，支持删除。常与 PushCommand 的 addRow 搭配。

字段	类型	说明
`field`	string	绑定的字段（行数组）
`columns`	array	列定义 `{ title, key }`
`height`	number \| string	表格高度
`fixedHeader`	boolean	固定表头
`deleteEnable`	boolean	是否显示删除列

{ type = "tableData", field = "rows", height = 240, deleteEnable = true,
  columns = {
    { title = "名称", key = "name" },
    { title = "数量", key = "count" },
  },
}

button

点击按钮，通过 event 与 click 绑定行为。

字段	类型	说明
`label`	string	按钮文本
`event`	string	事件名（需唯一）
`click`	function	点击回调 `click(form)`
`loadingBindTask`	string	若该任务正在运行，按钮显示 loading 状态
`class`	string	CSS 类

{ type = "button", label = "添加挂机点", event = "addPoint",
  click = function(form)
    local pos = hmPlayer.getCurrentPosition()
    PushCommand("points", "addItems", {
      { label = pos.sceneName .. "(" .. pos.x .. "," .. pos.y .. ")" },
    })
  end,
}

提示

click 函数在界面环境中执行，可以使用 PushCommand、AddTask 等界面专属函数。

完整示例

function main.uiSchema(form)
  local items = {}
  for _, name in ipairs(getItemNames()) do
    table.insert(items, { label = name, value = name })
  end

  return {
    type = "table",
    children = {
      { type = "flex", direction = "row", gap = 8, children = {
        { type = "checkbox", field = "enable", label = "启用", default = false },
        { type = "number", field = "count", label = "数量", default = 1, width = 120 },
      } },
      { type = "radio", field = "mode", label = "模式", default = 1, options = {
        { label = "模式一", value = 1 },
        { label = "模式二", value = 2 },
      } },
      { type = "checkboxSelectList", field = "selectedItems", label = "物品", options = items, height = 200 },
      { type = "button", label = "添加", event = "add", class = "mt-4",
        click = function(f)
          PushCommand(nil, "openForm", { formName = "select", title = "选择物品" })
        end,
      },
    },
  }
end

下一步：表单模块与生命周期。

通用字段​

组件类型一览​

table​

flex​

group​

text​

input​

number​

select / autocomplete / combobox​

checkbox​

radio​

list​

checkboxSelectList​

tableData​

button​

完整示例​