界面模块

导入UI库

导入UI构建库

lua

local ui = require("ui_builder")

功能：导入 ui_builder 库，返回一个包含UI创建和管理函数的表。

返回值：table，包含UI构建相关函数的表。

示例：

lua

local ui = require("ui_builder")
-- 现在可以使用 ui.createAlert(), ui.createSlider() 等函数

小白快速开始

如果你第一次使用动态 UI，可以先复制下面这份完整示例运行。它包含输入框、数字输入、下拉选择、开关、滑块、说明文字、布局分组和参数取值。

lua

local ui = require("ui_builder")

-- 1. 准备下拉选项
local modeItems = {
    { label = "自动", key = "auto", description = "按默认策略运行" },
    { label = "手动", key = "manual" },
    { label = "调试", key = "debug", isDisabled = true },
}

-- 2. 创建输入组件
local nameInput = ui.createInput("name", "名称", "请输入名称", "")
nameInput.Input.variant = "bordered"
nameInput.Input.layout = { span = 6 }

local countInput = ui.createNumberInput("count", 1, "数量", 0, 100, 1, "1~100")
countInput.NumberInput.variant = "bordered"
countInput.NumberInput.layout = { span = 6 }

local modeSelect = ui.createSelect("mode", "auto", "运行模式", modeItems)
modeSelect.Select.variant = "bordered"
modeSelect.Select.layout = { span = 6 }

local speedSlider = ui.createSlider("speed", 50, "速度", 0, 100, 1)
speedSlider.Slider.color = "primary"
speedSlider.Slider.showTooltip = true
speedSlider.Slider.layout = { span = 12 }

local enableSwitch = {
    Switch = {
        name = "enableFeature",
        title = "启用功能",
        isSelected = true,
        color = "primary",
        layout = { span = 6 },
    }
}

-- 3. 用 Group / Div / P 做布局和说明
local page = {
    Div = {
        className = "rounded-small border border-default-200 bg-default-50 p-4",
        item = {
            {
                {
                    P = {
                        text = "这是一个可以直接复制运行的动态 UI 示例。",
                        className = "text-sm text-default-500 mb-2",
                        layout = { span = 12 },
                    }
                }
            },
            {
                {
                    Group = {
                        title = "基础参数",
                        description = "Group / Div / P 只负责布局和展示，不会影响取值。",
                        direction = "grid",
                        columns = 12,
                        gap = 4,
                        item = {
                            { nameInput, countInput },
                            { modeSelect, enableSwitch },
                            { speedSlider },
                        }
                    }
                }
            }
        }
    }
}

-- 4. 构建并显示 UI
-- 第二个参数 1 表示更新界面时尽量保留用户已经改过的值
ui.buildUI({ page }, 1)
StartUI()

-- 5. 用户修改任意参数时，会触发这个函数
-- values 是当前 UI 的完整参数表。
-- 用户修改任意输入组件时，这里都可以读取所有输入组件的当前值。
function onUIChanged(values)
    if values.name ~= nil then
        print("名称变化:", values.name)
    end

    if values.count ~= nil then
        print("数量变化:", values.count)
    end

    if values.mode ~= nil then
        print("运行模式变化:", values.mode)
    end

    if values.enableFeature ~= nil then
        print("启用功能变化:", values.enableFeature)
    end

    if values.speed ~= nil then
        print("速度变化:", values.speed)
    end

    -- 如果你要读取全部当前值，请用 UICurrentValue
    print("当前名称:", UICurrentValue.name)
    print("当前数量:", UICurrentValue.count)
    print("当前运行模式:", UICurrentValue.mode)
    print("当前启用功能:", UICurrentValue.enableFeature)
    print("当前速度:", UICurrentValue.speed)
end

-- 6. 也可以在其它地方主动读取当前值
function printCurrentValues()
    print("当前名称:", UICurrentValue.name)
    print("当前速度:", UICurrentValue.speed)

    if UICurrentValue.enableFeature then
        print("功能已启用")
    else
        print("功能未启用")
    end
end

这份示例里最重要的规则：

nameInput 的 key 是 "name"，所以变化回调里用 values.name，主动读取用 UICurrentValue.name。
countInput 的 key 是 "count"，所以变化回调里用 values.count，主动读取用 UICurrentValue.count。
Switch 里写的是 name = "enableFeature"，所以变化回调里用 values.enableFeature。
onUIChanged(values) 收到的是当前 UI 的完整参数表，不是单个变化字段。
在回调内可以用 values.xxx 读取完整当前值；在回调外、循环或其它函数中使用 UICurrentValue.xxx。
Div、Group、P 只是布局/说明组件，不会产生值。
layout.span = 6 表示半行，两个 span = 6 的组件会显示在同一行。
layout.span = 12 表示占满一整行。

动态 UI 开发者速查

本节用于快速确认前端动态渲染当前支持哪些组件、哪些组件会产生值、默认值字段怎么写，以及布局字段怎么使用。

当前前端动态渲染支持以下组件：

组件	类型	是否产生值	默认值字段	说明
`Alert`	展示型	否	-	提示信息
`Slider`	输入型	是	`defaultValue`	滑块，支持单值或范围值
`Select`	输入型	是	`defaultSelectedKeys`	下拉选择，支持单选或多选
`Autocomplete`	输入型	是	`defaultSelectedKey`	可搜索的单选选择框
`CheckboxGroup`	输入型	是	`defaultValue`	多选复选框组
`Checkbox`	输入型	是	`defaultSelected`	单个复选框
`Switch`	输入型	是	`isSelected`	开关
`RadioGroup`	输入型	是	`defaultValue`	单选按钮组
`Input`	输入型	是	`defaultValue`	单行文本输入
`NumberInput`	输入型	是	`defaultValue`	数字输入
`Chip`	展示型	否	-	标签/状态
`Divider`	展示型	否	-	分割线
`Image`	展示型	否	-	图片
`P`	展示型	否	-	文本段落
`Div`	布局型	否	-	通用布局容器
`Group`	布局型	否	-	纯布局/分组容器
`Tabs`	容器型	否	-	标签页容器
`Accordion`	容器型	否	-	手风琴容器

节点结构规则：

每个动态 UI 节点都是一个只有一个组件名键的 table：

lua

{
    Input = {
        name = "username",
        label = "用户名",
        defaultValue = "",
    }
}

对应 JSON 结构为：

json

{
  "Input": {
    "name": "username",
    "label": "用户名",
    "defaultValue": ""
  }
}

如果组件已经有 ui.createXxx(...) 生成器函数，优先使用生成器函数；如果生成器暂时没有封装，例如 Switch、Autocomplete，可以直接手写节点表。

值回传规则：

输入型组件必须设置 name。name 是该组件在 UICurrentValue 和 onUIChanged(values) 中的字段名。

lua

function onUIChanged(values)
    print(values.username)
    print(values.enableFeature)
end

展示型组件和容器型组件不会产生业务值：

展示型：Alert、Chip、Divider、Image、P
布局型：Div、Group
容器型：Tabs、Accordion

默认值字段规则：

组件	推荐默认值字段	值类型
`Slider`	`defaultValue`	`number` 或 `{number, number}`
`Select`	`defaultSelectedKeys`	`string`、逗号分隔字符串或字符串数组
`Autocomplete`	`defaultSelectedKey`	`string`
`CheckboxGroup`	`defaultValue`	字符串数组
`Checkbox`	`defaultSelected`	`boolean`
`Switch`	`isSelected`	`boolean`
`RadioGroup`	`defaultValue`	`string`
`Input`	`defaultValue`	`string`
`NumberInput`	`defaultValue`	`number`

