示例：一个可配置的任务

本示例把清单、运行机制、界面、基础库与命令串起来，写一个「自动使用物品」任务：

• 界面可配置：是否启用、要使用的物品列表；
• 通过子表单从背包里勾选物品；
• 任务按配置循环使用物品。

目录结构

apps/黑猫@自动使用物品/
├── .hm.json
├── index.lua
└── ui/
    ├── index.lua
    ├── main.lua
    └── form_select_item.lua

1. 清单

apps/黑猫@自动使用物品/.hm.json

{
  "名称": "自动使用物品",
  "作者": "黑猫",
  "类型": "任务",
  "版本": "v1.0",
  "简介": "按配置循环使用背包物品",
  "仓库地址": "",
  "依赖软件包": {
    "黑猫@基础库": "v1.0"
  }
}

2. 界面注册

apps/黑猫@自动使用物品/ui/index.lua

local main = require("ui.main")
local selectItem = require("ui.form_select_item")

function Init()
  RegisterForm("main", main)
  RegisterForm("selectItem", selectItem)
end

3. 主表单

apps/黑猫@自动使用物品/ui/main.lua

local main = {}

function main.uiSchema(form)
  return {
    type = "table",
    children = {
      {
        type = "checkbox",
        field = "autoUse",
        label = "启用自动使用",
        default = false,
      },
      {
        type = "button",
        label = "添加物品",
        event = "addItem",
        class = "my-2",
        click = function(f)
          -- 打开子表单选择物品
          PushCommand(nil, "openForm", {
            formName = "selectItem",
            title = "选择要使用的物品",
          })
        end,
      },
      {
        type = "list",
        label = "待使用物品",
        field = "useItems",
        titleKey = "label",
        deleteEnable = true,
        height = 200,
        default = {},
      },
    },
  }
end

function main.validateForm(form)
  if form.autoUse and #(form.useItems or {}) == 0 then
    return "启用后请至少添加一个物品"
  end
  return nil
end

return main

4. 子表单

apps/黑猫@自动使用物品/ui/form_select_item.lua

local hmPackage = require("黑猫@基础库.package")

local selectItem = {}

function selectItem.uiSchema()
  -- 取背包里所有物品名称并去重
  local names = hmPackage.getUniqueNamesFromArray(hmPackage.getList(nil))
  local options = {}
  for _, name in ipairs(names) do
    table.insert(options, { label = name, value = name })
  end

  return {
    type = "table",
    children = {
      {
        type = "checkboxSelectList",
        field = "selectedItems",
        options = options,
        height = 300,
      },
    },
  }
end

function selectItem.validateForm(form)
  if #(form.selectedItems or {}) == 0 then
    return "请选择物品"
  end
  return nil
end

function selectItem.submitForm(form)
  -- 把选中的物品推送到主表单的 useItems 列表
  local items = {}
  for _, name in ipairs(form.selectedItems) do
    table.insert(items, { label = name })
  end
  PushCommand("useItems", "addItems", items)
  return nil
end

return selectItem

5. 任务入口

apps/黑猫@自动使用物品/index.lua

local hmPackage = require("黑猫@基础库.package")

-- 每 1 秒检查一次
CheckTime = 1000

function Check()
  -- 未启用时返回 0，继续等待
  if CurrentSettings.autoUse then
    return 1
  end
  return 0
end

function Main()
  local settings = CurrentSettings
  local items = settings.useItems or {}

  for _, item in ipairs(items) do
    local name = item.label
    if hmPackage.isItemExists(name) then
      local pos = hmPackage.getIndexFromArray(hmPackage.getList(nil), name)
      if pos >= 0 then
        hmPackage.useItem(pos)
        GoPrint("已使用：" .. name)
        Delay(500)
      end
    else
      GoPrint("背包中没有：" .. name)
    end
  end
end

关键点回顾

• 清单声明了 类型 为任务、依赖基础库。
• 主表单的 提交 会校验并保存配置，任务启动后通过 CurrentSettings 读取。
• 子表单通过 PushCommand(nil, "openForm", ...) 打开；确认时执行 submitForm， 再用 PushCommand("useItems", "addItems", ...) 把结果推回主表单的列表。
• Check / Main 分工明确：Check 判断是否启用，Main 执行使用逻辑。
• #(form.useItems or {}) 的写法可避免字段为 nil 时报错。

下一步：示例：编写一个函数库。