界面模块

导入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

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")

创建复选框组

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

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 函数。

示例：

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)

创建单选框组

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

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")

创建手风琴折叠面板组

创建一个包含多个可折叠面板的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", {
    { -- 这是一个组，组内的元素会水平排列（如果空间允许）
        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元素配置表。同一个分组内的元素会尝试水平排列，不同分组之间通常会垂直堆叠。

返回值：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元素列表，生成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, Tabs, Accordion, CheckboxGroup, NumberInput, Checkbox, RadioGroup, Chip 等。
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(changedValues)
    if changedValues.delay then -- 检查 'delay' 滑块的值是否改变
        maxDelay = changedValues.delay -- 更新Lua脚本中的变量
        print("新的延迟值设置为: " .. maxDelay .. "ms")
    end

    if changedValues.autoStart then -- 检查 'autoStart' 复选框的值是否改变
        autoRunEnabled = changedValues.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参数值 ​