Autocomplete 为兼容旧写法，同时兼容 defaultSelectedKeys 和 defaultValue，但推荐新代码使用 defaultSelectedKey。

选项结构规则：

Select、Autocomplete、CheckboxGroup、RadioGroup 都使用相同的 items 结构：

lua

items = {
    { label = "自动", key = "auto", description = "按默认策略运行" },
    { label = "手动", key = "manual" },
    { label = "调试", key = "debug", isDisabled = true },
}

label：显示文本。
key：实际值。
description：选项说明，部分组件会展示。
isDisabled：禁用该选项。

布局规则：

默认情况下，旧 UI 仍然保持从上到下垂直排列。

如果同一个分组内任意节点设置了 layout.span 或 layout.mode = "row"，该分组会启用 12 栅格布局。

lua

local nameInput = ui.createInput("name", "名称", "请输入名称", "")
nameInput.Input.layout = { span = 6 }

local countInput = ui.createNumberInput("count", 1, "数量", 0, 100, 1, "1~100")
countInput.NumberInput.layout = { span = 6 }

常用 span：

`span`	效果
`12`	占满一整行
`6`	半行，两个组件一行
`4`	三分之一行，三个组件一行
`3`	四分之一行，四个组件一行

属性透传规则：

大多数组件可以继续补充 HeroUI 支持的属性，例如：

lua

local input = ui.createInput("name", "名称", "请输入", "")
input.Input.variant = "bordered"
input.Input.color = "primary"
input.Input.size = "sm"
input.Input.isDisabled = false
input.Input.layout = { span = 6 }

常用透传属性：

size："sm"、"md"、"lg"。
radius："none"、"sm"、"md"、"lg"、"full"。
variant：例如 "flat"、"bordered"、"faded"、"underlined"。
color："default"、"primary"、"secondary"、"success"、"warning"、"danger"。
isDisabled：是否禁用。
isReadOnly：是否只读，主要用于输入类组件。
isRequired：是否必填，主要用于输入类组件。
className：追加前端样式类名。

内部保留字段：

items：选项或容器项数据，前端内部使用。
layout：布局数据，前端内部使用。
item：Div / Group / Tabs / Accordion 子项内容，前端内部使用。

不建议给事件类属性传字符串函数，例如 onClick、onChange。动态 UI 的交互统一通过 onUIChanged(values) 或运行页已有通信机制处理。

UI 参数取值说明

本节只讲一件事：用户在界面上改了参数后，Lua 代码怎么拿到这些值。

最重要的规则：

输入型组件必须有一个取值名字。通过 ui.createXxx(...) 创建的组件，第一个参数通常就是取值名字；手写节点时使用 name 字段。

lua

-- 这个输入框的取值名字是 name
local input = ui.createInput("name", "名称", "请输入名称", "")

-- 这个开关的取值名字是 enableFeature
local switch = {
    Switch = {
        name = "enableFeature",
        title = "启用功能",
        isSelected = true
    }
}

取值时就用：

lua

print(values.name)
print(values.enableFeature)
print(UICurrentValue.name)
print(UICurrentValue.enableFeature)

两种取值方式：

方式	什么时候用	示例
`onUIChanged(values)`	用户修改 UI 时自动触发	读取当前 UI 的完整参数表
`UICurrentValue.xxx`	在脚本其它地方主动读取当前值	运行逻辑中读取最新参数

方式一：监听用户修改：

lua

function onUIChanged(values)
    -- values 是当前 UI 的完整参数表
    if values.name ~= nil then
        print("名称变化:", values.name)
    end

    if values.speed ~= nil then
        print("速度变化:", values.speed)
    end

    if values.enableFeature ~= nil then
        print("是否启用变化:", values.enableFeature)
    end
end

只要用户改了输入框、滑块、下拉框、开关等参数，就会触发 onUIChanged(values)。

values 是当前 UI 的完整参数表，不是单个变化字段。回调内可以直接读取任意输入组件的当前值，例如 values.name、values.speed。回调外、主循环或其它函数中主动读取时使用 UICurrentValue.xxx。

方式二：主动读取当前值：

lua

function runTask()
    local name = UICurrentValue.name or ""
    local speed = UICurrentValue.speed or 50
    local enabled = UICurrentValue.enableFeature == true

    print("开始运行:", name, speed, enabled)
end

UICurrentValue 是当前 UI 的所有参数值表。通常在 StartUI() 之后使用。

各组件取值类型：

组件	创建/默认值字段	取值示例	返回值类型
`Input`	`defaultValue`	`values.name`	字符串
`NumberInput`	`defaultValue`	`values.count`	数字
`Slider`	`defaultValue`	`values.speed`	数字或数字数组
`Select` 单选	`defaultSelectedKeys`	`values.mode`	字符串
`Select` 多选	`defaultSelectedKeys`	`values.tags`	逗号分隔字符串
`Autocomplete`	`defaultSelectedKey`	`values.project`	字符串或 `nil`
`Checkbox`	`defaultSelected`	`values.enableLog`	布尔值
`Switch`	`isSelected`	`values.enableFeature`	布尔值
`CheckboxGroup`	`defaultValue`	`values.fruits`	字符串数组
`RadioGroup`	`defaultValue`	`values.priority`	字符串

展示/布局/容器组件没有值：

这些组件只是用来显示内容或组织布局，它们自身不会出现在 values 和 UICurrentValue 里：

Alert
Chip
Divider
Image
P
Div
Group
Tabs
Accordion

例如：

lua

local box = {
    Div = {
        item = {
            {
                {
                    P = {
                        text = "说明文字"
                    }
                }
            },
            {
                ui.createInput("username", "用户名", "请输入", "")
            }
        }
    }
}

function onUIChanged(values)
    print(values.username) -- username 变化时可以取到
    print(values.Div)      -- nil，Div 没有值
    print(values.P)        -- nil，P 没有值
end

嵌套组件怎么取值：

组件放在 Tabs、Accordion、Group、Div 里面也不影响取值。Div、Group、P 自身没有值，但它们内部的输入组件只要设置了 name，就会正常进入 values 和 UICurrentValue。

lua

local input = ui.createInput("nickname", "昵称", "请输入昵称", "")

local tab = ui.createTabs({
    ui.createTab("基础设置", {
        { input }
    })
}, "top", true)

function onUIChanged(values)
    if values.nickname ~= nil then
        print(values.nickname)
    end
end

多选值怎么处理：

CheckboxGroup 返回字符串数组：

lua

local fruits = values.fruits or {}
for index, fruit in ipairs(fruits) do
    print(index, fruit)
end

Select 多选当前返回逗号分隔字符串，例如 "auto,manual"。如果要拆开，可以这样写：

lua

function splitText(text, separator)
    local result = {}
    if text == nil or text == "" then
        return result
    end

    for value in string.gmatch(text, "([^" .. separator .. "]+)") do
        table.insert(result, value)
    end

    return result
end

function onUIChanged(values)
    local selectedModes = splitText(values.multiMode, ",")
    for index, mode in ipairs(selectedModes) do
        print(index, mode)
    end
end

常见错误：

问题	原因	解决
`values.xxx` 是 `nil`	组件没有设置对应的 `name` / key	检查 `ui.createXxx("xxx", ...)` 的第一个参数
`Div` / `Group` 取不到值	它们本身就是布局组件，不产生业务值	读取它们内部输入组件的值，内部输入组件会正常进入 `values` 和 `UICurrentValue`
`UICurrentValue` 是空的	UI 还没启动	先调用 `ui.buildUI(...)`，再调用 `StartUI()`
多选 Select 不是数组	当前返回逗号字符串	用字符串拆分，或改用 `CheckboxGroup`
修改默认值后界面没变	`buildUI(..., 1)` 会保留旧值	临时使用 `buildUI(..., 0)` 强制覆盖
点击保存后日志还是旧值	保存配置会写入 `ui.json`，不会重新执行当前 Lua 初始化代码	停止脚本后重新运行，再验证初始化值

创建提示框

创建一个用于显示提示信息的UI元素

lua

ui.createAlert("鼓励大家使用新功能", "新功能已经上线，欢迎大家使用！", "success")

功能：创建一个用于在UI界面顶部显示消息的提示框。

参数：

title：字符串，提示框的标题。
content：字符串，提示框显示的内容。
type：字符串（可选），提示框的类型，影响其外观。可选值包括："success", "info", "warning", "error"。默认值为 "info"。

返回值：table，Alert元素配置表，用于 buildUI 函数。

示例：

lua

local successAlert = ui.createAlert("操作成功", "您的设置已保存。", "success")
local warningAlert = ui.createAlert("注意", "请检查网络连接。", "warning")

创建滑块

创建一个用于调整数值范围的滑块。支持单值和范围值。

lua

ui.createSlider("speed", 0.3, "速度", 0, 1, 0.1)
ui.createSlider("interval", {65, 50}, "间隔", 0, 100) -- 范围值示例

功能：创建一个滑块UI元素，用于用户调整单个数值或一个数值范围。

参数：

key：字符串，该滑块的唯一标识符，用于在 onUIChanged 或 UICurrentValue 中获取其值。
defaultValue：数字或 table。
- 如果是数字，表示单值滑块的初始值。
- 如果是 table，例如 {start, end}，表示范围滑块的初始范围。
label：字符串，滑块旁边显示的文本标签。
min：数字，滑块可设置的最小值。
max：数字，滑块可设置的最大值。
step：数字（可选），滑块每次调整的最小步长。默认为1。

返回值：table，Slider元素配置表，用于 buildUI 函数。

示例：

lua

-- 创建一个单值滑块，默认值0.5，范围0到1，步长0.1
local volumeSlider = ui.createSlider("volume", 0.5, "音量", 0, 1, 0.1)

-- 创建一个范围滑块，默认范围10到90，范围0到100
local timeRangeSlider = ui.createSlider("timeRange", {10, 90}, "时间范围", 0, 100)

创建选择框

创建一个下拉选择器或多选器。

lua

-- 创建单选下拉选择器
ui.createSelect("Teammembers", "2000", "组员业绩", {
    {label = "小白", key = "2000"},
    {label = "小周", key = "3000"},
    {label = "小李", key = "4000"}
})

-- 创建多选下拉选择器
-- mode = "multiple"
-- 多选选择器默认值为 逗号 , 分隔 是一个文本值
ui.createSelect("promote", "4000,3000", "提拔", {
    {label = "小李", key = "4000"},
    {label = "小周", key = "3000"}
}, "multiple")

功能：创建一个下拉选择器（单选）或多选器（多选），允许用户从预定义选项中选择一个或多个值。

参数：

key：字符串，该选择框的唯一标识符。
defaultValue：字符串
- 如果是单选，表示单选模式下默认选中的选项的 "key"。
- 如果是多选，例如 "key1,key2"，表示多选模式下默认选中的选项的 key 数组。
label：字符串，选择框旁边显示的文本标签。
options：table，包含所有可选项目的数组。每个项目是一个 table，包含 label（显示文本）和 key（实际值）。
mode：字符串（可选）。如果设置为 "multiple"，则为多选模式；否则为单选模式。

返回值：table，Select元素配置表，用于 buildUI 函数。

示例：

lua

-- 单选模式
local colorSelect = ui.createSelect("favColor", "blue", "选择颜色", {
    {label = "红色", key = "red"},
    {label = "绿色", key = "green"},
    {label = "蓝色", key = "blue"}
})

-- 多选模式 (注意：demo 脚本中使用了布尔值 true 表示多选，但推荐使用字符串 "multiple" 以明确语义)
local fruitSelect = ui.createSelect("favFruits", {"apple", "banana"}, "选择水果", {
    {label = "苹果", key = "apple"},
    {label = "香蕉", key = "banana"},
    {label = "橘子", key = "orange"}
}, "multiple")

创建自动完成选择框

创建一个可输入搜索的单选选择框，适合选项较多的场景。

当前前端已经支持 Autocomplete 动态节点。如果 ui_builder 暂时没有封装 ui.createAutocomplete(...)，可以直接手写节点表，不需要修改生成器。

lua

local projectSelect = {
    Autocomplete = {
        name = "project",
        label = "选择项目",
        placeholder = "输入关键字搜索",
        defaultSelectedKey = "hexide",
        variant = "bordered",
        items = {
            { label = "HexIDE", key = "hexide", description = "当前项目" },
            { label = "UITEST", key = "uitest" },
            { label = "旧项目", key = "legacy", isDisabled = true },
        },
        layout = { span = 6 },
    }
}

功能：创建一个带搜索能力的选择框。用户可以输入关键字过滤选项，并从列表中选择一个值。

参数/属性：

name：字符串，该自动完成选择框的唯一标识符，用于在 onUIChanged 或 UICurrentValue 中获取值。
label：字符串，组件标签。
placeholder：字符串（可选），输入框为空时显示的提示文本。
defaultSelectedKey：字符串（可选），默认选中的选项 key。
items：table，选项数组。每项至少包含 label 和 key。
variant：字符串（可选），常见值为 "flat"、"bordered"、"faded"、"underlined"。
color：字符串（可选），常见值为 "default"、"primary"、"secondary"、"success"、"warning"、"danger"。
isClearable：布尔值（可选），是否允许清空。
isDisabled：布尔值（可选），是否禁用。
layout：布局配置（可选），例如 { span = 6 } 表示在 12 栅格布局中占 6 格。

兼容默认值字段：

前端优先读取 defaultSelectedKey，同时兼容 defaultSelectedKeys 和 defaultValue。推荐新写法使用 defaultSelectedKey。

选项属性：

items 中每个选项除了 label 和 key，也可以补充 description、isDisabled 等属性。

返回值：table，Autocomplete元素配置表，用于 buildUI 函数。

示例：

lua

local userSelect = {
    Autocomplete = {
        name = "user",
        label = "选择用户",
        placeholder = "搜索用户",
        defaultSelectedKey = "u001",
        items = {
            { label = "张三", key = "u001", description = "管理员" },
            { label = "李四", key = "u002" },
            { label = "王五", key = "u003", isDisabled = true },
        },
        layout = { span = 12 },
    }
}

在回调中读取：

lua

function onUIChanged(values)
    print("当前选择用户:", values.user)
end

创建复选框组

创建一个可多选的复选框组。

lua

local fruitItems = {
    { key = "apple",  label = "苹果"  },
    { key = "banana", label = "香蕉" },
    { key = "orange", label = "橙子" },
}
ui.createCheckboxGroup("fruits", {"apple","orange"}, "喜欢的水果(可多选)", fruitItems)

功能：创建一个包含多个复选框的组，用户可以从中选择一个或多个选项。

参数：

key：字符串，该复选框组的唯一标识符。
defaultValues：table，一个包含默认选中选项的 key 字符串的数组。
label：字符串，复选框组的标题或描述。
options：table，包含所有可选项目的数组。每个项目是一个 table，包含 label（显示文本）和 key（实际值）。

返回值：table，CheckboxGroup元素配置表，用于 buildUI 函数。

可选属性补充：

ui.createCheckboxGroup(...) 返回的是一个普通 table，可以在创建后补充 HeroUI 支持的属性。

orientation：字符串，控制复选框排列方向。可选值：
- "vertical"：纵向排列，默认表现。
- "horizontal"：横向排列。

lua

local fruits = ui.createCheckboxGroup("fruits", {"apple"}, "选择水果", {
    { label = "苹果", key = "apple" },
    { label = "香蕉", key = "banana" },
    { label = "橙子", key = "orange" },
})

-- 横向排列
fruits.CheckboxGroup.orientation = "horizontal"

-- 可选：配合布局字段，让该复选框组占整行
fruits.CheckboxGroup.layout = { span = 12 }

示例：

lua

local hobbies = {
    { key = "reading", label = "阅读" },
    { key = "coding",  label = "编程" },
    { key = "gaming",  label = "游戏" },
}
local hobbyCheckbox = ui.createCheckboxGroup("myHobbies", {"reading", "gaming"}, "选择爱好", hobbies)

创建数字输入框

创建一个用于输入数字的文本框。

lua

ui.createNumberInput("numberInput", 6, "数字输入", 0, 100, 1, "0~100")

功能：创建一个文本输入框，专门用于接收数字输入，并可设置输入范围和步长。

参数：

key：字符串，该输入框的唯一标识符。
defaultValue：数字，输入框的初始默认值。
label：字符串，输入框旁边的文本标签。
min：数字，允许输入的最小值。
max：数字，允许输入的最大值。
step：数字，点击上下箭头时数字变化的步长。
placeholder：字符串（可选），输入框为空时显示的提示文本。

返回值：table，NumberInput元素配置表，用于 buildUI 函数。

示例：

lua

local quantityInput = ui.createNumberInput("quantity", 1, "数量", 1, 99, 1, "输入购买数量")
local dpiInput = ui.createNumberInput("dpi", 800, "DPI设置", 400, 3200, 100)

创建单个复选框

创建一个独立的复选框。

lua

ui.createCheckbox("singleCheck", "一个普通的 Checkbox", true)

功能：创建一个单独的复选框，用于表示一个布尔状态（选中/未选中）。

参数：

key：字符串，该复选框的唯一标识符。
label：字符串，复选框旁边显示的文本标签。
defaultValue：布尔值，复选框的初始选中状态（true为选中，false为未选中）。

返回值：table，Checkbox元素配置表，用于 buildUI 函数。

示例：

lua

local enableFeature = ui.createCheckbox("enableFeature", "启用高级功能", false)
local autoStart = ui.createCheckbox("autoStart", "开机自启动", true)

创建开关

创建一个开关控件，用于表示一个布尔状态。

当前前端已经支持 Switch 动态节点。如果 ui_builder 暂时没有封装 ui.createSwitch(...)，可以直接手写节点表，不需要修改生成器。

lua

local enableFeature = {
    Switch = {
        name = "enableFeature",
        title = "启用功能",
        isSelected = true,
        color = "primary",
        layout = { span = 6 },
    }
}

local debugMode = {
    Switch = {
        name = "debugMode",
        title = "调试模式",
        isSelected = false,
        color = "warning",
        layout = { span = 6 },
    }
}

功能：创建一个开关控件，用户可以在开启和关闭两个状态之间切换。

参数/属性：

name：字符串，该开关的唯一标识符，用于在 onUIChanged 或 UICurrentValue 中获取值。
title：字符串，开关旁边显示的文本。
isSelected：布尔值，开关初始状态。true 表示开启，false 表示关闭。
color：字符串（可选），颜色主题。常见值为 "default"、"primary"、"secondary"、"success"、"warning"、"danger"。
size：字符串（可选），常见值为 "sm"、"md"、"lg"。
isDisabled：布尔值（可选），是否禁用开关。
layout：布局配置（可选），例如 { span = 6 } 表示在 12 栅格布局中占 6 格。

返回值：table，Switch元素配置表，用于 buildUI 函数。

示例：

lua

local switchPanel = ui.createAccordion({
    ui.createTab("开关测试", {
        {
            {
                Switch = {
                    name = "enableFeature",
                    title = "启用功能",
                    isSelected = true,
                    color = "primary",
                    layout = { span = 6 },
                }
            },
            {
                Switch = {
                    name = "debugMode",
                    title = "调试模式",
                    isSelected = false,
                    color = "warning",
                    layout = { span = 6 },
                }
            }
        }
    })
})

在回调中读取：

lua

function onUIChanged(values)
    if values.enableFeature then
        print("启用功能已打开")
    end
end

创建单选框组

创建一个可单选的单选框组。

lua

local fruitItems = {
    { key = "apple",  label = "苹果"  },
    { key = "banana", label = "香蕉" },
    { key = "orange", label = "橙子" },
}
ui.createRadioGroup("favorite", "apple", "单选水果", fruitItems)

功能：创建一个包含多个单选按钮的组，用户只能从中选择一个选项。

参数：

key：字符串，该单选框组的唯一标识符。
defaultValue：字符串，默认选中选项的 key。
label：字符串，单选框组的标题或描述。
options：table，包含所有可选项目的数组。每个项目是一个 table，包含 label（显示文本）和 key（实际值）。

返回值：table，RadioGroup元素配置表，用于 buildUI 函数。

示例：

lua

local difficultyOptions = {
    { key = "easy",   label = "简单" },
    { key = "medium", label = "中等" },
    { key = "hard",   label = "困难" },
}
local gameDifficulty = ui.createRadioGroup("difficulty", "medium", "选择难度", difficultyOptions)

创建标签芯片

创建一个静态的标签或芯片。

lua

ui.createChip("Chip 标签", "primary", "dot")

功能：创建一个小型、静态的标签或“芯片”UI元素，通常用于显示简短信息、分类或状态。它不提供交互功能，仅用于展示。

参数：

label：字符串，芯片上显示的文本。
color：字符串（固定单选），芯片的颜色主题。必须为下面任意之一： default | primary | secondary | success | warning | danger
variant：字符串（固定单选），芯片的视觉样式。必须为下面任意之一： solid | bordered | light | flat | faded | shadow | dot

返回值：table，Chip元素配置表，用于 buildUI 函数。

示例：

lua

local statusChip = ui.createChip("在线", "success", "filled")
local categoryChip = ui.createChip("游戏", "info", "outlined")

创建布局分组

创建一个纯布局/装饰分组容器，用来组织内部组件，不会影响参数取值。

Group 是前端动态 UI 的布局组件。如果 ui_builder 暂时没有封装 ui.createGroup(...)，可以直接手写节点表，不需要修改生成器。

lua

local baseGroup = {
    Group = {
        title = "基础参数",
        description = "这些字段会正常进入 UICurrentValue，Group 本身不会产生值。",
        direction = "grid",
        columns = 12,
        gap = 4,
        item = {
            {
                ui.createInput("name", "名称", "请输入名称", ""),
                ui.createNumberInput("count", 1, "数量", 0, 100, 1, "1~100")
            }
        },
        layout = { span = 12 },
    }
}

功能：只负责布局和视觉分组，不产生业务值，不会写入 UICurrentValue。Group 内部的输入组件仍会正常参与 onUIChanged(values) 和 UICurrentValue。

参数/属性：

title：字符串（可选），分组标题。
description：字符串（可选），分组说明。
direction：字符串（可选），内部排列方式。
- "vertical"：竖向排列。
- "horizontal"：横向排列，自动换行。
- "grid"：栅格排列。
columns：数字（可选），direction = "grid" 时的列数，默认 12。
gap：数字（可选），内部间距，默认 4。单位按 Tailwind 间距习惯换算，4 约等于 1rem。
item：二维组件数组，写法与 ui.createTab(...) 的内容结构一致。
layout：布局配置（可选），用于控制 Group 本身在父级栅格中占几格。

direction = "grid" 时，子组件如果没有设置 layout.span，默认占 1 列；如果设置了 layout.span，则按指定列宽显示。旧 UI 和未使用 Group 的布局不受影响。

小白怎么选：

想要的效果	推荐写法
组件从上到下排列	`direction = "vertical"`
多个开关/复选框横着排	`direction = "horizontal"`
输入框左右分栏	`direction = "grid"`，并给子组件设置 `layout.span`
两个组件一行	父级 `columns = 12`，子组件各自 `layout.span = 6`
三个组件一行	父级 `columns = 12`，子组件各自 `layout.span = 4`
四个组件一行	父级 `columns = 12`，子组件各自 `layout.span = 3`

常用间距 gap：

`gap`	效果
`0`	没有间距
`2`	小间距
`4`	默认间距，最常用
`6`	较大间距
`8`	大间距

常用写法：两个输入框一行：

lua

local inputA = ui.createInput("firstName", "姓", "请输入", "")
inputA.Input.layout = { span = 6 }

local inputB = ui.createInput("lastName", "名", "请输入", "")
inputB.Input.layout = { span = 6 }

local twoColumnGroup = {
    Group = {
        title = "双列表单",
        direction = "grid",
        columns = 12,
        gap = 4,
        item = {
            { inputA, inputB }
        }
    }
}

常用写法：一组开关横向排列：

lua

local switchGroup = {
    Group = {
        title = "开关设置",
        direction = "horizontal",
        gap = 4,
        item = {
            {
                {
                    Switch = {
                        name = "enableA",
                        title = "功能 A",
                        isSelected = true
                    }
                },
                {
                    Switch = {
                        name = "enableB",
                        title = "功能 B",
                        isSelected = false
                    }
                }
            }
        }
    }
}

示例：竖向分组：

lua

local verticalGroup = {
    Group = {
        title = "竖向分组",
        direction = "vertical",
        item = {
            { ui.createInput("username", "用户名", "请输入", "") },
            { ui.createCheckbox("enableLog", "启用日志", true) },
        }
    }
}

示例：横向分组：

lua

local horizontalGroup = {
    Group = {
        title = "横向分组",
        direction = "horizontal",
        gap = 4,
        item = {
            {
                ui.createCheckbox("a", "选项 A", true),
                ui.createCheckbox("b", "选项 B", false),
                ui.createCheckbox("c", "选项 C", false),
            }
        }
    }
}

示例：栅格分组：

lua

local nameInput = ui.createInput("name", "名称", "请输入名称", "")
nameInput.Input.layout = { span = 6 }

local countInput = ui.createNumberInput("count", 1, "数量", 0, 100, 1, "1~100")
countInput.NumberInput.layout = { span = 6 }

local gridGroup = {
    Group = {
        title = "栅格分组",
        direction = "grid",
        columns = 12,
        item = {
            { nameInput, countInput }
        }
    }
}

取值说明：

lua

function onUIChanged(values)
    -- Group 本身没有值
    -- 这里只能拿到 Group 内部输入组件的值
    print(values.name)
    print(values.count)
end

创建通用容器

创建一个类似 HTML div 的通用布局容器，用于包裹内部组件，不会影响参数取值。

Div 是纯布局组件，不会写入 UICurrentValue。Div 内部的输入组件仍会正常参与取值。

lua

local box = {
    Div = {
        className = "rounded-small border border-default-200 p-4",
        item = {
            {
                {
                    P = {
                        text = "这一段是说明文本，不会产生参数值。",
                        className = "text-sm text-default-500"
                    }
                }
            },
            {
                ui.createInput("boxName", "名称", "请输入名称", "")
            }
        },
        layout = { span = 12 },
    }
}

功能：用于布局、包裹、添加样式，不产生业务值。

参数/属性：

className：字符串（可选），前端样式类名。
style：对象（可选），前端内联样式。
title：字符串（可选），容器标题。
description：字符串（可选），容器说明。
item：二维组件数组，内部子组件。
layout：布局配置（可选），用于控制 Div 本身在父级栅格中占几格。

小白怎么用 className：

className 可以理解为“外观样式”。不会写前端也没关系，直接复制下面这些组合即可。

想要的效果	`className` 写法
普通卡片边框	`"rounded-small border border-default-200 p-4"`
浅色背景区域	`"rounded-small bg-default-50 p-4"`
带边框和浅色背景	`"rounded-small border border-default-200 bg-default-50 p-4"`
内容之间竖向留空	`"flex flex-col gap-4"`
内容横向排列	`"flex flex-wrap items-start gap-4"`
占满宽度	`"w-full"`
居中内容	`"flex items-center justify-center"`

常用样式含义：

rounded-small：小圆角。
border：显示边框。
border-default-200：默认浅色边框。
bg-default-50：默认浅色背景。
p-4：内部留白。
gap-4：内部组件间距。
flex flex-col：内部从上到下排列。
flex flex-wrap：内部横向排列，空间不够时自动换行。

常用写法：说明卡片：

lua

local helpBox = {
    Div = {
        className = "rounded-small border border-default-200 bg-default-50 p-4",
        item = {
            {
                {
                    P = {
                        text = "这里是说明内容，可以放在表单上方。",
                        className = "text-sm text-default-600"
                    }
                }
            }
        }
    }
}

常用写法：卡片里放表单：

lua

local cardInput = ui.createInput("cardValue", "参数", "请输入", "")

local formCard = {
    Div = {
        title = "卡片标题",
        description = "这个容器只负责外观，里面的参数仍然正常取值。",
        className = "rounded-small border border-default-200 p-4",
        item = {
            { cardInput }
        }
    }
}

style 写法：

不熟悉前端时，优先使用 className。只有需要精确控制时再使用 style。

lua

local customBox = {
    Div = {
        style = {
            padding = "16px",
            border = "1px solid #ddd",
            borderRadius = "8px"
        },
        item = {
            {
                {
                    P = {
                        text = "这是用 style 写出来的容器。"
                    }
                }
            }
        }
    }
}

取值说明：

lua

function onUIChanged(values)
    -- Div 本身没有值
    print(values.boxName)
end

创建段落文本

创建一个类似 HTML p 的文本段落，用于显示说明文字，不会影响参数取值。

lua

local description = {
    P = {
        text = "这里可以写一段提示说明。",
        className = "text-sm text-default-500",
        layout = { span = 12 },
    }
}

功能：显示一段文本，不产生业务值。

参数/属性：

text：字符串，段落文本。推荐使用。
content：字符串，段落文本。兼容字段。
title：字符串，段落文本。兼容字段。
className：字符串（可选），前端样式类名。
style：对象（可选），前端内联样式。
layout：布局配置（可选），用于控制 P 本身在父级栅格中占几格。

小白怎么用 className：

想要的效果	`className` 写法
普通说明文字	`"text-sm text-default-500"`
稍微醒目的说明	`"text-sm text-default-700"`
小号辅助文字	`"text-xs text-default-500"`
成功提示文字	`"text-sm text-success"`
警告提示文字	`"text-sm text-warning"`
错误提示文字	`"text-sm text-danger"`
居中文本	`"text-center"`
加粗文本	`"font-medium"`
顶部留一点距离	`"mt-2"`
底部留一点距离	`"mb-2"`

常用样式含义：

text-xs：很小的文字。
text-sm：小号文字，适合说明。
text-default-500：浅灰文字。
text-default-700：较深文字。
text-success：成功色。
text-warning：警告色。
text-danger：危险/错误色。
font-medium：文字加粗一点。

常用写法：表单说明：

lua

local tip = {
    P = {
        text = "请先填写基础参数，再点击运行。",
        className = "text-sm text-default-500 mb-2"
    }
}

常用写法：警告说明：

lua

local warningText = {
    P = {
        text = "注意：调试模式会输出更多日志。",
        className = "text-sm text-warning font-medium"
    }
}

常用写法：配合栅格占满一行：

lua

local fullLineText = {
    P = {
        text = "这段文字占满整行。",
        className = "text-sm text-default-500",
        layout = { span = 12 }
    }
}

创建手风琴折叠面板组

创建一个包含多个可折叠面板的UI分组。

lua

local page1 = {
    ui.createAlert("UI 全组件演示", "左侧是交互组件，右侧实时打印变化"),
    ui.createSlider("speed", 30, "速度(0~100)", 0, 100, 1),
}
local page2 = {
    ui.createAlert("套娃演示", "ABC"),
    ui.createNumberInput("numberInput", 6, "数字输入", 0, 100, 1, "0~100"),
}

ui.createAccordion {
    ui.createTab("第一页", page1),
    ui.createTab("其它页", page2),
}

功能：创建一个手风琴式的可折叠面板组。每个面板由一个 ui.createTab 定义，点击面板标题可以展开或折叠其内容。

参数：

tabs：table，一个包含由 ui.createTab 函数创建的各个面板（标签页）配置表的数组。

返回值：table，Accordion元素配置表，用于 buildUI 函数。

示例：

lua

local sectionAContent = {
    { ui.createCheckbox("toggleA", "启用选项A", true) }
}
local sectionBContent = {
    { ui.createSlider("valueB", 50, "数值B", 0, 100) }
}

local myAccordion = ui.createAccordion {
    ui.createTab("通用设置", sectionAContent),
    ui.createTab("高级设置", sectionBContent)
}

创建标签页组

创建一个包含多个标签页的UI分组。

lua

ui.createTabs({
    ui.createTab("第一组", {
        { ui.createSlider("speed", 30, "速度(0~100)", 0, 100, 1) }
    }),
    ui.createTab("第二组", {
        { ui.createCheckboxGroup("fruits", {"apple","orange"}, "喜欢的水果(可多选)", fruitItems) }
    }),
},
"top",
false
)

功能：创建一个标签页容器，允许将多个独立的UI标签页组织在一起，用户可以通过点击标签来切换显示内容。

参数：

tabs：table，一个包含由 ui.createTab 函数创建的各个标签页配置表的数组。
placement : str 四个选择值
fullWidth: bool 逻辑值代标签是否占用全部宽度

`placement`值	标签位置	推荐全宽属性 `fullWidth`
top	顶部	是
bottom	底部	是
start	左边	否
end	右边	否

返回值：table，Tabs元素配置表，用于 buildUI 函数。

示例：

lua

local tab1Content = {
    { ui.createSlider("setting1", 50, "设置一", 0, 100) }
}
local tab2Content = {
    { ui.createAlert("信息", "这是第二个标签页的内容。", "info") }
}

local myTabs = ui.createTabs({
    ui.createTab("通用设置", tab1Content),
    ui.createTab("高级选项", tab2Content)
},
"top",
false
)

创建单个标签页

创建一个标签页或可折叠分组，用于组织和分组其他UI元素。

lua

ui.createTab("标签页A", {
    { -- 这是一个组。默认仍会垂直排列；需要水平排列时请给节点设置 layout。
        ui.createSlider("createSlider_A", 17, "滑块A", 0, 100),
        ui.createSlider("createSlider_B", 17, "滑块B", 0, 100)
    },
    { -- 另一个组，通常会换行
        ui.createSelect("selectC", "opt1", "选项C", {{label="选项1", key="opt1"}})
    }
})

功能：创建一个独立的UI分组容器。它可以作为 ui.createTabs 的一个标签页，ui.createAccordion 的一个可折叠面板，也可以作为顶级元素直接显示在UI界面上，此时它通常表现为一个可折叠的分组。

参数：

title：字符串，该分组的标题。
groups：table，一个包含UI元素分组的数组。每个分组本身是一个 table，其中包含多个UI元素配置表。为了兼容旧版UI，组内元素默认仍然垂直堆叠；如果同一个分组内任意元素设置了 layout.span 或 layout.mode = "row"，该分组会启用 12 栅格布局，不同分组之间仍然垂直堆叠。

布局补充：

不需要修改 ui_builder 生成器。ui.createXxx(...) 返回的是一个普通 table，可以在创建后手动给节点添加 layout 字段。旧代码不添加 layout 时，界面保持原来的垂直排列。

layout.span：数字或字符串，范围建议为 1 到 12，表示当前组件在 12 栅格中占几格。
layout.mode = "row"：启用当前分组的横向栅格布局。通常只设置 span 即可。
推荐写在控件内部配置上，例如 input.Input.layout = { span = 6 }。前端也兼容 input.layout = { span = 6 }。

布局示例：

lua

local nameInput = ui.createInput("name", "名称", "请输入名称", "")
nameInput.Input.layout = { span = 6 }

local countInput = ui.createNumberInput("count", 1, "数量", 0, 100, 1, "1~100")
countInput.NumberInput.layout = { span = 6 }

local speedSlider = ui.createSlider("speed", 50, "速度", 0, 100, 1)
speedSlider.Slider.layout = { span = 12 }

local myTab = ui.createTab("基础设置", {
    { nameInput, countInput }, -- 两个 span=6 的控件会显示在同一行
    { speedSlider }            -- span=12，单独占一整行
})

返回值：table，Tab元素配置表，用于 ui.createTabs、ui.createAccordion 或直接用于 buildUI 函数。

示例：

lua

local tabContentGroup1 = {
    ui.createSlider("item1", 10, "项目1", 0, 100),
    ui.createSlider("item2", 20, "项目2", 0, 100)
}
local tabContentGroup2 = {
    ui.createAlert("提示", "这是一个独立的分组。", "info")
}

-- 作为独立的可折叠分组显示
local myCollapsibleGroup = ui.createTab("我的设置", {
    tabContentGroup1,
    tabContentGroup2
})

创建输入框

创建一个文本输入框，用于获取用户输入。

ui.createInput(key, label, placeholder, defaultValue) 参数：

key：字符串，该输入框的唯一标识符。
label：字符串，输入框的标签。
placeholder：字符串，输入框的占位符。
defaultValue：字符串，输入框的默认值。

示例：

lua

ui.createInput("inputName", "输入框标签", "输入框占位符", "默认值")

创建图片框

创建一个图片框，用于显示图片。

ui.createImage(src, isZoomed , alt ,width, height)

参数：

src：字符串，图片的URL地址。
isZoomed: 悬停时是否应缩放图像。
alt: 替代文本，当图片无法加载时显示。
width: 图片的宽度。
height: 图片的高度。

示例：

lua

ui.createImage("https://heroui.com/images/hero-card-complete.jpeg", true, "主页面示例图片", "300", "200")

创建分割线

创建一个分割线，用于分隔UI元素。

ui.createDivider(orientation)

参数：

orientation: 分割线的方向。可选值有 horizontal 和 vertical

示例：

lua

ui.createDivider("horizontal")

组件属性补充

大多数 UI 节点都可以在 ui.createXxx(...) 创建后继续补充前端组件属性。

ui.createXxx(...) 返回的是普通 table。在不修改 ui_builder 生成器的情况下，可以直接给返回节点的内部配置表追加属性。前端会把这些属性透传给对应 HeroUI 组件。

通用写法：

lua

local input = ui.createInput("name", "名称", "请输入名称", "")
input.Input.size = "sm"
input.Input.variant = "bordered"
input.Input.color = "primary"
input.Input.isDisabled = false
input.Input.layout = { span = 6 }

常用通用属性：

size：常见值为 "sm"、"md"、"lg"。
radius：常见值为 "none"、"sm"、"md"、"lg"、"full"。
variant：具体可用值取决于组件，例如输入类常用 "flat"、"bordered"、"faded"、"underlined"。
color：常见值为 "default"、"primary"、"secondary"、"success"、"warning"、"danger"。
isDisabled：禁用组件。
isReadOnly：只读，适用于输入类组件。
isRequired：标记为必填，适用于输入类组件。
className：追加 Tailwind/CSS 类名。
layout：前端动态布局字段，详见 ui.createTab 的布局补充说明。

Accordion 属性示例：

lua

local panel = ui.createAccordion({
    ui.createTab("基础设置", {
        { ui.createInput("name", "名称", "请输入", "") }
    })
})

panel.Accordion.variant = "splitted" -- light | shadow | bordered | splitted
panel.Accordion.isCompact = true
panel.Accordion.selectionMode = "multiple"
panel.Accordion.defaultSelectedKeys = {"基础设置"}
panel.Accordion.showDivider = false

前端同时兼容两种面板数据结构：

lua

-- 推荐：通过 ui.createAccordion({ ... }) 传入数组
local panelA = ui.createAccordion({
    ui.createTab("基础设置", {
        { ui.createInput("name", "名称", "请输入", "") }
    }),
    ui.createTab("高级设置", {
        { ui.createSlider("speed", 50, "速度", 0, 100, 1) }
    })
})

-- 兼容：Lua table 序列化后可能变成 "1"、"2" 这类数字键对象
-- 前端会按数字键顺序识别这些面板项，并自动忽略这些数字键，不会把它们透传给 HeroUI。

如果需要让 defaultSelectedKeys 默认展开某个面板，建议直接使用面板标题：

lua

panelA.Accordion.selectionMode = "multiple"
panelA.Accordion.defaultSelectedKeys = {"基础设置"}

ui.createTab(...) 生成的面板项也可以补充属性：

lua

local tab = ui.createTab("高级设置", {
    { ui.createSlider("speed", 50, "速度", 0, 100, 1) }
})

tab.subtitle = "可选参数"
tab.isDisabled = false

local panel = ui.createAccordion({ tab })

Tabs 属性示例：

lua

local tabs = ui.createTabs({
    ui.createTab("参数A", {
        { ui.createInput("a", "参数A", "请输入", "") }
    }),
    ui.createTab("参数B", {
        { ui.createInput("b", "参数B", "请输入", "") }
    })
}, "top", false)

tabs.Tabs.placement = "top" -- top | bottom | start | end
tabs.Tabs.fullWidth = true
tabs.Tabs.variant = "underlined"
tabs.Tabs.color = "primary"

Tabs 的标签项同样支持数组结构和数字键结构。前端会优先使用标签项的 key，没有 key 时使用 title 作为 React key，因此也可以用标题作为默认选中键。

Select / CheckboxGroup / RadioGroup 选项属性示例：

选项 items 中的每一项除了 label 和 key，也可以补充 description、isDisabled 等属性。

lua

local mode = ui.createSelect("mode", "auto", "运行模式", {
    { label = "自动", key = "auto", description = "按默认策略运行" },
    { label = "手动", key = "manual" },
    { label = "调试", key = "debug", isDisabled = true },
})

Autocomplete 属性示例：

lua

local project = {
    Autocomplete = {
        name = "project",
        label = "选择项目",
        placeholder = "输入关键字搜索",
        defaultSelectedKey = "hexide",
        isClearable = true,
        variant = "bordered",
        items = {
            { label = "HexIDE", key = "hexide" },
            { label = "UITEST", key = "uitest" },
        },
        layout = { span = 6 },
    }
}

Slider 属性示例：

lua

local speed = ui.createSlider("speed", 50, "速度", 0, 100, 1)
speed.Slider.showTooltip = true
speed.Slider.color = "primary"
speed.Slider.size = "sm"

Input / NumberInput 属性示例：

lua

local username = ui.createInput("username", "用户名", "请输入用户名", "")
username.Input.variant = "bordered"
username.Input.isClearable = true
username.Input.layout = { span = 6 }

local count = ui.createNumberInput("count", 1, "数量", 0, 100, 1, "1~100")
count.NumberInput.variant = "bordered"
count.NumberInput.hideStepper = false
count.NumberInput.layout = { span = 6 }

Switch 属性示例：

lua

local enableFeature = {
    Switch = {
        name = "enableFeature",
        title = "启用功能",
        isSelected = true,
    }
}

enableFeature.Switch.color = "primary"
enableFeature.Switch.size = "md"
enableFeature.Switch.layout = { span = 6 }

注意：

layout、items 是前端动态渲染使用的内部字段，不会继续透传给 HeroUI 组件。
未在本页列出的 HeroUI 属性，如果对应组件支持，通常也可以用同样方式追加。
不建议给事件类属性传字符串函数，例如 onClick、onChange。动态 UI 的交互仍建议通过 onUIChanged(values) 处理。

构建UI

根据定义的UI元素列表，生成UI结构并发送给前端。

lua

local uiElements = {
    ui.createAlert("欢迎", "这是一个示例UI。", "info"),
    ui.createSlider("mainSpeed", 0.5, "主速度", 0, 1, 0.1)
}
local jsonString = ui.buildUI(uiElements, 1)

功能：根据通过 ui.createX 系列函数定义的UI元素，构建完整的UI界面结构，并准备将其发送给前端进行渲染。

参数：

elements：table，一个包含所有顶级UI元素配置表的数组。这些元素将直接显示在UI的主界面上，例如 Alert, Slider, Select, Autocomplete, Div, P, Group, Tabs, Accordion, CheckboxGroup, NumberInput, Checkbox, Switch, RadioGroup, Input, Chip, Divider, Image 等。
updateMode：整数（可选），UI的更新模式。
- 0：强制覆盖（默认）。UI界面会完全按照代码中定义的默认值进行初始化。
- 1：更新结构并保留值。如果存在之前保存的UI值，则会优先使用这些保存的值，同时更新UI结构（例如，新增或删除元素）。这是推荐的模式，以便用户设置在脚本重新加载后得以保留。

返回值：string，表示UI结构的JSON字符串。在绝大多数情况下，你不需要直接处理这个字符串，库内部会将其发送给前端。

注意：此函数通常只在脚本启动时调用一次，用于初始化UI。

示例：

lua

local myUiElements = {
    ui.createAlert("提示", "请调整以下参数。", "info"),
    ui.createSlider("delay", 100, "延迟(ms)", 0, 500, 10),
    ui.createSelect("mode", "auto", "模式选择", {
        {label = "自动", key = "auto"},
        {label = "手动", key = "manual"}
    }),
    ui.createCheckbox("logging", "启用日志记录", true)
}

-- 构建UI，并尝试保留用户之前的设置
ui.buildUI(myUiElements, 1)

启动UI交互

启动UI界面并开始监听用户的交互事件。

lua

StartUI()

功能：显示UI界面，并激活与用户的交互功能。在此函数调用后，UI界面将可见，并且 onUIChanged 回调函数将开始监听用户操作。

注意：

必须在 ui.buildUI 之后调用此函数。
调用此函数后，全局 UICurrentValue 表将可用，其中包含所有UI元素的当前值。
onUIChanged 回调函数（如果已定义）将在UI参数改变时被触发。

示例：

lua

-- 1. 定义UI元素
local myUiElements = {
    ui.createSlider("sensitivity", 5, "灵敏度", 1, 10)
}

-- 2. 构建UI结构
ui.buildUI(myUiElements, 1)

-- 3. 启动UI界面
StartUI()

-- 此时，UI界面已显示，用户可以进行交互

UI参数改变回调函数

当用户在UI界面上改变任何参数时，系统会自动调用此函数。你需要定义这个函数来响应用户的操作。

lua

function onUIChanged(values)
    print("[Lua] onUIChanged fired!")
    if values.speed then -- 假设有一个名为 "speed" 的滑块
        local newSpeed = values.speed
        print("新的速度值 = ", newSpeed)
        -- 在此处更新你的脚本逻辑或全局变量
    end
    if values.selectColor then -- 假设有一个名为 "selectColor" 的选择框
        local selectedColors = values.selectColor -- 可能是字符串（单选）或数组（多选）
        if type(selectedColors) == "table" then
            print("新的颜色选择 (多选) = ", table.concat(selectedColors, ", "))
        else
            print("新的颜色选择 (单选) = ", selectedColors)
        end
    end
    if values.numberInput then -- 假设有一个名为 "numberInput" 的数字输入框
        local newNumber = values.numberInput
        print("新的数字输入值 = ", newNumber)
    end
    if values.singleCheck then -- 假设有一个名为 "singleCheck" 的复选框
        local isChecked = values.singleCheck
        print("单个复选框状态 = ", isChecked)
    end
    if values.favorite then -- 假设有一个名为 "favorite" 的单选框组
        local selectedFruit = values.favorite
        print("新的单选水果 = ", selectedFruit)
    end
end

功能：这是一个由系统自动调用的回调函数。当用户在UI界面上对任何元素进行操作，导致其值发生改变时，系统会触发此函数。你需要定义并实现此函数来响应用户的输入，从而更新你的脚本逻辑。

参数：

values：table，一个表，其中包含所有发生改变的UI元素的键名及其新值。
- 键是UI元素的 key 属性（在 createX 函数中定义的）。
- 值是该元素的新值。对于单值元素（如单选选择器、单值滑块、数字输入框、单个复选框、单选框组），值是字符串或数字；对于范围滑块和多选选择器（包括多选复选框组），值是一个包含相应值的 table。

注意：

你需要手动在你的脚本中定义此函数。
即使是未在代码中明确定义的UI元素，如果其值改变，也会出现在 values 参数中。
在此函数内部，通常会根据 values 表中的键来判断哪个UI元素的值发生了改变，并更新脚本中的相应变量或执行特定操作。

示例：

lua

-- 假设你有一个名为 'maxDelay' 的全局变量，对应一个滑块
local maxDelay = 100
local autoRunEnabled = false

function onUIChanged(values)
    if values.delay then -- 检查 'delay' 滑块的值是否改变
        maxDelay = values.delay -- 更新Lua脚本中的变量
        print("新的延迟值设置为: " .. maxDelay .. "ms")
    end

    if values.autoStart then -- 检查 'autoStart' 复选框的值是否改变
        autoRunEnabled = values.autoStart
        print("自动运行功能: " .. (autoRunEnabled and "已启用" or "已禁用"))
    end
end

-- ... 你的 UI 构建和 StartUI() 调用 ...

获取当前所有UI参数值

一个全局可用的表，包含了UI界面上所有元素的当前值。可以在脚本的任何地方直接访问。

lua

print("当前速度设置:", UICurrentValue.speed or "未设置")
print("当前间隔范围:", UICurrentValue.interval[1], "-", UICurrentValue.interval[2])
print("当前选中的水果 (多选):", table.concat(UICurrentValue.fruits or {}, ", "))

功能：UICurrentValue 是一个全局可用的表，它存储了UI界面上所有可交互元素的当前值。你可以在脚本的任何位置（在 StartUI() 调用之后）直接访问这个表来获取UI的最新状态。

返回值：table，一个包含所有UI元素当前键值对的表。

对于单值元素（如单选选择器、单值滑块、数字输入框、单个复选框、单选框组），值是字符串、数字或布尔值。
对于范围滑块和多选选择器（包括多选复选框组），值是一个包含相应值的 table（数组）。

注意：

UICurrentValue 表在 StartUI() 函数被调用后才可用。
如果某个键名对应的UI元素当前不存在，访问 UICurrentValue.键名 将返回 nil。
通常情况下，你会在 onUIChanged 函数中处理UI值的变化，但 UICurrentValue 提供了一种随时查询UI状态的便捷方式。

示例：

lua

-- 假设UI中有一个名为 "mainToggle" 的开关和一个名为 "threshold" 的滑块
-- local mainToggleValue = UICurrentValue.mainToggle
-- local thresholdValue = UICurrentValue.threshold

-- 在主循环中获取并使用UI参数
while true do
    if UICurrentValue.mainToggle then -- 检查开关是否打开
        local currentThreshold = UICurrentValue.threshold or 50 -- 获取滑块值，如果不存在则默认50
        print("当前阈值为: " .. currentThreshold)
        -- 执行基于阈值的逻辑
    else
        print("主功能已关闭。")
    end
    -- 模拟一些延迟，避免CPU占用过高
    -- Sleep(100)
end

界面模块 ​

导入UI库 ​

小白快速开始 ​

动态 UI 开发者速查 ​

UI 参数取值说明 ​

创建提示框 ​

创建滑块 ​

创建选择框 ​

创建自动完成选择框 ​

创建复选框组 ​

创建数字输入框 ​

创建单个复选框 ​

创建开关 ​

创建单选框组 ​

创建标签芯片 ​

创建布局分组 ​

创建通用容器 ​

创建段落文本 ​

创建手风琴折叠面板组 ​

创建标签页组 ​

创建单个标签页 ​

创建输入框 ​

创建图片框 ​

创建分割线 ​

组件属性补充 ​

构建UI ​

启动UI交互 ​

UI参数改变回调函数 ​

获取当前所有UI参数值 ​

界面模块

导入UI库

小白快速开始

动态 UI 开发者速查

UI 参数取值说明

创建提示框

创建滑块

创建选择框

创建自动完成选择框

创建复选框组

创建数字输入框

创建单个复选框

创建开关

创建单选框组

创建标签芯片

创建布局分组

创建通用容器

创建段落文本

创建手风琴折叠面板组

创建标签页组

创建单个标签页

创建输入框

创建图片框

创建分割线

组件属性补充

构建UI

启动UI交互

UI参数改变回调函数

获取当前所有UI参数值