一、概述

exeasyui 是整合 LuatOS 中 lcd 核心库和 tp 触摸核心库以及 exlcd 显示扩展库和 extp 触摸扩展库而简化 UI 组件扩展库，内置了组件管理、页面渲染与触摸事件分发功能，使用少量代码就能实现 UI 交互的功能。

exeasyui为早期基于LCD核心库开发的简单UI开发扩展库，不适合较复杂UI的设计和开发；新项目UI开发更推荐使用AirUI 核心库进行开发

主要特性

• 组件丰富：内置 button、label、progress_bar、message_box、picture、check_box、combo_box、input、keyboard、window 等核.心组件
• 更低成本：可选内置合宙矢量字体，节省字库成本
• 开发高效：用更少代码快速搭建可量产的触控界面，内置触摸/渲染/组件与示例
• 验证便捷：提供 LuatOS PC 模拟器快速验证效果，无需烧录就能看到代码运行效果
• 效果一致：PC 模拟器呈现的功能效果与设备上运行的效果一致
• 持续更新：更多组件持续更新中，当前版本为：V1.7.1，点击下载 exeasyui 演示 demo 搭配 V2013及以上版本PC 模拟器进行仿真体验

注意事项

• exeasyui 为扩展库，没有内置到 LuatOS 内核固件中，使用时需要 require(“exeasyui”)加载后才能正常调用 exeasyui 的功能；
• exeasyui 默认使用的是 12 号中文字体，Air780EPM 不支持 12 号中文字体，使用会没有中文显示；
• Air780EHM/EHV/EGH 系列、Air8000 系列使用 exeasyui 配套的中文输入法，需要使用对应型号版本为 V2020 及以上的固件；
• Air780EHM/EHV/EGH 系列、Air8000 系列使用固件内置的 hzfont 合宙10-100号矢量字体，需要使用对应型号版本为 V2020 及以上的 14 号/114号固件。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/ui/exeayui

2.1 核心代码

以下示例演示：创建一个窗口，开启纵向滚动，将各个组件的最小可用示例纵向排布，滑动浏览。

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    ui.sw_init({ theme = "light" })

    local win = ui.window({ background_color = ui.COLOR_WHITE })
    -- 内容高度较大，启用纵向滚动
    win:enable_scroll({ direction = "vertical", content_height = 1000, threshold = 8 })

    local y = 20
    local function place(h)
        local cur = y; y = y + h + 16; return cur
    end

    -- 1) button
    local btn = ui.button({ x = 20, y = place(44), w = 280, h = 44, text = "button", on_click = function(self)
        log.info("demo", "button clicked")
    end })
    win:add(btn)

    -- 2) Toggle按钮
    local tb = ui.button({ x = 20, y = place(64), w = 64, h = 64, 
        src = "/luadb/icon.jpg", toggle = true, 
        on_toggle = function(t) log.info("demo", "toggled", t) end 
    })
    win:add(tb)

    -- 3) check_box
    local cb = ui.check_box({ x = 20, y = place(24), text = "Check me", checked = false, on_change= function(v)
        log.info("demo", "check_box", v)
    end })
    win:add(cb)

    -- 4) label（v1.6.0：支持自动换行）
    local lbl = ui.label({ x = 20, y = place(60), w = 280, word_wrap = true,
        text = "This is a long text that will wrap automatically within the specified width." })
    win:add(lbl)

    -- 5) picture（示例：无实际图片时会显示占位框）
    local pic = ui.picture({ x = 20, y = place(120), w = 160, h = 120, autoplay = false, src = "/luadb/sample.jpg" })
    win:add(pic)

    -- 6) message_box（作为静态面板展示）
    local box = ui.message_box({ x = 20, y = place(120), w = 280, h = 120, title = "message_box", message = "Info Panel", buttons = {"OK"}, on_result = function(r)
        log.info("demo", "msgbox", r)
    end })
    win:add(box)

    -- 7) progress_bar
    local pb = ui.progress_bar({ x = 20, y = place(26), w = 280, h = 26, progress = 35, text = "35%" })
    win:add(pb)

    ui.add(win)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.2 使用合宙 LuatOS-PC 模拟器仿真 exeasyui

2.2.1 PC 模拟器说明

• LuatOS-PC 模拟器是一个能在 win10/win11 上模拟运行 lua 脚本的仿真软件，内置 LuatOS 内核固件，运行.lua 脚本效果与实际设备类似；
• 目前 PC 模拟器可以通过 LuaTools 工具的资源管理器进行下载，所以我们需要先下载安装 LuaTools 工具，然后再通过 LuaTools 工具来下载 LuatOS-PC 模拟器，最后通过 LuatOS-PC 模拟器运行 exeasyui 演示 demo；

2.2.2 LuatOS-PC 模拟器安装步骤

1. 点击下载：Luatools v3 下载调试工具

2. 通过 LuaTools 工具下载 LuatOS-PC 模拟器

3. LuaTools 工具安装完毕后，点击首页面左上角的–账户–打开资源下载

4. 选择-公共资源–LuatOS 的 PC 模拟器–选择最新版本 LuatOS-PC 模拟器–点击开始下载（非刷机）

2.2.3 下载底层固件和上层运行脚本

1. 下载运行所需固件，点击资源管理–选择 Air780EHM 的 LuatOS 固件–下载最新版本的 1 号固件和 14 号固件
2. 下载本演示 demo 内所有.lua 脚本文件、images 文件夹

2.2.4 使用 LuatOS-PC 模拟器仿真 运行 exeasyui 演示 demo

1. 返回 Luatloos 工具首页，点击–项目管理测试

2、 创建一个项目并命名

3、 选择固件刚才下载的固件–点击打开，路径在 Luatools 目录下 resource\LuatOS_Air780EHM\LuatOS-SoC_VXXXX_Air780EHM

4、 将下载的 demo 图片资源和.lua文件拖入到项目管理内的脚本和资源列表区域–勾选添加默认 lib–点击模拟器运行–出来的界面就是 demo 在实际设备上运行界面的仿真，可以用鼠标进行交互

5、 如需切换 demo 内的演示内容，可打开下载脚本文件中的 mian.lua 文件，将需要演示 demo 的 require 前面–去掉，将不需要演示 demo 的 require 前面加上–。注释掉 require 的其他 demo 文件后，再点击模拟器运行，就会出现所 require 的 demo 对应的界面仿真。
6、 比如：需要演示下拉框组件，将-- require(“win_combo_box”) 改为 require(“win_combo_box”) ，并把其他加载的组件改为注释状态。

2.3 组件效果及其 demo

2.3.1 window（窗口容器）+label（文本）+ 循环更新

2.3.1.1 演示效果

默认使用12号中文字体	文本内容动态变化	可设置颜色
黑色/白色，跟随主题	时间：19:30:20	时间：19:30:20

2.3.1.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建label（文本）组件，在（20，20）位置显示"hello exeasyui"，命名为lbl
    lbl = ui.label({ x = 20, y = 20, text = "hello exeasyui"})

    -- 将组件lbl并注册到page1
    page1:add(lbl)

    -- 将page1注册到ui
    ui.add(page1)

    -- 显示主循环
    while true do      
        -- 更新时间给文本组件lbl
        lbl:set_text("时间:"..os.date("%Y-%m-%d %H:%M:%S"))           
        -- 等待300ms
        sys.wait(300)
    end

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.1.3 加载方式

require("win_dyn_label")  --动态更新标签演示

2.3.2 window（窗口容器）+ button（按钮）文本模式

2.3.2.1 演示效果

	默认状态	按下反馈
默认按钮	Button	Button
自定义命名	确定	确定

2.3.2.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个button（按钮）文本模式，显示在（20.20）位置，命名为btn1
    local btn1 = ui.button({ x = 20, y = 20})
    page1:add(btn1)

    -- 将page1注册到ui
    ui.add(page1)
end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.2.3 加载方式

require("win_button")  --基础按钮组件演示

2.3.3 window（窗口容器）+ button（按钮）图标模式

2.3.3.1 演示效果

2.3.3.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个button（按钮）图标模式，显示在（20.20）位置，命名为btn2，点击切换图片
    local btn2 = ui.button({x = 20, y = 20, w = 64, h = 64,
        toggle = true,                  -- 启用切换模式
        src = "/luadb/4.jpg",           -- 默认图片
        src_toggled = "/luadb/5.jpg",   -- 切换状态时的图片
    })
    page1:add(btn2)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.3.3 加载方式

require("win_toggle_button")  --切换按钮演示

2.3.4 window（窗口容器）+ progress_bar（进度条）静态方式

2.3.4.1 演示效果

2.3.4.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个progress_bar进度条，显示在（20.20）位置，命名为pb
    local pb = ui.progress_bar({ x = 20, y = 20, w = 280, h = 26})
    -- 添加控件到page1
    page1:add(pb)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.4.3 加载方式

require("win_progress_bar")  --静态进度条演示

2.3.5 window（窗口容器）+ progress_bar（进度条）动态方式

2.3.5.1 演示效果

2.3.5.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个progress_bar进度条，显示在（20.20）位置，命名为pb
    local pb = ui.progress_bar({ x = 20, y = 20, w = 280, h = 26})
    -- 添加控件到page1
    page1:add(pb)

    -- 将page1注册到ui
    ui.add(page1)

    -- 显示主循环
    while true do

        current = current + direction
        if current >= 100 then
            direction = -1
        elseif current <= 0 then
            direction = 1
        end

        pb:set_progress(current)

        -- 等待30ms
        sys.wait(30)
    end

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.5.3 加载方式

require("win_dyn_progress_bar")  --动态进度条演示

2.3.6 window（窗口容器）+ message_box（消息面板）

2.3.6.1 演示效果

2.3.6.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个message_box（消息面板），启用自动换行，显示在（20.20）位置，命名为box
    local box = ui.message_box({ x = 20, y = 20, word_wrap = true,title = "通知", message = "愿你前路浩荡,未来可期.愿你保持热爱,奔赴山海。愿你所有的努力都不被辜负,最终活成自己最喜欢的模样.加油!"})
    page1:add(box)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.6.3 加载方式

require("win_message_box")  --消息框组件演示

2.3.7 window（窗口容器）+ check_box（复选框）

2.3.7.1 演示效果

2.3.7.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个check_box（复选框），显示在（20.20）位置，命名为cb
    local cb = ui.check_box({ x = 20, y = 20, text = "Check me"})
    page1:add(cb)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.7.3 加载方式

require("win_check_box")  --复选框组件演示

2.3.8 window（窗口容器）+ picture（图片轮播）单图模式

2.3.8.1 演示效果

2.3.8.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"


**2.3.8.2 演示代码**

```lua
PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个 picture（图片轮播）组件，显示在（20.20）位置，命名为pic
    local pic = ui.picture({ x = 20, y = 20, sources = {"/luadb/1.jpg"}})
    -- 添加控件pic到page1
    page1:add(pic)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.8.3 加载方式

require("win_picture")  --静态图片显示演示

2.3.9 window（窗口容器）+ picture（图片轮播）轮播模式

2.3.9.1 演示效果

2.3.9.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个 picture（图片轮播）组件，按顺序每张图片显示1.5s，显示在（20.20）位置，命名为pic
    local pic = ui.picture({ x = 20, y = 20, sources = {"/luadb/1.jpg", "/luadb/2.jpg", "/luadb/3.jpg"}, autoplay = true, interval = 1500})
    -- 添加控件pic到page1
    page1:add(pic)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.9.3 加载方式

require("win_autoplay_picture")  --自动轮播图片演示

2.3.10 window（窗口容器）+ combo_box（下拉框）

2.3.10.1 演示效果

2.3.10.2 演示代码

-- 项目名称和版本定义
PROJECT = "exeasyui_demo" -- 项目名称，用于标识当前工程
VERSION = "1.0.0"         -- 项目版本号

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建下拉框
    local combo_box = ui.combo_box({
        x = 20,
        y = 20,
        w = 200,
        h = 30,
        options = { "选项1", "选项2", "选项3" },
        placeholder = "请选择",
        selected = 1,
        on_select = function(value, index, text)
            log.info("component_page", "选择了:", text, "索引:", index)
        end
    })

    -- 此处打开PC模拟器报错
    page1:add(combo_box)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.10.3 加载方式

require("win_combo_box")  --下拉框组件演示

2.3.11 window（窗口容器）+ input（输入框）明文输入

2.3.11.1 演示效果

2.3.11.2 演示代码

-- 项目名称和版本定义
PROJECT = "exeasyui_demo" -- 项目名称，用于标识当前工程
VERSION = "1.0.0"         -- 项目版本号

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建输入框
    local text_input = ui.input({
        x = 20, y = 20,
        w = 200, h = 30,
        placeholder = "请输入文本...",
        max_length = 20
    })

    -- 此处打开PC模拟器报错
    page1:add(text_input)

    -- 将page1注册到ui
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.11.3 加载方式

require("win_input")  --文本输入框演示

2.3.12 window（窗口容器）+ input（输入框）密码输入 password

2.3.12.1 演示效果

2.3.12.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建窗口容器
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建密码输入框组件
    local password_input = ui.input({
        x = 20, y = 20,
        w = 150, h = 30,
        placeholder = "请输入密码...",
        input_type = "password",
        max_length = 16
    })

    -- 创建密码显示/隐藏切换按钮
    local password_visible = false
    local btn_password_toggle = ui.button({
        x = 180, y = 20,
        w = 60, h = 30,
        text = "显示",
        bg_color = ui.COLOR_BLUE,
        text_color = ui.COLOR_WHITE,
        on_click = function()
            password_visible = not password_visible
            password_input.input_type = password_visible and "text" or "password"
            btn_password_toggle:set_text(password_visible and "隐藏" or "显示")
        end
    })

    -- 添加组件到窗口
    page1:add(password_input)
    page1:add(btn_password_toggle)

    -- 注册窗口到UI系统
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.12.3 加载方式

require("win_password_input")  --密码输入框演示

2.3.13 window（窗口容器）+ input（输入框）数字输入 number

2.3.13.1 演示效果

2.3.13.2 演示代码

PROJECT = "exeasyui_demo"
VERSION = "1.0.0"

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建窗口容器
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建数字输入框组件
    local number_input = ui.input({
        x = 20, y = 20,
        w = 100, h = 30,
        placeholder = "0-100",
        input_type = "number",
        max_length = 3
    })

    -- 创建减少按钮
    local btn_number_minus = ui.button({
        x = 130, y = 20,
        w = 40, h = 30,
        text = "-",
        on_click = function()
            local value = tonumber(number_input:get_text()) or 0
            if value > 0 then
                number_input:set_text(tostring(value - 1))
            end
        end
    })

    -- 创建增加按钮
    local btn_number_plus = ui.button({
        x = 180, y = 20,
        w = 40, h = 30,
        text = "+",
        on_click = function()
            local value = tonumber(number_input:get_text()) or 0
            if value < 100 then
                number_input:set_text(tostring(value + 1))
            end
        end
    })

    -- 添加组件到窗口
    page1:add(number_input)
    page1:add(btn_number_minus)
    page1:add(btn_number_plus)

    -- 注册窗口到UI系统
    ui.add(page1)

end

-- 为主程序创建协程，使主程序运行起来
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.13.3 加载方式

require("win_number_input")  --数字输入框演示

2.3.14 全部控件

2.3.14.1 演示效果

2.3.14.2 演示代码

--[[
@module  win_all_component
@summary 所有UI组件综合演示模块
@version 1.0.0
@date    2025.11.20
@author  江访
@usage
本文件为所有UI组件综合演示模块，核心业务逻辑为：
1、创建带滚动功能的窗口容器；
2、集成展示所有exEasyUI组件；
3、实现组件间的交互逻辑；
4、展示进度条、消息框、按钮、复选框、输入框等完整功能；
5、启动UI渲染循环持续刷新显示；

本文件的对外接口有1个：
1、返回主函数供main.lua调用；
]]

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 设置主题
    ui.sw_init({ theme = "light" })

    -- 创建窗口容器并启用滚动
    local page1 = ui.window({ background_color = ui.COLOR_WHITE })
    page1:enable_scroll({
        direction = "vertical",
        content_height = 1000,
        threshold = 8
    })

    -- ==================== 标题区域 ====================
    local title = ui.label({
        x = 100, y = 25,
        text = "组件演示页面",
        color = ui.COLOR_BLACK,
        size = 16
    })
    page1:add(title)

    -- ==================== 进度条组件区域 ====================
    local progress_label = ui.label({
        x = 20, y = 70,
        text = "1. 进度条组件演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local progress = 0
    local pb = ui.progress_bar({
        x = 20, y = 100,
        w = 200, h = 26,
        progress = progress
    })

    local btn_progress = ui.button({
        x = 230, y = 100,
        w = 70, h = 26,
        text = "+10%",
        on_click = function(self)
            progress = progress + 10
            if progress > 100 then
                progress = 0
            end
            pb:set_progress(progress)
            pb:set_text("进度: " .. progress .. "%")
        end
    })

    page1:add(progress_label)
    page1:add(pb)
    page1:add(btn_progress)

    -- ==================== 消息框组件区域 ====================
    local msgbox_label = ui.label({
        x = 20, y = 140,
        text = "2. 消息框组件演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local btn_msgbox = ui.button({
        x = 20, y = 170,
        w = 120, h = 30,
        text = "弹出消息框",
        on_click = function(self)
            local message_box = ui.message_box({
                x = 40, y = 150,
                w = 240, h = 180,
                word_wrap = true,
                title = "祝福",
                message = "愿你前路浩荡,未来可期.愿你保持热爱,奔赴山海。愿你所有的努力都不被辜负,最终活成自己最喜欢的模样.加油!",
                buttons = { "接受祝福" }
            })
            ui.add(message_box)
        end
    })

    page1:add(msgbox_label)
    page1:add(btn_msgbox)

    -- ==================== 切换按钮组件区域 ====================
    local toggle_label = ui.label({
        x = 20, y = 220,
        text = "3. 切换按钮演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local btn_toggle = ui.button({
        x = 20, y = 250,
        w = 64, h = 64,
        src = "/luadb/4.jpg",
        src_toggled = "/luadb/5.jpg",
        toggle = true,
    })

    page1:add(toggle_label)
    page1:add(btn_toggle)

    -- ==================== 复选框组件区域 ====================
    local checkbox_label = ui.label({
        x = 20, y = 330,
        text = "4. 复选框组件演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local checkbox1 = ui.check_box({
        x = 20, y = 360,
        text = "选项A",
        checked = false,
        on_change = function(checked)
            log.info("checkbox", "选项A:", checked)
        end
    })

    local checkbox2 = ui.check_box({
        x = 120, y = 360,
        text = "选项B",
        checked = true,
        on_change = function(checked)
            log.info("checkbox", "选项B:", checked)
        end
    })

    page1:add(checkbox_label)
    page1:add(checkbox1)
    page1:add(checkbox2)

    -- ==================== 输入框组件区域 ====================
    local input_label = ui.label({
        x = 20, y = 410,
        text = "5. 输入框组件演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local text_input = ui.input({
        x = 20, y = 440,
        w = 200, h = 30,
        placeholder = "请输入文本...",
        max_length = 20
    })

    page1:add(input_label)
    page1:add(text_input)

    -- ==================== 密码输入框组件区域 ====================
    local password_label = ui.label({
        x = 20, y = 490,
        text = "6. 密码输入框演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local password_input = ui.input({
        x = 20, y = 520,
        w = 150, h = 30,
        placeholder = "请输入密码...",
        input_type = "password",
        max_length = 16
    })

    local password_visible = false
    local btn_password_toggle = ui.button({
        x = 180, y = 520,
        w = 60, h = 30,
        text = "显示",
        bg_color = ui.COLOR_BLUE,
        text_color = ui.COLOR_WHITE,
        on_click = function()
            password_visible = not password_visible
            password_input.input_type = password_visible and "text" or "password"
            btn_password_toggle:set_text(password_visible and "隐藏" or "显示")
        end
    })

    page1:add(password_label)
    page1:add(password_input)
    page1:add(btn_password_toggle)

    -- ==================== 数字输入框组件区域 ====================
    local number_label = ui.label({
        x = 20, y = 570,
        text = "7. 数字输入框演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local number_input = ui.input({
        x = 20, y = 600,
        w = 100, h = 30,
        placeholder = "0-100",
        input_type = "number",
        max_length = 3
    })

    local btn_number_minus = ui.button({
        x = 130, y = 600,
        w = 40, h = 30,
        text = "-",
        on_click = function()
            local value = tonumber(number_input:get_text()) or 0
            if value > 0 then
                number_input:set_text(tostring(value - 1))
            end
        end
    })

    local btn_number_plus = ui.button({
        x = 180, y = 600,
        w = 40, h = 30,
        text = "+",
        on_click = function()
            local value = tonumber(number_input:get_text()) or 0
            if value < 100 then
                number_input:set_text(tostring(value + 1))
            end
        end
    })

    page1:add(number_label)
    page1:add(number_input)
    page1:add(btn_number_minus)
    page1:add(btn_number_plus)

    -- ==================== 下拉框组件区域 ====================
    local combo_label = ui.label({
        x = 20, y = 650,
        text = "8. 下拉框组件演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local combo_box = ui.combo_box({
        x = 20, y = 680,
        w = 200, h = 30,
        options = { "选项1", "选项2", "选项3" },
        placeholder = "请选择",
        selected = 1,
        on_select = function(value, index, text)
            log.info("combo_box", "选择了:", text, "索引:", index)
        end
    })

    page1:add(combo_label)
    page1:add(combo_box)

    -- ==================== 图片轮播组件区域 ====================
    local picture_label = ui.label({
        x = 20, y = 730,
        text = "9. 图片自动轮播组件演示:",
        color = ui.COLOR_BLACK,
        size = 14
    })

    local pic = ui.picture({
        x = 20, y = 760,
        w = 128, h = 128,
        sources = { "/luadb/1.jpg", "/luadb/2.jpg", "/luadb/3.jpg" },
        autoplay = true,
        interval = 1500
    })

    local btn_picture_toggle = ui.button({
        x = 160, y = 760,
        w = 80, h = 30,
        text = "手动切换图片",
        on_click = function()
            pic:next()
        end
    })

    page1:add(picture_label)
    page1:add(pic)
    page1:add(btn_picture_toggle)

    -- 注册窗口到UI系统
    ui.add(page1)
end

sys.taskInit(ui_main)

2.3.14.3 加载方式

require("win_all_component")  _--所有组件综合演示

2.3.15 window（窗口容器）+ 横向滑动

2.3.15.1 演示效果

2.3.15.2 演示代码

-- 项目名称和版本定义
PROJECT = "exeasyui_demo"  -- 项目名称，用于标识当前工程
VERSION = "1.0.0"          -- 项目版本号

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()
    ui.sw_init({ theme = "light" })

    local win = ui.window({ background_color = 0xFFFF })
    -- 启用横向滚动，将两页内容并排布置到一个宽画布
    local pageW, pageH = 320, 480
    local totalW = pageW * 2
    win:enable_scroll({ direction = "horizontal", content_width = totalW, threshold = 8, enabled = true, page_width = pageW })

    local function makeGrid(offset_x, labelPrefix)
        local cols, rows = 3, 3
        local bw, bh = 90, 80
        local mx, my = 20 + offset_x, 60
        local gapx, gapy = 10, 10
        local n = 1
        for r = 0, rows - 1 do
            for c = 0, cols - 1 do
                local x = mx + c * (bw + gapx)
                local y = my + r * (bh + gapy)
                local btn = ui.button({ x = x, y = y, w = bw, h = bh, text = string.format("%s-%d", labelPrefix, n) })
                win:add(btn)
                n = n + 1
            end
        end
    end

    -- 左页与右页
    makeGrid(0,  "P1")
    makeGrid(pageW, "P2")

    ui.add(win)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.15.3 加载方式

_equire("win_horizontal_slidin_page")  --横向滑动页面演示

2.3.16 window（窗口容器）+ 纵向滑动

2.3.16.1 演示效果

2.3.16.2 演示代码

-- 项目名称和版本定义
PROJECT = "exeasyui_demo" -- 项目名称，用于标识当前工程
VERSION = "1.0.0"         -- 项目版本号

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    ui.sw_init({ theme = "light" })

    local win = ui.window({ background_color = 0xFFFF })
    -- 启用纵向分页滚动，将两页内容上下排布到一个高画布
    local pageW, pageH = 320, 480
    local totalH = pageH * 2

    -- 创建一个窗口组件，纵向滑动，2个屏幕宽度，默认子组件滑动跟随
    win:enable_scroll({ direction = "vertical", content_height = totalH, threshold = 10, page_height = pageH })

    -- 创建一个窗口组件，纵向滑动，2个屏幕宽度，启用滑动翻页，滑动跟随失效
    -- win:enable_scroll({ direction = "vertical", content_height = totalH, threshold = 10, snap_to_page = true, page_height = pageH })

    local function makebuttons(offset_y, labelPrefix)
        -- 改为竖直等间距排列：1列3行，横向居中
        local cols, rows = 1, 3
        local bw, bh = 90, 80
        local mx = math.floor((pageW - bw) / 2) -- 居中
        local gap = math.floor((pageH - rows * bh) / (rows + 1))
        if gap < 8 then gap = 8 end
        local n = 1
        for r = 0, rows - 1 do
            local x = mx
            local y = offset_y + gap + r * (bh + gap)
            local btn = ui.button({ x = x, y = y, w = bw, h = bh, text = string.format("%s-%d", labelPrefix, n) })
            win:add(btn)
            n = n + 1
        end
    end

    -- 上页与下页：每页 3 个按钮，共 6 个
    makebuttons(0, "P1")
    makebuttons(pageH, "P2")

    ui.add(win)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.16.3 加载方式

require("win_vertical_slidin_page")  --纵向滑动页面演示

2.3.17 页面切换

2.3.17.1 演示效果

2.3.17.2 演示代码

-- 项目名称和版本定义
PROJECT = "exeasyui_demo"  -- 项目名称，用于标识当前工程
VERSION = "1.0.0"          -- 项目版本号

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 创建一个msgbox_page页面的函数
-- 这个函数用于创建消息框演示页面
local function msgbox_page()
    -- 创建一个白色背景的窗口容器
    local win = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建一个消息框作为页面标题（不包含按钮）
    -- 这里使用message_box组件来显示标题和描述文字
    local title = ui.message_box({ 
        x = 10, y = 10,          -- 位置坐标
        w = 300, h = 80,         -- 宽度和高度
        title = "消息框页面",     -- 标题文字
        message = "点击按钮弹出消息框",  -- 描述信息
        buttons = {}             -- 空按钮数组，表示不显示任何按钮
    })

    -- 创建"弹出消息框"按钮
    local btn = ui.button({
        x = 20, y = 140,         -- 按钮位置
        w = 180, h = 50,         -- 按钮尺寸
        text = "弹出消息框",      -- 按钮文字
        -- 按钮点击事件处理函数
        on_click = function()
            -- 当按钮被点击时，创建一个新的消息框
            local box = ui.message_box({
                x = 40, y = 210,     -- 消息框显示位置
                w = 240, h = 120,    -- 消息框尺寸
                title = "提示",      -- 消息框标题
                message = "这是一条消息",  -- 消息内容
                buttons = { "确定", "取消" },  -- 两个按钮
                -- 按钮点击回调函数（这里为空函数）
                on_result = function()
                    -- 可以在这里处理按钮点击后的逻辑
                end
            })
            -- 将消息框添加到UI渲染队列中
            ui.add(box)
        end
    })

    -- 创建"返回"按钮
    local back = ui.button({
        x = 220, y = 140,        -- 按钮位置（在弹出按钮右边）
        w = 80, h = 50,          -- 按钮尺寸
        text = "返回",           -- 按钮文字
        -- 按钮点击事件：返回上一级页面
        on_click = function()
            win:back()  -- 调用窗口的back方法返回主页
        end
    })

    -- 将所有组件添加到窗口中
    win:add(title)  -- 添加标题消息框
    win:add(btn)    -- 添加弹出按钮
    win:add(back)   -- 添加返回按钮

    return win      -- 返回创建好的窗口对象
end

-- 创建一个check_box_page页面的函数
-- 这个函数用于创建复选框演示页面
local function check_box_page()
    -- 创建白色背景窗口
    local win = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建页面标题（使用无按钮的消息框）
    local title = ui.message_box({ 
        x = 10, y = 10, 
        w = 300, h = 80, 
        title = "复选框页面", 
        message = "演示多个check_box", 
        buttons = {} 
    })

    -- 创建三个复选框组件
    local cb1 = ui.check_box({ x = 20, y = 120, text = "选项A" })  -- 默认未选中
    local cb2 = ui.check_box({ x = 20, y = 160, text = "选项B", checked = true })  -- 默认选中
    local cb3 = ui.check_box({ x = 20, y = 200, text = "选项C" })  -- 默认未选中

    -- 创建返回主页按钮
    local back = ui.button({
        x = 20, y = 260, 
        w = 120, h = 40,
        text = "返回主页",
        on_click = function()
            win:back()  -- 返回主页
        end
    })

    -- 将所有组件添加到窗口
    win:add(title)  -- 标题
    win:add(cb1)    -- 复选框A
    win:add(cb2)    -- 复选框B  
    win:add(cb3)    -- 复选框C
    win:add(back)   -- 返回按钮

    return win      -- 返回窗口对象
end

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 显示触摸初始化
    hw_font_drv.init()

    -- 初始化UI系统，设置主题为浅色模式
    ui.sw_init({ theme = "light" })

    -- 创建主页面窗口（白色背景）
    local home = ui.window({ background_color = ui.COLOR_WHITE })

    -- 配置子页面工厂函数
    -- 这里注册了两个子页面："page1"对应消息框页面，"page2"对应复选框页面
    home:configure_subpages({ 
        page1 = msgbox_page,   -- 消息框演示页面
        page2 = check_box_page  -- 复选框演示页面
    })

    -- 创建导航按钮1：进入复选框示例页面
    local btn1 = ui.button({
        x = 20, y = 60,    -- 按钮位置
        w = 280, h = 50,   -- 按钮尺寸
        text = "复选框示例", -- 按钮文字
        on_click = function()
            -- 点击后显示复选框示例页面
            home:show_subpage("page2")
        end
    })

    -- 创建导航按钮2：进入消息框示例页面  
    local btn2 = ui.button({
        x = 20, y = 130,   -- 按钮位置（在第一个按钮下方）
        w = 280, h = 50,   -- 按钮尺寸
        text = "消息框示例", -- 按钮文字
        on_click = function()
            -- 点击后显示消息框示例页面
            home:show_subpage("page1")
        end
    })

    -- 创建功能按钮：移除复选框子界面（演示销毁功能）
    local btnRemove = ui.button({
        x = 20, y = 200,   -- 按钮位置
        w = 280, h = 50,   -- 按钮尺寸
        text = "移除复选框子界面(销毁)", -- 按钮文字
        on_click = function()
            -- 强制销毁缓存的check_box子页面，释放内存
            home:close_subpage("page2", { destroy = true })
        end
    })

    -- 将所有按钮添加到主页面
    home:add(btn1)         -- 复选框示例按钮
    home:add(btn2)         -- 消息框示例按钮
    home:add(btnRemove)    -- 移除页面按钮

    -- 将主页面添加到UI渲染系统
    ui.add(home)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

-- 启动系统调度器
sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.17.3 加载方式

require("win_switch_page")  --页面切换演示

2.3.18 合宙矢量字体

2.3.18.1 演示效果

2.3.18.2 演示代码

-- 项目名称和版本定义
PROJECT = "exeasyui_demo"  -- 项目名称，用于标识当前工程
VERSION = "1.0.0"          -- 项目版本号

-- 必须加载才能启用exeasyui的功能
local ui = require("exeasyui")

-- 加载显示、触摸和字体驱动模块
local hw_font_drv = require("hw_font_drv")

-- 主程序
local function exeasyui_demo()
    sys.wait(500)

    -- 启用14号固件内置HzFont矢量字体方式驱动
    hw_font_drv.init({
        type = "hzfont",
        size = 32,
        antialias = -1  -- 自动抗锯齿
    })

    ui.sw_init({ theme = "light" })

    local win = ui.window({ background_color = ui.COLOR_WHITE })
    ui.add(win)

    -- 显示各种字符
    local text1 = ui.label({ x = 10, y = 20, text = "HzFont矢量字体", color = ui.COLOR_BLACK })
    local text2 = ui.label({ x = 10, y = 60, text = "Hello World", color = ui.COLOR_RED })
    local text3 = ui.label({ x = 10, y = 100, text = "中英混排 ABC 123", color = ui.COLOR_GREEN })
    local text4 = ui.label({ x = 10, y = 140, text = "支持抗锯齿渲染", color = ui.COLOR_BLUE })
    local text5 = ui.label({ x = 10, y = 180, text = "智能缓存加速", color = ui.COLOR_ORANGE })

    win:add(text1)
    win:add(text2)
    win:add(text3)
    win:add(text4)
    win:add(text5)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

sys.run() -- 结尾都是sys.run()，之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

2.3.18.3 加载方式

require("win_hzfont")  --合宙矢量字体演示

三、常量详解

扩展库常量，顾名思义是由扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中需要 require(“exeasyui”)后，可通过 exeasyui.常量名直接调用；

exEasyUI 库定义了以下常量，用于颜色配置和触摸事件处理：

3.1 exeasyui.COLOR_WHITE

参数含义：白色  
数据类型：number  
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10, 
            w = 100, h = 40,
            text = "按钮",
            textColor = exeasyui.COLOR_WHITE
        })

3.2 exeasyui.COLOR_BLACK

参数含义：黑色  
数据类型：number  
示例代码：
        local label = exeasyui.Label({
            x = 10, y = 10,
            text = "文本标签",
            color = exeasyui.COLOR_BLACK
        })

3.3 exeasyui.COLOR_GRAY

参数含义：灰色  
数据类型：number  
示例代码：
        local progressBar = exeasyui.ProgressBar({
            x = 10, y = 10,
            w = 200, h = 20,
            backgroundColor = exeasyui.COLOR_GRAY
        })

3.4 exeasyui.COLOR_BLUE

参数含义：蓝色  
数据类型：number   
示例代码：
        local progressBar = exeasyui.ProgressBar({
            x = 10, y = 10,
            w = 200, h = 20,
            progressColor = exeasyui.COLOR_BLUE
        })

3.5 exeasyui.COLOR_RED

参数含义：红色  
数据类型：number   
示例代码：
        local label = exeasyui.Label({
            x = 10, y = 10,
            text = "错误信息",
            color = exeasyui.COLOR_RED
        })

3.6 exeasyui.COLOR_GREEN

参数含义：绿色  
数据类型：number   
示例代码：
        local label = exeasyui.Label({
            x = 10, y = 10,
            text = "成功信息",
            color = exeasyui.COLOR_GREEN
        })

3.7 exeasyui.COLOR_YELLOW

参数含义：黄色  
数据类型：number  
示例代码：
        local label = exeasyui.Label({
            x = 10, y = 10,
            text = "警告信息",
            color = exeasyui.COLOR_YELLOW
        })

3.8 exeasyui.COLOR_CYAN

参数含义：青色  
数据类型：number    
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "按钮",
            bgColor = exeasyui.COLOR_CYAN
        })

3.9 exeasyui.COLOR_MAGENTA

参数含义：洋红色  
数据类型：number   
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "按钮",
            borderColor = exeasyui.COLOR_MAGENTA
        })

3.10 exeasyui.COLOR_ORANGE

参数含义：橙色  
数据类型：number   
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "警告按钮",
            bgColor = exeasyui.COLOR_ORANGE
        })

3.11 exeasyui.COLOR_PINK

参数含义：粉色  
数据类型：number   
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "特殊按钮",
            bgColor = exeasyui.COLOR_PINK
        })

3.12 exeasyui.COLOR_WIN11_LIGHT_DIALOG_BG

参数含义：Windows 11 浅色主题对话框背景色  
数据类型：number   
示例代码：
        local window = exeasyui.Window({
            x = 0, y = 0,
            w = 320, h = 240,
            backgroundColor = exeasyui.COLOR_WIN11_LIGHT_DIALOG_BG
        })

3.13 exeasyui.COLOR_WIN11_LIGHT_BUTTON_BG

参数含义：Windows 11 浅色主题按钮背景色  
数据类型：number   
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "按钮",
            bgColor = exeasyui.COLOR_WIN11_LIGHT_BUTTON_BG
        })

3.14 exeasyui.COLOR_WIN11_LIGHT_BUTTON_BORDER

参数含义：Windows 11 浅色主题按钮边框色  
数据类型：number   
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "按钮",
            borderColor = exeasyui.COLOR_WIN11_LIGHT_BUTTON_BORDER
        })

3.15 exeasyui.COLOR_WIN11_DARK_DIALOG_BG

参数含义：Windows 11 深色主题对话框背景色  
数据类型：number   
示例代码：
        local window = exeasyui.Window({
            x = 0, y = 0,
            w = 320, h = 240,
            backgroundColor = exeasyui.COLOR_WIN11_DARK_DIALOG_BG
        })

3.16 exeasyui.COLOR_WIN11_DARK_BUTTON_BG

参数含义：Windows 11 深色主题按钮背景色  
数据类型：number   
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "按钮",
            bgColor = exeasyui.COLOR_WIN11_DARK_BUTTON_BG
        })

3.17 exeasyui.COLOR_WIN11_DARK_BUTTON_BORDER

参数含义：Windows 11 深色主题按钮边框色  
数据类型：number   
示例代码：
        local btn = exeasyui.Button({
            x = 10, y = 10,
            w = 100, h = 40,
            text = "按钮",
            borderColor = exeasyui.COLOR_WIN11_DARK_BUTTON_BORDER
        })

四、函数详解

4.1 核心初始化与渲染接口

4.1.1 ui.hw_init(opts)

功能

初始化硬件显示和触摸设备。

注意

• 使用时需要 require：exeasyui 才能正常使用 exeasyui 的功能
• 初始化硬件显示和触摸设备，exeasyui 默认开启缓冲区设置，禁用 JPG 图片硬件解码，使用 12 号中文字体。
• 启用缓冲区后，缓冲区会占用固定的内存空间（大小为：屏幕宽度 × 屏幕高度 × 2 字节），所有绘图操作结果所生成的数据将首先写入缓冲区，在执行刷新指令时，系统会一次性将缓冲区中的数据快速传输至屏幕。
• 若不设置缓冲区，模块需要一边处理图像数据一边等待数据发送，每次只要产生显示数据都需要寻找端口然后发送，相对于设置缓冲区实现同样的操作运行效率更低。
• JPG 硬件解码开启，图片刷新速度更快， JPG 图片的长宽都需要是 16 的倍数, 否则会出现画面拉伸的现象。

参数

opts

参数含义：硬件配置参数表
数据类型：table
是否必选：可选
取值范围：包含以下lcd_config，tp_config，enable_buffer，
         enable_hardware_decode，font_config五个子参数：
        {
        参数含义：LCD显示配置参数表
        数据类型：table
        取值范围：包含以下可选子参数
                {
                    参数含义：LCD显示配置参数表
                    数据类型：table
                    取值范围：包含以下可选子参数：
                    参数含义：lcd型号标识；
                    数据类型：string；
                    取值范围：：分为四大类,当lcd_model是配件板且搭配配套的开发板使用或者量产功能板时，
                               只需要传入lcd_model参数
                             1、合宙LCD配件板
                                 "AirLCD_1000"(对应Air780EPM/EHM/EGH/EHV整机开发板上配套的的显示屏)
                                 "AirLCD_1010"(对应Air8000整机开发板上配套的的显示屏)
                                 "AirLCD_1020"(对应Air8101核心板上配套的的显示屏)
                             2、合宙量产功能板
                                 "Air780EHM_LCD_4"(自带3.5寸480*320触摸屏，矢量字库，tf卡槽)
                             3、支持显示IC型号
                                 "st7796"、"st7789"、"st7735"、"st7735v"、"st7735s"
                                 "gc9a01"、"gc9106l"、"gc9306x"、"ili9486"、"ili9341"
                                 "nv3037"、"h050iwv"、"co5300"、"jd9261t"、"sh8601z"
                             4、自定义显示IC型号
                                 "custom"；
                    是否必选：必须传入此参数；
                    注意事项：根据实际使用的lcd屏幕型号填写对应的参数；
                    参数示例：lcd_model = "Air780EHM_LCD_4"
                    lcd_model = ,

                    参数含义：lcd供电开启GPIO的ID号，设置后初始化时会拉高所设置GPIO；
                    数据类型：number；
                    取值范围：有效的GPIO的ID号；
                    是否必选：可选传入此参数；如果没有传入，根据自己的硬件设计需要自行控制；
                    注意事项：暂无；
                    参数示例：pin_vcc = 1
                    pin_vcc = ,

                    参数含义：lcd背光引脚GPIO的ID号，设置可通过该引脚控制屏幕背光开启和关闭；
                    数据类型：number；
                    取值范围：有效的GPIO的ID号；
                    是否必选：可选传入此参数；如果没有传入，无法使用休眠唤醒指令控制休眠和唤醒，
                             且需要根据自己的硬件设计需要自行控制背光；
                    注意事项：具体步骤可以按【1.2章节注意事项】来操作；
                    参数示例：pin_pwr = 1                     
                    pin_pwr = ,

                    参数含义：lcd背光引脚PWM的ID号，设置可通过该引脚控制屏幕背光亮度；
                    数据类型：number；
                    取值范围：有效的PWM的ID号；
                    是否必选：可选传入此参数；如果没有传入，根据自己的硬件设计需要自行控制背光；
                    注意事项：具体步骤可以按【1.2章节注意事项】来操作；
                    参数示例：pin_pwm = 0
                    pin_pwm = ,

                    参数含义：lcd硬件驱动端口类型；
                    数据类型：number或者string；
                    取值范围：
                            1、lcd.HWID_0表示专用lcd SPI接口；
                            2、lcd.RGB表示RGB端口；
                            3、0,1,2表示具体的标准SPI硬件端口ID；
                            4、lcd.QSPI_MODE标识QSPI端口；
                            5、"device"表示具体的标准SPI硬件端口对象；
                               device的方式是通过spi.deviceSetup()先将SPI接口设置为SPI对象，
                               并赋值给一个全局变量，然后再将全局变量放到lcd.init()第三个参数spi_dev，
                               在此需要赋值port = "device"，      
                    是否必选：合宙量产功能板和合宙LCD配件板可选，其他必须传入此参数；
                    注意事项：根据实际硬件连接选择对应的端口类型；
                    参数示例：port = lcd.HWID_0
                    port = ,

                    参数含义：lcd数据/命令选择引脚GPIO号；
                    数据类型：number；
                    取值范围：有效的GPIO的ID号；
                    是否必选：可选传入此参数，默认nil，
                    注意事项：1、当参数port = lcd.HWID_0时，pin_dc参数保持为空；
                             2、当参数port = lcd.RGB时，pin_dc参数保持为空；
                             3、当参数port = 0、1、2等标准SPI接口时，pin_dc需要赋值；
                             4、当参数port = lcd.QSPI_MODE时，pin_dc参数保持为空；
                             5、当参数port = "device"时，pin_dc需要赋值；
                    参数示例：pin_dc = 31
                    pin_dc = ,

                    参数含义：lcd复位引脚GPIO号；
                    数据类型：number；
                    取值范围：有效的GPIO的ID号；
                    是否必选：可选传入此参数；
                    注意事项：1、当参数port = lcd.RGB时，pin_rst参数保持为空；
                             2、当参数port = 其他类型时，pin_rst参数根据实际情况填写；
                    参数示例：pin_rst = 10
                    pin_rst = ,

                    参数含义：lcd屏幕方向；
                    数据类型：number；
                    取值范围：lcd.direction_0表示显示方向为0°；
                             lcd.direction_90表示显示方向为90°；
                             lcd.direction_180表示显示方向为180°；
                             lcd.direction_270表示显示方向为270°；
                    是否必选：可选传入此参数；不传入此参数，默认是0度方向；
                    注意事项：设置屏幕的显示方向；
                    参数示例：direction = lcd.direction_0
                    direction = ,

                    参数含义：lcd水平分辨率；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：合宙量产功能板和合宙LCD配件板可选，其他必须传入此参数；
                    注意事项：设置屏幕的宽度像素值；
                    参数示例：w = 240
                    w = ,

                    参数含义：lcd竖直分辨率；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：合宙量产功能板和合宙LCD配件板可选，其他必须传入此参数；
                    注意事项：设置屏幕的高度像素值；
                    参数示例：h = 320
                    h = ,

                    参数含义：X偏移；
                    数据类型：number；
                    取值范围：整数；
                    是否必选：可选传入此参数，省略此参数则偏移量默认为0；
                    注意事项：不同屏幕IC和不同屏幕方向会有差异；
                    参数示例：xoffset = 0
                    xoffset = ,

                    参数含义：Y偏移；
                    数据类型：number；
                    取值范围：整数；
                    是否必选：可选传入此参数，省略此参数则偏移量默认为0；
                    注意事项：不同屏幕IC和不同屏幕方向会有差异；
                    参数示例：yoffset = 0
                    yoffset = ,

                    参数含义：睡眠命令；
                    数据类型：number；
                    取值范围：十六进制命令值；
                    是否必选：可选传入此参数，默认0x10；
                    注意事项：使用lcd.sleep()时发送配置的命令；
                    参数示例：sleepcmd = 0x10
                    sleepcmd = ,

                    参数含义：唤醒命令；
                    数据类型：number；
                    取值范围：十六进制命令值；
                    是否必选：可选传入此参数，默认0x11；
                    注意事项：使用lcd.wakeup()时发送配置的命令；
                    参数示例：wakecmd = 0x11
                    wakecmd = ,

                    参数含义：0°方向的命令；
                    数据类型：number；
                    取值范围：十六进制命令值；
                    是否必选：可选传入此参数，省略此参数时默认为0x00；
                    注意事项：不同屏幕IC会有差异；
                    参数示例：direction0 = 0x00
                    direction0 = ,

                    参数含义：90°方向的命令；
                    数据类型：number；
                    取值范围：十六进制命令值；
                    是否必选：可选传入此参数，省略此参数时默认为0x60；
                    注意事项：不同屏幕IC会有差异；
                    参数示例：direction90 = 0x01
                    direction90 = ,

                    参数含义：180°方向的命令；
                    数据类型：number；
                    取值范围：十六进制命令值；
                    是否必选：可选传入此参数，省略此参数时默认为0xC0；
                    注意事项：不同屏幕IC会有差异；
                    参数示例：direction180 = 0x02
                    direction180 = ,

                    参数含义：270°方向的命令；
                    数据类型：number；
                    取值范围：十六进制命令值；
                    是否必选：可选传入此参数，省略此参数时默认为0xA0；
                    注意事项：不同屏幕IC会有差异；
                    参数示例：direction270 = 0x03
                    direction270 = ,

                    参数含义：lcd接口软件驱动类型；
                    数据类型：string；
                    取值范围：lcd.QSPI_MODE；
                    是否必选：可选传入此参数，
                    注意事项：interface_mode参数是port参数的进一步细分
                             1、当参数port = lcd.QSPI_MODE时，interface_mode参数赋值为lcd.QSPI_MODE；
                             2、当参数port = lcd.HWID_0且所接屏幕接口为QSPI时，
                                interface_mode参数赋值为lcd.QSPI_MODE；
                             3、当参数port = 其他类型时，interface_mode参数保持为空；
                    参数示例：interface_mode = lcd.QSPI_MODE
                    interface_mode = ,

                    参数含义：QSPI/RGB总线速率，单位为Hz；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数；
                    注意事项：目前lcd核心库设置速率上限是80MHz，目前lcd库支持的型号
                             显示IC型号:jd9261t, QSPI接口，bus_speed = 70000000
                             显示IC型号:co5300,  QSPI接口，bus_speed = 60000000
                             显示IC型号:h050iwv,  RGB接口， bus_speed = 30000000             
                             其他QSPI/RGB接口显示IC，根据芯片手册要求填此参数
                    参数示例：bus_speed = 70000000
                    bus_speed = ,

                    参数含义：水平后廊，用于生成水平扫描时序，控制有效数据传输前的延迟周期；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数；
                    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
                             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
                             优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
                    参数示例：hbp = 10
                    hbp = ,

                    参数含义：水平同步脉冲宽度，初始化时参与水平同步信号的时序计算，
                             决定水平同步脉冲的持续周期；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数，无默认值；
                    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
                             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
                             优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
                    参数示例：hspw = 5
                    hspw = ,

                    参数含义：水平前廊，用于水平扫描时序配置，控制有效数据传输后的延迟周期；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数，无默认值；
                    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
                             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
                             优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
                    参数示例：hfp = 10
                    hfp = ,

                    参数含义：垂直后廊，在垂直扫描时序配置中生效，控制帧数据传输前的垂直延迟周期；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数，无默认值；
                    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
                             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
                             优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
                    参数示例：vbp = 10
                    vbp = ,

                    参数含义：垂直同步脉冲宽度，初始化时参与垂直同步信号的时序计算，
                             决定垂直同步脉冲的持续周期；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数，无默认值；
                    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
                             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
                             优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
                    参数示例：vspw = 5
                    vspw = ,

                    参数含义：垂直前廊，用于垂直扫描时序配置，控制帧数据传输后的垂直延迟周期；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数，无默认值；
                    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
                             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
                             优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
                    参数示例：vfp = 10
                    vfp = ,

                    参数含义：垂直同步，用于控制垂直同步信号的使能或参数，
                             具体作用依赖屏幕驱动 IC 的时序要求；
                    数据类型：number；
                    取值范围：正整数；
                    是否必选：可选传入此参数，无默认值；
                    注意事项：此参数为校准调试参数，lcd.init()中driver_ic支持的型号不需要填写，
                             其他非driver_ic支持的型号，如果出现不显示或显示不正确的情况，
                             优先与芯片原厂沟通需要调节哪些参数，再根据显示芯片手册在规定范围内进行调整；
                    参数示例：vs = 1
                    vs = ,

                    参数含义：刷新率，用于控制屏幕扫描时的帧刷新频率，驱动会根据该值调整数据传输的周期；
                    数据类型：number；
                    取值范围：正整数，单位0.1Hz；
                    是否必选：可选传入此参数，无默认值；
                    注意事项：屏幕选型时建议询问厂家对应的型号是否带RAM，若不带则根据芯片手册建议进行设置；
                    参数示例：flush_rate = 600
                    flush_rate = ,

                    参数含义：调换x方向（默认为水平方向）和y方向判定（默认为竖直方向）；
                    数据类型：boolean；
                    取值范围：true或false；
                    是否必选：可选传入此参数，不填则默认值为false，一般不需要使用；
                    注意事项：false（默认）：x 为水平方向，y 为竖直方向；
                             true：交换 x 和 y 的方向判定，适用于特殊屏幕布局需求
                    参数示例：rb_swap = false
                    rb_swap = ,

                    参数含义：自定义屏幕初始化命令表，在lcd.init()内部执行初始化后，
                             会自动调用lcd.cmd按顺序执行initcmd表内的命令；
                    数据类型：table；
                    取值范围：包含初始化命令序列的table；
                    是否必选：可选传入此参数；
                    注意事项：用于自定义屏幕初始化流程，driver_ic为"custom"时才使用，命令格式如下；
                             1、0x01xxxx: 表示延时，xxxx为延时ms时间
                             2、0x02xxxx: 表示命令，xxxx为命令码
                             3、0x03xxxx: 表示参数，xxxx为参数值
                    参数示例：initcmd = {0x0200FE, 0x030000}
                    initcmd = ,

                    参数含义：SPI设备对象；
                    数据类型：userdata；
                    取值范围：SPI设备对象；
                    是否必选：可选传入此参数；
                    注意事项：当port = "device"时有效，当port ≠ "device"时可省略该参数或者填nil；
                    参数示例：spi_dev = device
                    spi_dev = ,

                    参数含义：是否允许在后台初始化lcd；
                    数据类型：boolean；
                    取值范围：true或false；
                    是否必选：可选传入此参数，默认值为false；
                    注意事项：支持的型号推荐使用，不支持的型号省略此参数；
                    参数示例：init_in_service = false
                    init_in_service = ,
                }，
        是否必选：必须
        注意事项：LCD配置为必须项，用于初始化显示设备
        lcd_config =  ,

        参数含义：触摸配置参数表
        数据类型：table
        取值范围：包含以下可选子参数：
                {
                    参数含义：触摸芯片型号
                    数据类型：string
                    是否必选：是
                    取值范围：分为三大类，当tp_model是配件板且搭配配套的开发板使用或者量产功能板时，
                             只需要传入tp_model参数
                             1、合宙LCD配件板
                                 "AirLCD_1010"(对应Air8000整机开发板上配套的的显示屏)
                                 "AirLCD_1020"(对应Air8101核心板上配套的的显示屏)
                             2、合宙量产功能板
                                 "Air780EHM_LCD_4"(自带3.5寸480*320触摸屏，矢量字库，tf卡槽)
                             3、支持触摸IC型号
                                 "gt911"、"cst820"、"gt9157"、"jd9261t"、"ft3x68"
                    注意事项：必须使用支持的型号，否则初始化失败
                    参数示例：tp_model =  "Air780EHM_LCD_4"
                    tp_model =  ,

                    参数含义：I2C通信端口，可以是硬件I2C的ID号（number类型）或软件I2C对象（userdata类型）
                    数据类型：number类型或userdata类型
                    是否必选：是
                    取值范围：有效的硬件I2C的ID号或由i2c.createSoft创建的软件I2C对象
                    注意事项：需要先使用i2c.setup初始化对应的I2C总线；
                             如果不知道所接引脚对应是哪个GPIO，可以查看对应型号的引脚（管脚）复用表，
                             或者可以使用[LuatIO引脚复用配置工具](https://docs.openluat.com/air780epm/common/luatio/)，参照说明查看对应型号的管脚默认定义；
                    参数示例：i2c_id =  1（硬件I2C端口1）或i2c_id = i2c.createSoft(20, 21)（软件I2C对象）
                    i2c_id =  ,

                    参数含义：触摸芯片复位引脚GPIO的ID
                    数据类型：number
                    是否必选：是
                    取值范围：有效的GPIO的ID，若屏幕实际未引出触摸芯片RST引脚，
                             则可以写成255一个不存在的且符合number类型的引脚；
                    注意事项：引脚需要正确连接到触摸芯片的复位引脚
                    参数示例：pin_rst =  20
                    pin_rst =  ,

                    参数含义：触摸芯片中断输入到SOC的引脚
                    数据类型：number
                    是否必选：是
                    取值范围：支持设置为输入模式的GPIO的ID和gpio.WEKEUP引脚
                    注意事项：引脚需要正确连接到触摸芯片的中断输出引脚
                    参数示例：pin_int =  22
                    pin_int =  ,

                    参数含义：屏幕宽度像素值
                    数据类型：number
                    是否必选：否
                    取值范围：大于0的整数，省略此参数则默认值自动从已初始化的LCD获取，
                    注意事项：填非正整数会报错重启
                    参数示例：320
                    w =  ,

                    参数含义：屏幕高度像素值
                    数据类型：number
                    是否必选：否
                    取值范围：大于0的整数，省略此参数则默认值自动从已初始化的LCD获取，
                    注意事项：填非正整数会报错重启
                    参数示例：240
                    h =  ,

                    参数含义：消息发布状态配置
                    数据类型：table
                    取值范围：包含消息类型和启用状态的键值对
                    是否必选：可选
                    注意事项：可配置"RAW_DATA"、"TOUCH_DOWN"、"MOVE_X"、"MOVE_Y"、
                             "SWIPE_LEFT"、"SWIPE_RIGHT"、"SWIPE_UP"、"SWIPE_DOWN"、
                             "SINGLE_TAP"、"LONG_PRESS"、"ALL"
                    参数示例：{SINGLE_TAP = true, LONG_PRESS = true}
                    message_enabled =  ,

                    参数含义：滑动判定阈值
                    数据类型：number
                    取值范围：必须大于0的数值，单位像素
                    是否必选：可选
                    注意事项：默认10像素，设置过小可能导致过于灵敏
                    参数示例：10
                    swipe_threshold =  ,

                    参数含义：长按判定阈值
                    数据类型：number
                    取值范围：必须大于0的数值，单位毫秒
                    是否必选：可选
                    注意事项：默认2000毫秒，设置过小可能导致长按被误识别为单击
                    参数示例：2000
                    long_press_threshold =  ,
                }，
        是否必选：必须
        注意事项：触摸配置为必须项，用于初始化触摸设备
        tp_config =  ,

        参数含义：启用帧缓冲区
        数据类型：boolean
        取值范围：true（启用）, false（禁用）
        是否必选：可选
        注意事项：默认启用
        参数示例：true
        enable_buffer =  ,

        参数含义：启用硬件JPG解码
        数据类型：boolean
        取值范围：true（启用）, false（禁用）
        是否必选：可选
        注意事项：默认禁用
        参数示例：false
        enable_hardware_decode =  ,

        参数含义：字体配置参数表
        数据类型：table
        取值范围：包含以下可选子参数：
                {
                    参数含义：字体后端类型
                    数据类型：string
                    取值范围：取值范围："hzfont"（内置矢量字体库）, "default"（内置字体）
                    是否必选：可选
                    注意事项：不设置时默认使用"default"，显示为12号中文字体
                    参数示例："hzfont"
                    type =  ,

                    参数含义：字体大小
                    数据类型：number
                    取值范围：大于0的整数
                    是否必选：可选
                    注意事项：在"hzfont"模式下有效，默认16
                    参数示例：16
                    size =  ,

                    参数含义：字体缓存大小
                    数据类型：number
                    取值范围：HZFONT_CACHE_128、HZFONT_CACHE_256、HZFONT_CACHE_512、HZFONT_CACHE_1024、HZFONT_CACHE_2048
                    是否必选：可选
                    注意事项：仅当type为"hzfont"时有效，默认为HZFONT_CACHE_256
                    参数示例：HZFONT_CACHE_256
                    cache_size =  ,

                    参数含义：抗锯齿级别
                    数据类型：number
                    取值范围：-1、1、2、4
                    是否必选：可选
                    注意事项：仅当type为"hzfont"时有效，-1表示不使用抗锯齿，默认-1
                    参数示例：2
                    antialias =  ,

                    参数含义：是否启用灰度渲染
                    数据类型：boolean
                    取值范围：true（启用）, false（禁用）
                    是否必选：可选
                    注意事项：暂无
                    参数示例：true
                    gray =  ,

                    参数含义：SPI通信配置
                    数据类型：table
                    取值范围：包含以下子参数：
                            {
                                参数含义：SPI的ID号
                                数据类型：number
                                取值范围：0, 1, 2等有效SPI端口
                                是否必选：否
                                注意事项：如果使用软件SPI，则这里传入软件SPI对象
                                参数示例：1
                                id =  ,

                                参数含义：SPI片选引脚
                                数据类型：number
                                取值范围：有效GPIO引脚号
                                是否必选：否
                                注意事项：暂无
                                参数示例：12
                                cs =  ,
                            }
                    是否必选：可选
                    注意事项：暂无
                    spi =  ,
                }                        
        是否必选：可选
        注意事项：暂无
        font_config =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：可选
注意事项：硬件初始化必须在其他UI操作之前调用

返回值

local hwinit_result = ui.hw_init(opts)

hwinit_result

含义说明：硬件初始化结果
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：初始化失败时后续UI操作可能异常
返回示例：true

示例 1： AirLCD_1010 搭配 Air8000 整机开发板初始化

-- 初始化exeasyui 硬件，默认开启缓冲区设置，禁用jpg图片硬件解码，使用12号中文字体

-- AirLCD_1010搭配Air8000整机开发板初始化
local success = ui.hw_init({
    -- lcd_config参数填写可以参考合宙exlcd显示扩展库exlcd.init(param)接口说明：https://docs.openluat.com/osapi/ext/exlcd/#31-exlcdinitparam
    lcd_config = 
    {
        lcd_model = "AirLCD_1010", -- LCD型号
    },

    -- tp_config参数填写可以参考合宙extp触摸扩展库以下三个接口说明：https://docs.openluat.com/osapi/ext/extp/#41-extpinitparam
    -- 按extp.init(param)接口说明填写tp_model、i2c_id、pin_rst、pin_int参数
    -- 按extp.set_publish_enabled(msg_type, enabled)接口说明和实际需求填写message_enabled{}列表内参数
    -- 按extp.set_swipe_threshold(threshold)接口说明填写swipe_threshold和long_press_threshold参数
    tp_config = 
    {
        tp_model = "AirLCD_1010", -- 触摸芯片/设备型号

        -- @param message_enabled 消息类型 ("ALL", "RAW_DATA", "TOUCH_DOWN", "MOVE_X", "MOVE_Y", "SWIPE_LEFT", "SWIPE_RIGHT", "SWIPE_UP", "SWIPE_DOWN", "SINGLE_TAP", "LONG_PRESS")
        message_enabled = 
        {
            TOUCH_DOWN = true,      -- 启用按下检测
            MOVE_X = true,          -- 启用横向滑动
            MOVE_Y = true,          -- 启用纵向滑动
            SWIPE_LEFT = true,      -- 启用左滑手势
            SWIPE_RIGHT = true,     -- 启用右滑手势
            SWIPE_UP = true,        -- 启用上滑手势
            SWIPE_DOWN = true,      -- 启用下滑手势
            SINGLE_TAP = true,      -- 启用点击手势
            LONG_PRESS = false      -- 禁用长按手势
        },
        swipe_threshold = 10,       -- 设置滑动阈值
        long_press_threshold = 2000 -- 设置长按阈值（毫秒）
    }
})

if success then
    log.info("硬件初始化成功")
else
    log.error("硬件初始化失败")
end

示例 2： AirLCD_1010 搭配 Air8000 核心板，自定义参数初始化

-- AirLCD_1010搭配Air8000核心板，自定义参数初始化
local success = ui.hw_init({
    -- lcd_config参数填写可以参考合宙exlcd显示扩展库exlcd.init(param)接口说明：https://docs.openluat.com/osapi/ext/exlcd/#31-exlcdinitparam
    lcd_config = 
    {
        lcd_model = "AirLCD_1000", -- LCD型号
        pin_vcc = 29,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 30,          -- 背光控制引脚GPIO的ID号
        pin_pwm = 1,          -- 背光控制引脚PWM的ID号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
    },

    -- tp_config参数填写可以参考合宙extp触摸扩展库以下三个接口说明：https://docs.openluat.com/osapi/ext/extp/#41-extpinitparam
    -- 按extp.init(param)接口说明填写tp_model、i2c_id、pin_rst、pin_int参数
    -- 按extp.set_publish_enabled(msg_type, enabled)接口说明和实际需求填写message_enabled{}列表内参数
    -- 按extp.set_swipe_threshold(threshold)接口说明填写swipe_threshold和long_press_threshold参数
    tp_config = 
    {
        tp_model = "AirLCD_1010", -- LCD型号
        i2c_id = 0,
        pin_rst = 255,
        pin_int = gpio.WAKEUP0
        -- @param message_enabled 消息类型 ("ALL", "RAW_DATA", "TOUCH_DOWN", "MOVE_X", "MOVE_Y", "SWIPE_LEFT", "SWIPE_RIGHT", "SWIPE_UP", "SWIPE_DOWN", "SINGLE_TAP", "LONG_PRESS")
        message_enabled = 
        {
            TOUCH_DOWN = true,      -- 启用按下检测
            MOVE_X = true,          -- 启用横向滑动
            MOVE_Y = true,          -- 启用纵向滑动
            SWIPE_LEFT = true,      -- 启用左滑手势
            SWIPE_RIGHT = true,     -- 启用右滑手势
            SWIPE_UP = true,        -- 启用上滑手势
            SWIPE_DOWN = true,      -- 启用下滑手势
            SINGLE_TAP = true,      -- 启用点击手势
            LONG_PRESS = false      -- 禁用长按手势
        },
        swipe_threshold = 10,       -- 设置滑动阈值
        long_press_threshold = 2000 -- 设置长按阈值（毫秒）
    }
})

if success then
    log.info("硬件初始化成功")
else
    log.error("硬件初始化失败")
end

示例 3：Air8101 搭配核心板 Air1020 自定义参数初始化

-- Air8101搭配核心板Air1020自定义参数初始化
local success = ui.hw_init({
    -- lcd_config参数填写可以参考合宙exlcd显示扩展库exlcd.init(param)接口说明：https://docs.openluat.com/osapi/ext/exlcd/#31-exlcdinitparam
    lcd_config = 
    {
        lcd_model = "AirLCD_1020",    -- LCD型号
        pin_pwr = 8,                  -- 背光控制引脚GPIO的ID号
        pin_pwm = 0,                  -- 背光控制引脚PWM的ID号
        port = lcd.RGB,               -- 驱动端口
        direction = 0,                -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 800,                      -- lcd 水平分辨率
        h = 480,                      -- lcd 竖直分辨率
        xoffset = 0,                  -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,                  -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        bus_speed = 30 * 1000 * 1000, -- SPI总线速度,不填默认50M，若速率要求更高需要进行设置
        hbp = 8,                      -- 水平后廊
        hspw = 4,                     -- 水平同步脉冲宽度
        hfp = 8,                      -- 水平前廊
        vbp = 16,                     -- 垂直后廊
        vspw = 4,                     -- 垂直同步脉冲宽度
        vfp = 16,                     -- 垂直前廊
    },

    -- tp_config参数填写可以参考合宙extp触摸扩展库以下三个接口说明：https://docs.openluat.com/osapi/ext/extp/#41-extpinitparam
    -- 按extp.init(param)接口说明填写tp_model、i2c_id、pin_rst、pin_int参数
    -- 按extp.set_publish_enabled(msg_type, enabled)接口说明和实际需求填写message_enabled{}列表内参数
    -- 按extp.set_swipe_threshold(threshold)接口说明填写swipe_threshold和long_press_threshold参数
    tp_config = 
    {
        tp_model = "AirLCD_1020", -- LCD型号
        i2c_id = i2c.createSoft(0, 1), --软件I2C触摸
        pin_rst = 28,
        pin_int = 7
        -- @param message_enabled 消息类型 ("ALL", "RAW_DATA", "TOUCH_DOWN", "MOVE_X", "MOVE_Y", "SWIPE_LEFT", "SWIPE_RIGHT", "SWIPE_UP", "SWIPE_DOWN", "SINGLE_TAP", "LONG_PRESS")
        message_enabled = 
        {
            TOUCH_DOWN = true,      -- 启用按下检测
            MOVE_X = true,          -- 启用横向滑动
            MOVE_Y = true,          -- 启用纵向滑动
            SWIPE_LEFT = true,      -- 启用左滑手势
            SWIPE_RIGHT = true,     -- 启用右滑手势
            SWIPE_UP = true,        -- 启用上滑手势
            SWIPE_DOWN = true,      -- 启用下滑手势
            SINGLE_TAP = true,      -- 启用点击手势
            LONG_PRESS = false      -- 禁用长按手势
        },
        swipe_threshold = 10,       -- 设置滑动阈值
        long_press_threshold = 2000 -- 设置长按阈值（毫秒）
    }
})

if success then
    log.info("硬件初始化成功")
else
    log.error("硬件初始化失败")
end

示例 4： LCD 量产功能板初始化

-- LCD 量产功能板初始化，不支持修改lcd_config和tp_config默认参数
local success = ui.hw_init({
    lcd_config = 
    {
        lcd_model = "Air780EHM_LCD_4",    -- LCD型号
    },
    tp_config = 
    {
        tp_model = "Air780EHM_LCD_4", -- LCD型号
        -- @param message_enabled 消息类型 ("ALL", "RAW_DATA", "TOUCH_DOWN", "MOVE_X", "MOVE_Y", "SWIPE_LEFT", "SWIPE_RIGHT", "SWIPE_UP", "SWIPE_DOWN", "SINGLE_TAP", "LONG_PRESS")
        message_enabled = 
        {
            TOUCH_DOWN = true,      -- 启用按下检测
            MOVE_X = true,          -- 启用横向滑动
            MOVE_Y = true,          -- 启用纵向滑动
            SWIPE_LEFT = true,      -- 启用左滑手势
            SWIPE_RIGHT = true,     -- 启用右滑手势
            SWIPE_UP = true,        -- 启用上滑手势
            SWIPE_DOWN = true,      -- 启用下滑手势
            SINGLE_TAP = true,      -- 启用点击手势
            LONG_PRESS = false      -- 禁用长按手势
        },
        swipe_threshold = 10,       -- 设置滑动阈值
        long_press_threshold = 2000 -- 设置长按阈值（毫秒）
    }
})

if success then
    log.info("硬件初始化成功")
else
    log.error("硬件初始化失败")
end

示例 5：驱动 ic 型号初始化

-- 驱动 ic 型号初始化
local success = ui.hw_init({
    -- lcd_config参数填写可以参考合宙exlcd显示扩展库exlcd.init(param)接口说明：https://docs.openluat.com/osapi/ext/exlcd/#31-exlcdinitparam
    lcd_config = 
    {
        lcd_model = "st7796", -- LCD型号
        pin_vcc = 24,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 1,          -- 背光控制引脚GPIO端口号
        pin_pwm = 0,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
    },

    -- tp_config参数填写可以参考合宙extp触摸扩展库以下三个接口说明：https://docs.openluat.com/osapi/ext/extp/#41-extpinitparam
    -- 按extp.init(param)接口说明填写tp_model、i2c_id、pin_rst、pin_int参数
    -- 按extp.set_publish_enabled(msg_type, enabled)接口说明和实际需求填写message_enabled{}列表内参数
    -- 按extp.set_swipe_threshold(threshold)接口说明填写swipe_threshold和long_press_threshold参数
    tp_config = 
    {
        tp_model = "gt911", -- LCD型号
        i2c_id = 0,
        pin_rst = 28,
        pin_int = 20
        -- @param message_enabled 消息类型 ("ALL", "RAW_DATA", "TOUCH_DOWN", "MOVE_X", "MOVE_Y", "SWIPE_LEFT", "SWIPE_RIGHT", "SWIPE_UP", "SWIPE_DOWN", "SINGLE_TAP", "LONG_PRESS")
        message_enabled = 
        {
            TOUCH_DOWN = true,      -- 启用按下检测
            MOVE_X = true,          -- 启用横向滑动
            MOVE_Y = true,          -- 启用纵向滑动
            SWIPE_LEFT = true,      -- 启用左滑手势
            SWIPE_RIGHT = true,     -- 启用右滑手势
            SWIPE_UP = true,        -- 启用上滑手势
            SWIPE_DOWN = true,      -- 启用下滑手势
            SINGLE_TAP = true,      -- 启用点击手势
            LONG_PRESS = false      -- 禁用长按手势
        },
        swipe_threshold = 10,       -- 设置滑动阈值
        long_press_threshold = 2000 -- 设置长按阈值（毫秒）
    }
})

if success then
    log.info("硬件初始化成功")
else
    log.error("硬件初始化失败")
end

示例 6：custom 方式初始化

-- custom方式初始化
local success = ui.hw_init({
    -- lcd_config参数填写可以参考合宙exlcd显示扩展库exlcd.init(param)接口说明：https://docs.openluat.com/osapi/ext/exlcd/#31-exlcdinitparam
    lcd_config = 
    {
        lcd_model = "custom", -- LCD型号
        pin_vcc = 24,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 1,          -- 背光控制引脚GPIO端口号
        pin_pwm = 0,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
        -- ST7796S专用初始化命令序列
        initcmd = {
            -- 命令格式说明：
            -- 0x01xxxx: 延时，xxxx为延时ms时间
            -- 0x02xxxx: 命令，xxxx为命令码
            -- 0x03xxxx: 数据，xxxx为参数值

            -- 1. 设置接口像素格式
            0x02003A, 0x030005,
            -- 命令0x3A: 设置像素格式为16位RGB565 (参数0x05)

            -- 2. 帧率控制2 - 空闲模式
            0x0200B2, 0x03000C, 0x03000C, 0x030000, 0x030033, 0x030033,
            -- 设置空闲模式下的帧率参数

            -- 3. 门控制
            0x0200B7, 0x030035,
            -- 设置门控参数，控制扫描行数

            -- 4. VCOM设置
            0x0200BB, 0x030032,
            -- 设置VCOM电压值，影响对比度

            -- 5. 电源控制3
            0x0200C2, 0x030001,
            -- 设置电源控制参数3

            -- 6. 电源控制4
            0x0200C3, 0x030015,
            -- 设置VCOMH电压

            -- 7. 电源控制5
            0x0200C4, 0x030020,
            -- 设置VCOML电压

            -- 8. VCOM偏移控制
            0x0200C6, 0x03000F,
            -- 设置VCOM偏移量

            -- 9. 电源控制1
            0x0200D0, 0x0300A4, 0x0300A1,
            -- 设置主要的电源控制参数

            -- 10. 正伽马校正
            0x0200E0, 0x0300D0, 0x030008, 0x03000E, 0x030009, 0x030009, 
            0x030005, 0x030031, 0x030033, 0x030048, 0x030017, 0x030014, 
            0x030015, 0x030031, 0x030034,
            -- 15个参数点，校正亮部色彩曲线

            -- 11. 负伽马校正
            0x0200E1, 0x0300D0, 0x030008, 0x03000E, 0x030009, 0x030009, 
            0x030015, 0x030031, 0x030033, 0x030048, 0x030017, 0x030014, 
            0x030015, 0x030031, 0x030034,
            -- 15个参数点，校正暗部色彩曲线
    },

    -- tp_config参数填写可以参考合宙extp触摸扩展库以下三个接口说明：https://docs.openluat.com/osapi/ext/extp/#41-extpinitparam
    -- 按extp.init(param)接口说明填写tp_model、i2c_id、pin_rst、pin_int参数
    -- 按extp.set_publish_enabled(msg_type, enabled)接口说明和实际需求填写message_enabled{}列表内参数
    -- 按extp.set_swipe_threshold(threshold)接口说明填写swipe_threshold和long_press_threshold参数
    tp_config = 
    {
        tp_model = "gt911", -- LCD型号
        i2c_id = 0,
        pin_rst = 28,
        pin_int = 20
        -- @param message_enabled 消息类型 ("ALL", "RAW_DATA", "TOUCH_DOWN", "MOVE_X", "MOVE_Y", "SWIPE_LEFT", "SWIPE_RIGHT", "SWIPE_UP", "SWIPE_DOWN", "SINGLE_TAP", "LONG_PRESS")
        message_enabled = 
        {
            TOUCH_DOWN = true,      -- 启用按下检测
            MOVE_X = true,          -- 启用横向滑动
            MOVE_Y = true,          -- 启用纵向滑动
            SWIPE_LEFT = true,      -- 启用左滑手势
            SWIPE_RIGHT = true,     -- 启用右滑手势
            SWIPE_UP = true,        -- 启用上滑手势
            SWIPE_DOWN = true,      -- 启用下滑手势
            SINGLE_TAP = true,      -- 启用点击手势
            LONG_PRESS = false      -- 禁用长按手势
        },
        swipe_threshold = 10,       -- 设置滑动阈值
        long_press_threshold = 2000 -- 设置长按阈值（毫秒）
    }
})

if success then
    log.info("硬件初始化成功")
else
    log.error("硬件初始化失败")
end

示例 7：14 号固件内置 HZFont 矢量字体初始化

-- 14号固件内置HZFont矢量字体初始化
local success = ui.hw_init({
    font_config = { type = "hzfont", size = 24, antialias = -1 }, -- 默认-1，表示自动抗锯齿
    -- lcd_config参数填写可以参考合宙exlcd显示扩展库exlcd.init(param)接口说明：https://docs.openluat.com/osapi/ext/exlcd/#31-exlcdinitparam
    lcd_config = 
    {
        lcd_model = "st7796", -- LCD型号
        pin_vcc = 24,         -- 供电引脚，使用GPIO控制屏幕供电可配置
        pin_rst = 36,         -- 复位引脚
        pin_pwr = 1,          -- 背光控制引脚GPIO端口号
        pin_pwm = 0,          -- 背光控制引脚PWM端口号
        port = lcd.HWID_0,    -- 驱动端口
        direction = 0,        -- lcd屏幕方向 0:0° 1:90° 2:180° 3:270°，屏幕方向和分辨率保存一致
        w = 320,              -- lcd 水平分辨率
        h = 480,              -- lcd 竖直分辨率
        xoffset = 0,          -- x偏移(不同屏幕ic 不同屏幕方向会有差异)
        yoffset = 0,          -- y偏移(不同屏幕ic 不同屏幕方向会有差异)
        sleepcmd = 0X10,      -- 睡眠命令，默认0X10
        wakecmd = 0X11,       -- 唤醒命令，默认0X11
    },

    -- tp_config参数填写可以参考合宙extp触摸扩展库以下三个接口说明：https://docs.openluat.com/osapi/ext/extp/#41-extpinitparam
    -- 按extp.init(param)接口说明填写tp_model、i2c_id、pin_rst、pin_int参数
    -- 按extp.set_publish_enabled(msg_type, enabled)接口说明和实际需求填写message_enabled{}列表内参数
    -- 按extp.set_swipe_threshold(threshold)接口说明填写swipe_threshold和long_press_threshold参数
    tp_config = 
    {
        tp_model = "gt911", -- LCD型号
        i2c_id = 0,
        pin_rst = 28,
        pin_int = 20
        -- @param message_enabled 消息类型 ("ALL", "RAW_DATA", "TOUCH_DOWN", "MOVE_X", "MOVE_Y", "SWIPE_LEFT", "SWIPE_RIGHT", "SWIPE_UP", "SWIPE_DOWN", "SINGLE_TAP", "LONG_PRESS")
        message_enabled = 
        {
            TOUCH_DOWN = true,      -- 启用按下检测
            MOVE_X = true,          -- 启用横向滑动
            MOVE_Y = true,          -- 启用纵向滑动
            SWIPE_LEFT = true,      -- 启用左滑手势
            SWIPE_RIGHT = true,     -- 启用右滑手势
            SWIPE_UP = true,        -- 启用上滑手势
            SWIPE_DOWN = true,      -- 启用下滑手势
            SINGLE_TAP = true,      -- 启用点击手势
            LONG_PRESS = false      -- 禁用长按手势
        },
        swipe_threshold = 10,       -- 设置滑动阈值
        long_press_threshold = 2000 -- 设置长按阈值（毫秒）
    }
})

if success then
    log.info("硬件初始化成功")
else
    log.error("硬件初始化失败")
end

4.1.2 ui.sw_init(opts)

功能

初始化 exeasyui 系统，配置主题和事件处理系统。

参数

opts

参数含义：系统配置参数表
数据类型：table
是否必选：可选
取值范围：包含以下可选子参数：
        {
            参数含义：设置UI主题模式
            数据类型：string
            取值范围："light"（浅色模式）, "dark"（深色模式）
            是否必选：可选
            注意事项：不设置时默认使用"dark"深色模式
            参数示例："light"
            theme =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：可选
注意事项：所有参数均为可选，不传入opts时使用默认配置

返回值

无

示例

-- 初始化exeasyui系统
ui.sw_init(
    {
        theme = "light", -- 使用浅色主题
    }
)

4.1.3 ui.add(component)

功能

将 UI 组件添加到 exeasyui 的渲染队列，会根据父组件索引对应的子组件状态，然后自动渲染出来。

参数

component

参数含义：要添加UI组件对象
数据类型：table
是否必选：是
取值范围：通过ui.window、ui.button、ui.label等构造函数创建的对象
注意事项：
参数示例：button_component

返回值

无

示例 1 在 exeasyui 中添加 window 组件

-- 创建window（窗口容器），设置背景为黑色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })
ui.add(page1)

示例 2 在 exeasyui 中添加 button 组件

local button = ui.button({x=10, y=10, w=100, h=36, text="测试按钮"})
ui.add(button)

4.1.4 ui.remove(component)

功能

从渲染队列中移除 UI 组件。

参数

component

参数含义：要移除的UI组件对象
数据类型：table
是否必选：是
取值范围：已通过ui.add添加的组件对象
注意事项：移除后组件将不再被渲染和响应事件
参数示例：button_component

返回值

local remove_result = ui.remove(component)

remove_result

含义说明：移除操作结果
数据类型：boolean
取值范围：true（成功移除）, false（未找到组件）
注意事项：无
返回示例：true

示例

local button = ui.button({x=10, y=10, w=100, h=36, text="测试按钮"})
ui.add(button)

-- 稍后移除按钮
local result = ui.remove(button)
if result then
    log.info("按钮移除成功")
end

4.1.5 ui.clear(color)

功能

清空屏幕并填充指定颜色。

参数

color

参数含义：清屏颜色
数据类型：number
是否必选：可选
取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值;
注意事项：不传入时默认使用黑色
参数示例：ui.COLOR_WHITE

返回值

无

示例

-- 清屏为白色
ui.clear(ui.COLOR_WHITE)

-- 清屏为默认黑色
ui.clear()

4.1.6 ui.debug(enabled)

功能

配置调试模式开关，默认关闭，开启后会出现渲染时间、触摸坐标等日志信息。

参数

enabled

参数含义：调试配置
数据类型：boolean
是否必选：可选
取值范围：true或false
注意事项：暂无
参数示例：true

返回值

无

示例

-- 启用调试信息（默认）
ui.debug(true)

-- 关闭所有调试
ui.debug(false)

-- 查询当前调试状态
-- 注意：此接口主要用于控制TP消息等调试信息的输出

4.1.7 ui.theme()

功能

获取当前 UI 主题模式。

参数

无

返回值

local current_theme = ui.theme()

current_theme

含义说明：当前主题模式
数据类型：string
取值范围："light", "dark"
注意事项：无
返回示例："dark"

示例

local theme = ui.theme()
log.info("当前主题", theme)

4.2 组件构造函数及构造后使用方法

4.2.1 ui.window(opts)

功能

创建窗口容器组件，支持子组件管理和页面导航。

参数

opts

参数含义：窗口配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：窗口左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：可选
            注意事项：默认0（全屏）
            参数示例：0
            x =  ,

            参数含义：窗口左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：可选
            注意事项：默认0（全屏）
            参数示例：0
            y =  ,

            参数含义：窗口宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认屏幕宽度
            参数示例：320
            w =  ,

            参数含义：窗口高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认屏幕高度
            参数示例：240
            h =  ,

            参数含义：窗口背景图片路径
            数据类型：string
            取值范围：有效的JPG文件路径
            是否必选：可选
            注意事项：与background_color背景色参数互斥
            参数示例："/luadb/bg.jpg"
            background_image=  ,

            参数含义：窗口背景颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLACK
            background_color =  ,

            参数含义：窗口是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：窗口是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：禁用时不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：窗口通常作为其他组件的容器使用

返回值

local win_component = ui.window(opts)

win_component

含义说明：窗口组件对象
数据类型：table
取值范围：包含draw、handle_event、add、remove等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：win_object

示例

ui = require("exeasyui")

-- 创建窗口
local win = ui.window({
    background_color = ui.COLOR_BLACK
})

-- 配置子页面
win:configure_subpages({
    page1 = function() return ui.window({background_color = ui.COLOR_RED}) end,
    page2 = function() return ui.window({background_color = ui.COLOR_BLUE}) end
})

-- 显示子页面
win:show_subpage("page1")

sys.wait(3000)
win:show_subpage("page2")

ui.add(win)

4.2.1.1 window:add(child)

功能

向 window 组件添加一个子组件。

参数

child

参数含义：要添加的组件实例
数据类型：table
是否必选：是
取值范围：任何实现了draw和handle_event方法的组件对象
注意事项：组件必须通过ui.button、ui.label等构造函数创建
参数示例：button_object

返回值

无

示例

ui = require("exeasyui")

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

-- 创建一个button（按钮）文本模式，显示在（20.20）位置，命名为btn1
local btn1 = ui.button({ x = 20, y = 20})

-- 将btn1添加到page1内
page1:add(btn1)

4…2.1.2 window:remove(child)

功能

从窗口中移除一个已添加的子组件。

参数

child

参数含义：要移除的组件实例
数据类型：table
是否必选：是
取值范围：已通过add方法添加到窗口的组件对象
注意事项：移除后组件将不再被渲染和响应事件
参数示例：button_object

返回值

local remove_result = window:remove(child)

remove_result

含义说明：移除操作结果
数据类型：boolean
取值范围：true（成功移除）, false（未找到组件）
注意事项：无
返回示例：true

示例

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

-- 创建一个button（按钮）文本模式，显示在（20.20）位置，命名为btn1
local btn1 = ui.button({ x = 20, y = 20})

local remove_result = page1:remove(btn1)

if remove_result then
    [log.info](https://log.info/)("组件btn1移除成功")
end

4.2.1.3 window:clear()

功能

清空窗口的所有子组件。

参数

无

返回值

无

示例

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

-- 清除名为page1的window（窗口容器）中的子组件
page1:clear()

4.2.1.4 window:set_background_image(path)

功能

设置窗口背景图片。

参数

path

参数含义：背景图片文件路径
数据类型：string
是否必选：是
取值范围：有效的JPG文件路径
注意事项：设置背景图片会覆盖背景颜色
参数示例："/luadb/wallpaper.jpg"

返回值

无

示例

ui = require("exeasyui")

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

page1:set_background_image("/luadb/background.jpg")

4.2.1.5 window:set_background_color(color)

功能

设置窗口背景颜色，并清除已设置的背景图片。

参数

color

参数含义：背景颜色值
数据类型：number
是否必选：是
取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值，
注意事项：设置背景颜色会清除背景图片
参数示例：ui.COLOR_WHITE

返回值

无

示例

ui = require("exeasyui")

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

page1:set_background_color(ui.COLOR_BLACK)

4.2.1.6 window:enable_scroll(opts)

功能

启用窗口内容的滑动跟随效果或者页面滑动切换效果。

参数

opts

参数含义：滚动/分页配置参数表
数据类型：table
是否必选：可选
取值范围：包含以下子参数：
        {
            参数含义：滚动方向，启用后实现窗口内组件实现滑动跟随效果
            数据类型：string
            取值范围："vertical"（纵向）, "horizontal"（横向）, "both"（双向）
            是否必选：可选
            注意事项：默认"vertical"
            参数示例："vertical"
            direction = ,

            参数含义：内容区域总宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认等于窗口宽度
            参数示例：640
            content_width=  ,

            参数含义：内容区域总高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认等于窗口高度
            参数示例：1200
            content_height =  ,

            参数含义：拖拽判定阈值
            数据类型：number
            取值范围：大于0的整数，单位像素
            是否必选：可选
            注意事项：默认10像素
            参数示例：8
            threshold =  ,

            参数含义：是否启用页面跳转
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：启用后默认窗口内组件滑动跟随效果失效
            参数示例：true
            snap_to_page =  ,

            参数含义：分页宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认等于窗口宽度
            参数示例：320
            page_width =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：可选
注意事项：所有参数均为可选

返回值

local win_self = win:enable_scroll(opts)

win_self

含义说明：窗口自身对象
数据类型：table
取值范围：窗口组件对象
注意事项：支持链式调用
返回示例：win_object

示例

ui = require("exeasyui")

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

-- 纵向滚动
page1:enable_scroll({
    direction = "vertical",
    content_height = 1200,
    threshold = 8
})

-- 横向分页
page1:enable_scroll({
    direction = "horizontal",
    enabled = true,
    page_width = 320,
    content_width = 960
})

4.2.1.7 window:set_content_size(w, h)

功能

设置内容区域尺寸，影响滚动边界的计算。

参数

w

参数含义：内容区域宽度
数据类型：number
是否必选：可选
取值范围：大于0的整数
注意事项：至少提供w或h其中一个参数
参数示例：640

h

参数含义：内容区域高度
数据类型：number
是否必选：可选
取值范围：大于0的整数
注意事项：至少提供w或h其中一个参数
参数示例：1200

返回值

无

示例

ui = require("exeasyui")

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

page1:set_content_size(320, 1200)
page1:set_content_size(640) -- 只设置宽度
page1:set_content_size(nil, 800) -- 只设置高度

4.2.1.8 window:enable_subpage_manager(opts)

功能

启用子页面管理能力，注册返回事件及回调函数。

参数

opts

参数含义：子页面管理配置参数表
数据类型：table
是否必选：可选
取值范围：包含以下子参数：
        {
            参数含义：返回事件名称
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：默认"NAV.BACK"
            参数示例："NAV_BACK"
            back_event_name = ,

            参数含义：返回事件回调函数
            数据类型：function
            取值范围：格式为function() end的函数
            是否必选：可选
            注意事项：在父窗口范围内调用
            参数示例：function() log.info("返回按钮点击") end
            on_back =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：可选
注意事项：通常只需要调用一次

返回值

local win_self = win:enable_subpage_manager(opts)

win_self

含义说明：窗口自身对象
数据类型：table
取值范围：窗口组件对象
注意事项：支持链式调用
返回示例：win_object

示例

ui = require("exeasyui")

-- 创建window（窗口容器），设置背景为白色，命名为page1
local page1 = ui.window({ background_color = ui.COLOR_WHITE })

page1:enable_subpage_manager({
    back_event_name = "NAV_BACK",
    on_back = function()
        log.info("导航返回")
    end
})

4.2 1.9 window:configure_subpages(factories)

功能

注册子页面工厂函数表。

参数

factories

参数含义：子页面工厂函数表
数据类型：table
是否必选：是
取值范围：键值对表，键为子页面名称，值为返回window对象的函数
注意事项：工厂函数应返回一个window实例
参数示例：{settings = function() return settings_window end}

返回值

local win_self = window:configure_subpages(factories)

win_self

含义说明：窗口自身对象
数据类型：table
取值范围：窗口组件对象
注意事项：支持链式调用
返回示例：win_object

示例

-- 引入exeasyui库
local ui = require("exeasyui")

-- 创建一个msgbox_page页面的函数
-- 这个函数用于创建消息框演示页面
local function msgbox_page()
    -- 创建一个白色背景的窗口容器
    local win = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建"返回"按钮
    local back = ui.button({
        x = 220, y = 140,        -- 按钮位置（在弹出按钮右边）
        w = 80, h = 50,          -- 按钮尺寸
        text = "返回",           -- 按钮文字
        -- 按钮点击事件：返回上一级页面
        on_click = function()
            win:back()  -- 调用窗口的back方法返回主页
        end
    })

    -- 将组件添加到窗口中
    win:add(back)   -- 添加返回按钮

    return win      -- 返回创建好的窗口对象
end

-- 主程序入口函数
local function exeasyui_demo()
    -- 等待500毫秒，确保系统初始化完成
    sys.wait(500)

    -- 初始化硬件（lcd显示屏和触摸屏）
    ui.hw_init({})

    -- 初始化UI系统，设置主题为浅色模式
    ui.sw_init({ theme = "light" })

    -- 创建主页面窗口（白色背景）
    local home = ui.window({ background_color = ui.COLOR_WHITE })

    -- 配置子页面工厂函数
    -- 这里注册了两个子页面："page1"对应消息框页面，"page2"对应复选框页面
    home:configure_subpages({ 
        page1 = msgbox_page,   -- 消息框演示页面
    })

    -- 创建导航按钮2：进入消息框示例页面  
    local btn2 = ui.button({
        x = 20, y = 130,   -- 按钮位置（在第一个按钮下方）
        w = 280, h = 50,   -- 按钮尺寸
        text = "消息框示例", -- 按钮文字
        on_click = function()
            -- 点击后显示消息框示例页面
            home:show_subpage("page1")
        end
    })

    -- 将按钮添加到主页面
    home:add(btn2)         -- 消息框示例按钮

    -- 将主页面添加到UI渲染系统
    ui.add(home)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

4.2.1.10 window:show_subpage(name, factory)

功能

显示指定名称的子页面。

参数

name

参数含义：子页面名称
数据类型：string
是否必选：是
取值范围：已通过configure_subpages注册的名称或任意字符串
注意事项：如果名称未注册，需要提供factory参数
参数示例："settings"

factory

参数含义：备用工厂函数
数据类型：function
是否必选：可选
取值范围：返回window对象的函数
注意事项：当name未注册时使用
参数示例：function() return settings_window end

返回值

无

示例

-- 引入exeasyui库
local ui = require("exeasyui")

-- 创建一个msgbox_page页面的函数
-- 这个函数用于创建消息框演示页面
local function msgbox_page()
    -- 创建一个白色背景的窗口容器
    local win = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建"返回"按钮
    local back = ui.button({
        x = 220, y = 140,        -- 按钮位置（在弹出按钮右边）
        w = 80, h = 50,          -- 按钮尺寸
        text = "返回",           -- 按钮文字
        -- 按钮点击事件：返回上一级页面
        on_click = function()
            win:back()  -- 调用窗口的back方法返回主页
        end
    })

    -- 将组件添加到窗口中
    win:add(back)   -- 添加返回按钮

    return win      -- 返回创建好的窗口对象
end

-- 主程序入口函数
local function exeasyui_demo()
    -- 等待500毫秒，确保系统初始化完成
    sys.wait(500)

    -- 初始化硬件（lcd显示屏和触摸屏）
    ui.hw_init({})

    -- 初始化UI系统，设置主题为浅色模式
    ui.sw_init({ theme = "light" })

    -- 创建主页面窗口（白色背景）
    local home = ui.window({ background_color = ui.COLOR_WHITE })

    -- 配置子页面工厂函数
    -- 这里注册了两个子页面："page1"对应消息框页面，"page2"对应复选框页面
    home:configure_subpages({ 
        page1 = msgbox_page,   -- 消息框演示页面
    })

    -- 创建导航按钮2：进入消息框示例页面  
    local btn2 = ui.button({
        x = 20, y = 130,   -- 按钮位置（在第一个按钮下方）
        w = 280, h = 50,   -- 按钮尺寸
        text = "消息框示例", -- 按钮文字
        on_click = function()
            -- 点击后显示消息框示例页面
            home:show_subpage("page1")
        end
    })

    -- 将按钮添加到主页面
    home:add(btn2)         -- 消息框示例按钮

    -- 将主页面添加到UI渲染系统
    ui.add(home)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

4.2.1.11 window:back()

功能

在子页面中调用，关闭当前子页面并返回父窗口。

参数

无

返回值

无

示例

-- 引入exeasyui库
local ui = require("exeasyui")

-- 创建一个msgbox_page页面的函数
-- 这个函数用于创建消息框演示页面
local function msgbox_page()
    -- 创建一个白色背景的窗口容器
    local win = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建"返回"按钮
    local back = ui.button({
        x = 220, y = 140,        -- 按钮位置（在弹出按钮右边）
        w = 80, h = 50,          -- 按钮尺寸
        text = "返回",           -- 按钮文字
        -- 按钮点击事件：返回上一级页面
        on_click = function()
            win:back()  -- 调用窗口的back方法返回主页
        end
    })

    -- 将组件添加到窗口中
    win:add(back)   -- 添加返回按钮

    return win      -- 返回创建好的窗口对象
end

-- 主程序入口函数
local function exeasyui_demo()
    -- 等待500毫秒，确保系统初始化完成
    sys.wait(500)

    -- 初始化硬件（lcd显示屏和触摸屏）
    ui.hw_init({})

    -- 初始化UI系统，设置主题为浅色模式
    ui.sw_init({ theme = "light" })

    -- 创建主页面窗口（白色背景）
    local home = ui.window({ background_color = ui.COLOR_WHITE })

    -- 配置子页面工厂函数
    -- 这里注册了两个子页面："page1"对应消息框页面，"page2"对应复选框页面
    home:configure_subpages({ 
        page1 = msgbox_page,   -- 消息框演示页面
    })

    -- 创建导航按钮2：进入消息框示例页面  
    local btn2 = ui.button({
        x = 20, y = 130,   -- 按钮位置（在第一个按钮下方）
        w = 280, h = 50,   -- 按钮尺寸
        text = "消息框示例", -- 按钮文字
        on_click = function()
            -- 点击后显示消息框示例页面
            home:show_subpage("page1")
        end
    })

    -- 将按钮添加到主页面
    home:add(btn2)         -- 消息框示例按钮

    -- 将主页面添加到UI渲染系统
    ui.add(home)
end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

4.2.1.12 window:close_subpage(name, opts)

功能

关闭指定名称的子页面。

参数

name

参数含义：要关闭的子页面名称
数据类型：string
是否必选：是
取值范围：已通过show_subpage显示的子页面名称
注意事项：无
参数示例："settings"

opts

参数含义：关闭选项参数表
数据类型：table
是否必选：可选
取值范围：包含以下子参数：
        {
            参数含义：是否彻底销毁子页面
            数据类型：boolean
            取值范围：true（销毁）, false（仅隐藏）
            是否必选：可选
            注意事项：销毁后会触发垃圾回收
            参数示例：true
            destroy = ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：可选
注意事项：无

返回值

local close_result = win:close_subpage(name, opts)

close_result

含义说明：关闭操作结果
数据类型：boolean
取值范围：true（成功关闭）, false（子页面不存在）
注意事项：无
返回示例：true

示例

-- 引入exeasyui库
local ui = require("exeasyui")

-- 创建一个check_box_page页面的函数
-- 这个函数用于创建复选框演示页面
local function check_box_page()
    -- 创建白色背景窗口
    local win = ui.window({ background_color = ui.COLOR_WHITE })

    -- 创建三个复选框组件
    local cb1 = ui.check_box({ x = 20, y = 120, text = "选项A" })  -- 默认未选中
    local cb2 = ui.check_box({ x = 20, y = 160, text = "选项B", checked = true })  -- 默认选中
    local cb3 = ui.check_box({ x = 20, y = 200, text = "选项C" })  -- 默认未选中

    -- 创建返回主页按钮
    local back = ui.button({
        x = 20, y = 260, 
        w = 120, h = 40,
        text = "返回主页",
        on_click = function()
            win:back()  -- 返回主页
        end
    })

    -- 将所有组件添加到窗口
    win:add(cb1)    -- 复选框A
    win:add(cb2)    -- 复选框B  
    win:add(cb3)    -- 复选框C
    win:add(back)   -- 返回按钮

    return win      -- 返回窗口对象
end

-- 主程序入口函数
local function exeasyui_demo()
    -- 等待500毫秒，确保系统初始化完成
    sys.wait(500)

    -- 初始化硬件（lcd显示屏和触摸屏）
    ui.hw_init({})

    -- 初始化UI系统，设置主题为浅色模式
    ui.sw_init({ theme = "light" })

    -- 创建主页面窗口（白色背景）
    local home = ui.window({ background_color = ui.COLOR_WHITE })

    -- 配置子页面工厂函数
    -- 这里注册了两个子页面："page1"对应消息框页面，"page2"对应复选框页面
    home:configure_subpages({ 
        page1 = msgbox_page,   -- 消息框演示页面
    })

    -- 创建导航按钮1：进入复选框示例页面
    local btn1 = ui.button({
        x = 20, y = 60,    -- 按钮位置
        w = 280, h = 50,   -- 按钮尺寸
        text = "复选框示例", -- 按钮文字
        on_click = function()
            -- 点击后显示复选框示例页面
            home:show_subpage("page2")
        end
    })

        -- 创建功能按钮：移除复选框子界面（演示销毁功能）
    local btnRemove = ui.button({
        x = 20, y = 200,   -- 按钮位置
        w = 280, h = 50,   -- 按钮尺寸
        text = "移除复选框子界面(销毁)", -- 按钮文字
        on_click = function()
            -- 强制销毁缓存的check_box子页面，释放内存
            home:close_subpage("page2", { destroy = true })
        end
    })

    -- 将按钮添加到主页面
    home:add(btn2)         -- 消息框示例按钮
    home:add(btnRemove)    -- 移除页面按钮

    -- 将主页面添加到UI渲染系统
    ui.add(home)

end

-- 创建并启动主任务
sys.taskInit(exeasyui_demo)

4.2.2 ui.label(opts)

功能

创建文本标签组件。

参数

opts

参数含义：标签配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：标签左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            x =  ,

            参数含义：标签左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            y =  ,

            参数含义：标签显示文本
            数据类型：string
            取值范围：任意字符串
            是否必选：是
            注意事项：支持中文
            参数示例："Hello World"
            text =  ,

            参数含义：标签文本颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            color =  ,

            参数含义：标签文本大小
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认使用系统字体大小
            参数示例：12
            size =  ,

            参数含义：标签宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：不设置时自动计算文本宽度
            参数示例：100
            w =  ,

            参数含义：是否启用自动换行
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：启用时需要设置w参数
            参数示例：true
            word_wrap =  ,

            参数含义：自定义字体指针
            数据类型：userdata
            取值范围：有效的字体对象
            是否必选：可选
            注意事项：高级用法，通常不需要设置
            参数示例：lcd.font_opposansm12
            font =  ,

            参数含义：标签是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：标签是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：标签不响应事件，此参数主要用于布局
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：必须包含位置和文本参数

返回值

local label_component = ui.label(opts)

label_component

含义说明：标签组件对象
数据类型：table
取值范围：包含draw、handle_event、set_text等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：label_object

示例

-- 创建单行标签
local label1 = ui.label({
    x = 10, y = 150,
    text = "单行文本",
    color = ui.COLOR_WHITE,
    size = 16
})

-- 创建自动换行标签
local label2 = ui.label({
    x = 10, y = 180,
    w = 200,
    text = "这是一段很长的文本，当启用自动换行时会根据宽度自动换行显示",
    word_wrap = true,
    color = ui.COLOR_YELLOW
})

ui.add(label1)
ui.add(label2)

-- 动态更新文本
label1:set_text("更新后的文本")
label1:set_size(18)  -- 更改字体大小

4.2.2.1 label:set_text(t)

功能

设置标签显示的文本。

参数

t

参数含义：新的标签文本
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：支持自动换行标签
参数示例："新标签文本"

返回值

无

示例

local label = ui.label({x=10, y=10, text="原始文本"})
label:set_text("更新后的文本")

4.2.3 ui.button(opts)

功能

创建按钮组件，支持文本按钮和图片按钮。

参数

opts

参数含义：按钮配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：按钮左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            x =  ,

            参数含义：按钮左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            y =  ,

            参数含义：按钮宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：是
            注意事项：必须为整数
            参数示例：100
            w =  ,

            参数含义：按钮高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：是
            注意事项：必须为整数
            参数示例：36
            h =  ,

            参数含义：按钮显示文本
            数据类型：string
            取值范围：任意字符串
            是否必选：文本模式和图片模式二选一
            注意事项：与src参数互斥
            参数示例："确定"
            text =  ,

            参数含义：按钮背景颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLUE
            bg_color =  ,

            参数含义：按钮文本颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            text_color =  ,

            参数含义：按钮边框颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_GRAY
            border_color =  ,

            参数含义：按钮文本大小
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：文本模式有效
            参数示例：12
            text_size =  ,

            参数含义：按钮图片路径（图片模式）
            数据类型：string
            取值范围：有效的JPG文件路径
            是否必选：文本模式和图片模式二选一
            注意事项：与text参数互斥
            参数示例："/luadb/button.jpg"
            src =  ,

            参数含义：按下状态图片路径
            数据类型：string
            取值范围：有效的JPG文件路径
            是否必选：可选
            注意事项：图片模式有效
            参数示例："/luadb/button_pressed.jpg"
            src_pressed =  ,

            参数含义：切换状态图片路径
            数据类型：string
            取值范围：有效的JPG文件路径
            是否必选：可选
            注意事项：toggle模式有效
            参数示例："/luadb/button_toggled.jpg"
            src_toggled =  ,

            参数含义：是否为切换按钮
            数据类型：boolean
            取值范围：true（是）, false（否）
            是否必选：可选
            注意事项：启用后按钮将在按下/抬起状态间切换
            参数示例：true
            toggle =  ,

            参数含义：切换按钮初始状态
            数据类型：boolean
            取值范围：true（按下）, false（抬起）
            是否必选：可选
            注意事项：toggle模式有效
            参数示例：false
            toggled =  ,

            参数含义：按钮点击回调函数
            数据类型：function
            取值范围：格式为function(button) end的函数
            是否必选：可选
            注意事项：按钮被点击时调用
            参数示例：function(btn) log.info("点击", btn.text) end
            on_click =  ,

            参数含义：切换状态变化回调函数
            数据类型：function
            取值范围：格式为function(toggled, button) end的函数
            是否必选：可选
            注意事项：toggle模式有效
            参数示例：function(state, btn) log.info("切换", state) end
            on_toggle =  ,

            参数含义：按钮是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：按钮是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：禁用时不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：必须包含位置和尺寸参数

返回值

local button_component = ui.button(opts)

button_component

含义说明：按钮组件对象
数据类型：table
取值范围：包含draw、handle_event等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：button_object

示例

-- 创建文本按钮
local btn = ui.button({
    x = 50, y = 50, w = 100, h = 36,
    text = "确定",
    bg_color = ui.COLOR_BLUE,
    text_color = ui.COLOR_WHITE,
    on_click = function(button)
        log.info("按钮被点击", button.text)
    end
})

-- 创建图片按钮
local imgBtn = ui.button({
    x = 160, y = 50, w = 64, h = 64,
    src = "/luadb/icon.jpg",
    src_pressed = "/luadb/icon_pressed.jpg",
    toggle = true,
    on_toggle = function(state)
        log.info("切换状态", state)
    end
})

ui.add(btn)
ui.add(imgBtn)

4.2.3.1 button:set_text(newText)

功能

设置按钮显示的文本。

参数

newText

参数含义：新的按钮文本
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：仅文本按钮有效
参数示例："新文本"

返回值

无

示例

local btn = ui.button({x=10, y=10, w=100, h=36, text="原始文本"})
btn:set_text("更新后的文本")

4.2.4 ui.progress_bar(opts)

功能

创建进度条组件。

参数

opts

参数含义：进度条配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：进度条左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            x =  ,

            参数含义：进度条左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            y =  ,

            参数含义：进度条宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：是
            注意事项：必须为整数
            参数示例：200
            w =  ,

            参数含义：进度条高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：是
            注意事项：必须为整数
            参数示例：24
            h =  ,

            参数含义：进度条初始进度
            数据类型：number
            取值范围：0到100的数值
            是否必选：可选
            注意事项：默认0
            参数示例：50
            progress =  ,

            参数含义：是否显示百分比
            数据类型：boolean
            取值范围：true（显示）, false（不显示）
            是否必选：可选
            注意事项：默认显示
            参数示例：true
            show_percentage =  ,

            参数含义：自定义进度文本
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：设置后覆盖百分比显示
            参数示例："下载中..."
            text =  ,

            参数含义：文本大小
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认使用系统字体大小
            参数示例：12
            text_size =  ,

            参数含义：背景颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_GRAY
            background_color =  ,

            参数含义：进度条颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLUE
            progress_color  =  ,

            参数含义：边框颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            border_color =  ,

            参数含义：文本颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            text_color =  ,

            参数含义：进度条是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：进度条是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：进度条不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：必须包含位置和尺寸参数

返回值

local progress_bar_component = ui.progress_bar(opts)

progress_bar_component

含义说明：进度条组件对象
数据类型：table
取值范围：包含draw、handle_event、set_progress等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：progress_bar_object

示例

-- 创建进度条
local progress = ui.progress_bar({
    x = 10, y = 350,
    w = 300, h = 24,
    progress = 0,
    progress_color  = ui.COLOR_BLUE,
    text = "初始化..."
})

ui.add(progress)

-- 动态更新进度
for i = 0, 100, 10 do
    progress:set_progress(i)
    progress:set_text("下载中 " .. i .. "%")
    sys.wait(500)
end

progress:set_text("完成！")

4.2.4.1 progress_bar:set_progress(value)

功能

设置进度条的当前进度值。

参数

value

参数含义：进度值
数据类型：number
是否必选：是
取值范围：0到100的数值
注意事项：会自动限制在0-100范围内，超出范围会自动修正
参数示例：75

返回值

无

示例

local progress = ui.progress_bar({x=10, y=10, w=200, h=24, progress=0})
progress:set_progress(50) -- 设置进度为50%
-- 进度值会自动限制在0-100范围内
progress:set_progress(150) -- 实际进度为100
progress:set_progress(-10) -- 实际进度为0

4.2.4.2 progress_bar:get_progress()

功能

获取进度条的当前进度值。

参数

无

返回值

local progress_value = progress:get_progress()

progress_value

含义说明：当前进度值
数据类型：number
取值范围：0到100的数值
注意事项：返回的是实际设置的进度值，不是估算值
返回示例：50

示例

local progress = ui.progress_bar({ x = 10, y = 10, w = 200, h = 24, progress = 30 })
local currentProgress = progress:get_progress() -- 返回30
log.info("当前进度", currentProgress .. "%")

-- 在循环中监控进度
for i = 0, 100, 10 do
    progress:set_progress(i)
    sys.wait(200)
    local current = progress:get_progress()
    log.info("进度更新", current .. "%")
end

4.2.4.3 progress_bar:set_text(text)

功能

设置进度条显示的文本内容。

参数

text

参数含义：显示的文本内容
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：设置自定义文本后会覆盖百分比显示，设置为nil或空字符串可恢复百分比显示
参数示例："下载中..."

返回值

无

示例

local progress = ui.progress_bar({ x = 10, y = 10, w = 200, h = 24, progress = 0 })

-- 设置自定义文本
progress:set_text("初始化...")
progress:set_progress(0)

-- 更新进度和文本
progress:set_progress(25)
progress:set_text("下载文件...")

progress:set_progress(50)
progress:set_text("处理数据...")

progress:set_progress(75)
progress:set_text("完成中...")

progress:set_progress(100)
progress:set_text("完成！")

-- 恢复显示百分比
progress:set_text(nil)    -- 或 progress:set_text("")
progress:set_progress(50) -- 现在会显示"50%"

4.2.5 ui.message_box(opts)

功能

创建消息框组件，包含标题、消息文本和按钮组。

参数

opts

参数含义：消息框配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：消息框左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：可选
            注意事项：不设置时默认居中显示
            参数示例：20
            x =  ,

            参数含义：消息框左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：可选
            注意事项：不设置时默认居中显示
            参数示例：40
            y =  ,

            参数含义：消息框宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认280
            参数示例：280
            w =  ,

            参数含义：消息框高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认160
            参数示例：160
            h =  ,

            参数含义：消息框标题
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：默认"Info"
            参数示例："提示"
            title =  ,

            参数含义：消息框内容文本
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：默认空字符串
            参数示例："操作成功！"
            message =  ,

            参数含义：是否启用自动换行
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：默认启用
            参数示例：true
            word_wrap =  ,

            参数含义：文本大小
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认使用系统字体大小
            参数示例：12
            text_size =  ,

            参数含义：边框颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            border_color =  ,

            参数含义：文本颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            text_color =  ,

            参数含义：背景颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLACK
            bg_color =  ,

            参数含义：按钮文本数组
            数据类型：table
            取值范围：包含按钮文本字符串的数组
            是否必选：可选
            注意事项：不设置，默认为{"OK"}，显示OK按钮
            参数示例：{"确定", "取消"}
            buttons =  ,

            参数含义：按钮点击回调函数
            数据类型：function
            取值范围：格式为function(button_text) end的函数
            是否必选：可选
            注意事项：点击按钮时调用，参数为按钮文本
            参数示例：function(btnText) log.info("点击", btnText) end
            on_result =  ,

            参数含义：消息框是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：消息框是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：禁用时不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：通常需要设置title、message和on_result参数

返回值

local message_box_component = ui.message_box(opts)

message_box_component

含义说明：消息框组件对象
数据类型：table
取值范围：包含draw、handle_event、show、hide等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：message_box_object

示例

-- 创建消息框
local msgbox = ui.message_box({
    title = "确认操作",
    message = "您确定要执行此操作吗？",
    buttons = {"确定", "取消"},
    on_result = function(btnText)
        if btnText == "确定" then
            log.info("用户点击了确定")
        else
            log.info("用户点击了取消")
        end
    end
})

ui.add(msgbox)

-- 动态更新消息框内容
msgbox:set_title("新标题")
msgbox:set_message("新的消息内容")

-- 显示/隐藏消息框
msgbox:show()
msgbox:hide()

4.2.5.1 message_box:show()

功能

显示消息框。

参数

无

返回值

无

示例

local msgbox = ui.message_box({
    title = "提示",
    message = "这是一个消息框",
    buttons = { "确定" }
})
msgbox:show()

4.2.5.2 message_box:hide()

功能

隐藏消息框。

参数

无

返回值

无

示例

local msgbox = ui.message_box({
    title = "提示",
    message = "这是一个消息框",
    buttons = { "确定" }
})
msgbox:hide()

4.2.5.3 message_box:set_title(title)

功能

设置消息框标题。

参数

title

参数含义：新的标题文本
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：无
参数示例："新标题"

返回值

无

示例

local msgbox = ui.message_box({ title = "原始标题", message = "内容" })
msgbox:set_title("更新后的标题")

4.2.5.4 message_box:set_message(message)

功能

设置消息框内容文本。

参数

message

参数含义：新的消息内容
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：如果启用了自动换行，会重新计算行缓存
参数示例："新的消息内容"

返回值

无

示例

local msgbox = ui.message_box({ title = "标题", message = "原始内容" })
msgbox:set_message("更新后的内容")

4.2.6 ui.check_box(opts)

功能

创建复选框组件。

参数

opts

参数含义：复选框配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：复选框左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            x =  ,

            参数含义：复选框左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            y =  ,

            参数含义：复选框方框尺寸
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认16
            参数示例：16
            box_size =  ,

            参数含义：复选框文本
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：显示在复选框右侧的说明文字
            参数示例："同意协议"
            text =  ,

            参数含义：复选框文本颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            text_color =  ,

            参数含义：复选框边框颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            border_color =  ,

            参数含义：复选框背景颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLACK
            bg_color =  ,

            参数含义：复选框勾选颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            tick_color =  ,

            参数含义：复选框初始状态
            数据类型：boolean
            取值范围：true（选中）, false（未选中）
            是否必选：可选
            注意事项：默认未选中
            参数示例：false
            checked =  ,

            参数含义：复选框状态变化回调函数
            数据类型：function
            取值范围：格式为function(checked) end的函数
            是否必选：可选
            注意事项：状态变化时调用
            参数示例：function(state) log.info("状态", state) end
            on_change=  ,

            参数含义：复选框是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：复选框是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：禁用时不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：必须包含位置参数

返回值

local check_box_component = ui.check_box(opts)

check_box_component

含义说明：复选框组件对象
数据类型：table
取值范围：包含draw、handle_event、set_checked等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：check_box_object

示例

-- 创建复选框
local check_box = ui.check_box({
    x = 10, y = 100,
    text = "启用功能",
    checked = false,
    on_change= function(checked)
        log.info("复选框状态", checked)
    end
})

ui.add(check_box)

-- 动态设置选中状态
check_box:set_checked(true)

-- 切换状态
check_box:toggle()

4.2.6.1 check_box:set_checked(enabled)

功能

设置复选框的选中状态。

参数

enabled

参数含义：选中状态
数据类型：boolean
是否必选：是
取值范围：true（选中）, false（未选中）
注意事项：状态变化会触发on_change回调
参数示例：true

返回值

无

示例

local check_box = ui.check_box({ x = 10, y = 10, text = "选项" })
check_box:set_checked(true)

4.2.6.2 check_box:toggle()

功能

切换复选框的选中状态。

参数

无

返回值

无

示例

local check_box = ui.check_box({ x = 10, y = 10, text = "选项" })
check_box:toggle() -- 从未选中变为选中
check_box:toggle() -- 从选中变为未选中

4.2.7 ui.picture(opts)

功能

创建图片显示组件，支持单图和轮播图。

参数

opts

参数含义：图片配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：图片左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            x =  ,

            参数含义：图片左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：是
            注意事项：必须为整数
            参数示例：10
            y =  ,

            参数含义：单张图片路径
            数据类型：string
            取值范围：有效的JPG文件路径
            是否必选：单图和轮播图二选一
            注意事项：与sources参数互斥
            参数示例："/luadb/image.jpg"
            src =  ,

            参数含义：轮播图片路径数组
            数据类型：table
            取值范围：包含多个JPG文件路径的数组
            是否必选：单图和轮播图二选一
            注意事项：与src参数互斥
            参数示例：{"/luadb/img1.jpg", "/luadb/img2.jpg", "/luadb/img3.jpg"}
            sources =  ,

            参数含义：轮播初始索引
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：sources模式有效
            参数示例：1
            index =  ,

            参数含义：是否启用自动轮播
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：sources模式有效
            参数示例：true
            autoplay =  ,

            参数含义：轮播间隔时间
            数据类型：number
            取值范围：大于0的整数，单位毫秒
            是否必选：可选
            注意事项：autoplay模式有效
            参数示例：1000
            interval =  ,

            参数含义：图片是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：图片是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：禁用时不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：必须包含位置和尺寸参数

返回值

local picture_component = ui.picture(opts)

picture_component

含义说明：图片组件对象
数据类型：table
取值范围：包含draw、handle_event、next、prev等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：picture_object

示例

-- 创建单张图片
local pic1 = ui.picture({
    x = 10, y = 250,
    src = "/luadb/photo.jpg"
})

-- 创建轮播图
local pic2 = ui.picture({
    x = 120, y = 250,
    sources = {"/luadb/slide1.jpg", "/luadb/slide2.jpg", "/luadb/slide3.jpg"},
    autoplay = true,
    interval = 2000
})

ui.add(pic1)
ui.add(pic2)

-- 手动控制轮播
pic2:next()  -- 下一张
pic2:prev()  -- 上一张
pic2:play()  -- 开始自动播放
pic2:pause() -- 暂停自动播放

-- 动态设置图片源
pic2:set_sources({"/luadb/new1.jpg", "/luadb/new2.jpg"})

4.2.7.1 picture:set_sources(list)

功能

设置轮播图片源列表。

参数

list

参数含义：图片路径数组
数据类型：table
是否必选：是
取值范围：包含多个JPG文件路径的数组
注意事项：会重置当前轮播索引到第一张
参数示例：{"/luadb/img1.jpg", "/luadb/img2.jpg"}

返回值

无

示例

local pic = ui.picture({ x = 10, y = 10 })
pic:set_sources({ "slide1.jpg", "slide2.jpg", "slide3.jpg" })

4.2.7.2 picture:next()

功能

切换到下一张图片。

参数

无

返回值

无

示例

local pic = ui.picture({
    x = 10,
    y = 10,
    sources = { "/luadb/1.jpg", "/luadb/2.jpg", "/luadb/3.jpg" }
})
pic:next() -- 显示2.jpg

4.2.7.3 picture:prev()

功能

切换到上一张图片。

参数

无

返回值

无

示例

local pic = ui.picture({
    x = 10,
    y = 10,
    sources = { "/luadb/1.jpg", "/luadb/2.jpg", "/luadb/3.jpg" },
    index = 2
})
pic:prev() -- 显示1.jpg

4.2.7.4 picture:play()

功能

开始自动轮播。

参数

无

返回值

无

示例

local pic = ui.picture({
    x = 10,
    y = 10,
    sources = { "/luadb/1.jpg", "/luadb/2.jpg", "/luadb/3.jpg" },
    autoplay = false
})
pic:play() -- 开始自动轮播

4.2.7.5 picture:pause()

功能

暂停自动轮播。

参数

无

返回值

无

示例

local pic = ui.picture({
    x = 10,
    y = 10,
    sources = { "/luadb/1.jpg", "/luadb/2.jpg", "/luadb/3.jpg" },
    autoplay = true
})
pic:pause() -- 暂停自动轮播

4.2.8 ui.input(opts)

功能

创建输入框组件，支持文本输入、数字输入、密码输入等多种输入类型，自动关联虚拟键盘。

参数

opts

参数含义：输入框配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：输入框左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：可选
            注意事项：必须为整数
            参数示例：10
            x =  ,

            参数含义：输入框左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：可选
            注意事项：必须为整数
            参数示例：10
            y =  ,

            参数含义：输入框宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认200
            参数示例：200
            w =  ,

            参数含义：输入框高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认36
            参数示例：36
            h =  ,

            参数含义：初始文本内容
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：默认空字符串
            参数示例："初始文本"
            text =  ,

            参数含义：占位符文本
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：当输入框为空时显示的提示文本，默认"请输入文本"
            参数示例："请输入用户名"
            placeholder =  ,

            参数含义：最大输入长度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：不设置时无长度限制
            参数示例：20
            max_length =  ,

            参数含义：输入类型
            数据类型：string
            取值范围："text"（文本）, "number"（数字）, "password"（密码）, "email"（邮箱）
            是否必选：可选
            注意事项：默认"text"，会影响键盘类型
            参数示例："number"
            input_type =  ,

            参数含义：背景颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            bg_color =  ,

            参数含义：文本颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLACK
            text_color =  ,

            参数含义：占位符颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：默认COLOR_GRAY
            参数示例：ui.COLOR_GRAY
            placeholder_color =  ,

            参数含义：边框颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLACK
            border_color =  ,

            参数含义：获得焦点时的边框颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：默认COLOR_SKY_BLUE
            参数示例：ui.COLOR_SKY_BLUE
            focused_border_color =  ,

            参数含义：文本大小
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认12
            参数示例：12
            text_size =  ,

            参数含义：文本内容变化回调函数
            数据类型：function
            取值范围：格式为function(text, input) end的函数
            是否必选：可选
            注意事项：文本内容变化时调用
            参数示例：function(text, input) log.info("文本变化", text) end
            on_text_changed =  ,

            参数含义：焦点变化回调函数
            数据类型：function
            取值范围：格式为function(focused, input) end的函数
            是否必选：可选
            注意事项：获得或失去焦点时调用，focused为true表示获得焦点
            参数示例：function(focused, input) log.info("焦点变化", focused) end
            on_focus_changed =  ,

            参数含义：确认输入回调函数
            数据类型：function
            取值范围：格式为function(input) end的函数
            是否必选：可选
            注意事项：用户确认输入时调用（如键盘确认键）
            参数示例：function(input) log.info("确认", input:get_text()) end
            on_confirm =  ,

            参数含义：是否启用键盘点击效果
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：默认启用
            参数示例：true
            keyboard_click_effect =  ,

            参数含义：输入框是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：输入框是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：禁用时不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：必须包含位置参数

返回值

local input_component = ui.input(opts)

input_component

含义说明：输入框组件对象
数据类型：table
取值范围：包含draw、handle_event、set_text、get_text、focus、blur等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：input_object

示例

-- 创建文本输入框
local input1 = ui.input({
    x = 10, y = 50,
    w = 200, h = 36,
    placeholder = "请输入用户名",
    on_text_changed = function(text, input)
        log.info("输入内容", text)
    end
})

-- 创建数字输入框
local input2 = ui.input({
    x = 10, y = 100,
    w = 200, h = 36,
    input_type = "number",
    placeholder = "请输入数字"
})

-- 创建密码输入框
local input3 = ui.input({
    x = 10, y = 150,
    w = 200, h = 36,
    input_type = "password",
    placeholder = "请输入密码",
    max_length = 20
})

ui.add(input1)
ui.add(input2)
ui.add(input3)

-- 动态操作
input1:set_text("新文本")
local text = input1:get_text()

4.2.8.1 input:set_text(text)

功能

设置输入框的文本内容。

参数

text

参数含义：新的文本内容
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：如果设置了max_length，会自动截断超出部分；会触发on_text_changed回调
参数示例："新文本"

返回值

无

示例

local input = ui.input({ x = 10, y = 10 })
input:set_text("Hello World")

4.2.8.2 input:get_text()

功能

获取输入框的当前文本内容。

参数

无

返回值

local text = input:get_text()

text

含义说明：当前文本内容
数据类型：string
取值范围：输入框中的文本字符串
注意事项：无
返回示例："Hello World"

示例

local input = ui.input({ x = 10, y = 10, text = "初始文本" })
local text = input:get_text() -- 返回"初始文本"

4.2.9 ui.combo_box(opts)

功能

创建下拉选择框组件，支持从多个选项中选择一个。

参数

opts

参数含义：下拉框配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
        {
            参数含义：下拉框左上角X坐标
            数据类型：number
            取值范围：0到屏幕宽度
            是否必选：可选
            注意事项：必须为整数
            参数示例：10
            x =  ,

            参数含义：下拉框左上角Y坐标
            数据类型：number
            取值范围：0到屏幕高度
            是否必选：可选
            注意事项：必须为整数
            参数示例：10
            y =  ,

            参数含义：下拉框宽度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认200
            参数示例：200
            w =  ,

            参数含义：下拉框高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认36
            参数示例：36
            h =  ,

            参数含义：选项列表
            数据类型：table
            取值范围：包含选项的数组，选项可以是字符串或包含text/value字段的表
            是否必选：可选
            注意事项：默认空数组
            参数示例：{"选项1", "选项2", "选项3"} 或 {{text="选项1", value=1}, {text="选项2", value=2}}
            options =  ,

            参数含义：初始选中项的索引
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认1，会自动限制在有效范围内
            参数示例：1
            selected =  ,

            参数含义：占位符文本
            数据类型：string
            取值范围：任意字符串
            是否必选：可选
            注意事项：当没有选项时显示的文本，默认"请选择"
            参数示例："请选择"
            placeholder =  ,

            参数含义：下拉列表最大可见项数
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认5
            参数示例：5
            max_visible_items =  ,

            参数含义：下拉列表项高度
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认32
            参数示例：32
            item_height =  ,

            参数含义：文本大小
            数据类型：number
            取值范围：大于0的整数
            是否必选：可选
            注意事项：默认14
            参数示例：14
            text_size =  ,

            参数含义：背景颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_WHITE
            bg_color =  ,

            参数含义：边框颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLACK
            border_color =  ,

            参数含义：文本颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：不设置时根据主题自动选择
            参数示例：ui.COLOR_BLACK
            text_color =  ,

            参数含义：箭头颜色
            数据类型：number
            取值范围：第三章常量解释中的3.1-3.17章节中的颜色常量，或其他16位RGB565颜色值
            是否必选：可选
            注意事项：默认使用COLOR_SKY_BLUE
            参数示例：ui.COLOR_SKY_BLUE
            arrow_color =  ,

            参数含义：选择项变化回调函数
            数据类型：function
            取值范围：格式为function(value, index, text) end的函数
            是否必选：可选
            注意事项：选择项变化时调用，参数为选中值、索引、文本
            参数示例：function(value, index, text) log.info("选择", value, index, text) end
            on_select =  ,

            参数含义：下拉框是否可见
            数据类型：boolean
            取值范围：true（可见）, false（不可见）
            是否必选：可选
            注意事项：默认可见
            参数示例：true
            visible =  ,

            参数含义：下拉框是否启用
            数据类型：boolean
            取值范围：true（启用）, false（禁用）
            是否必选：可选
            注意事项：禁用时不响应触摸事件
            参数示例：true
            enabled =  ,
        }
数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：必须包含位置参数

返回值

local combo_box_component = ui.combo_box(opts)

combo_box_component

含义说明：下拉框组件对象
数据类型：table
取值范围：包含draw、handle_event、set_options、set_selected等方法的组件对象
注意事项：需要调用ui.add添加到渲染队列
返回示例：combo_box_object

示例

-- 创建下拉框
local combo = ui.combo_box({
    x = 10, y = 100,
    w = 200, h = 36,
    options = {"选项1", "选项2", "选项3"},
    selected = 1,
    on_select = function(value, index, text)
        log.info("选择了", text, "索引", index, "值", value)
    end
})

ui.add(combo)

-- 使用表格式选项（带value）
local combo2 = ui.combo_box({
    x = 10, y = 150,
    options = {
        {text = "红色", value = "red"},
        {text = "绿色", value = "green"},
        {text = "蓝色", value = "blue"}
    },
    selected = 1
})

-- 动态更新选项
combo:set_options({"新选项1", "新选项2"})
combo:set_selected(1)

-- 获取当前选中信息
local index = combo:get_selected_index()
local text = combo:get_selected_text()
local value = combo:get_selected_value()

4.2.9.1 combo_box:set_options(opts)

功能

设置下拉框的选项列表。

参数

options

参数含义：选项列表
数据类型：table
是否必选：是
取值范围：包含选项的数组，选项可以是字符串或包含text/value字段的表
注意事项：会重置选中索引到最后一个有效项
参数示例：{"选项1", "选项2"}

返回值

无

示例

local combo = ui.combo_box({ x = 10, y = 10, options = {"A", "B"} })
combo:set_options({"选项1", "选项2", "选项3"})

4.2.9.2 combo_box:set_selected(index)

功能

设置下拉框的选中项索引。

参数

index

参数含义：选中项索引
数据类型：number
是否必选：是
取值范围：1到选项数量的整数
注意事项：超出范围时不会改变选中项
参数示例：2

返回值

无

示例

local combo = ui.combo_box({ x = 10, y = 10, options = {"A", "B", "C"} })
combo:set_selected(2) -- 选中"B"

4.2.9.3 combo_box:get_selected_index()

功能

获取当前选中项的索引。

参数

无

返回值

local selected_index = combo:get_selected_index()

selected_index

含义说明：当前选中项索引
数据类型：number
取值范围：大于0的整数，如果没有选项则返回0
注意事项：无
返回示例：2

示例

local combo = ui.combo_box({ x = 10, y = 10, options = {"A", "B", "C"}, selected = 2 })
local index = combo:get_selected_index() -- 返回2

4.2.9.4 combo_box:get_selected_text()

功能

获取当前选中项的文本。

参数

无

返回值

local selected_text = combo:get_selected_text()

selected_text

含义说明：当前选中项文本
数据类型：string
取值范围：选项的文本内容，如果没有选项则返回占位符文本
注意事项：无
返回示例："选项2"

示例

local combo = ui.combo_box({ x = 10, y = 10, options = {"选项1", "选项2"} })
local text = combo:get_selected_text() -- 返回"选项1"

4.2.9.5 combo_box:get_selected_value()

功能

获取当前选中项的值。

参数

无

返回值

local selected_value = combo:get_selected_value()

selected_value

含义说明：当前选中项的值
数据类型：任意类型
取值范围：如果选项是表格式（包含value字段），返回value；否则返回选项本身；如果没有选项则返回nil
注意事项：无
返回示例：1 或 "red" 或 nil

示例

local combo = ui.combo_box({
    x = 10, y = 10,
    options = {{text = "红色", value = "red"}, {text = "绿色", value = "green"}}
})
local value = combo:get_selected_value() -- 返回"red"

五、模组支持说明

1. lcd 需要硬件支持, 请确认你的设备有 lcd 屏幕接口，可以查看选型手册对应型号及固件是否支持 lcd 功能或 lcd 库以及 tp 库
2. 支持 SPI QSPI RGB 等多种接口的 lcd 屏幕, 取决于具体的硬件
3. 对于 Air780EHM/EGH/EHV/Air8000 系列, 默认开启 JPG 硬件解码, JPG 图片的长宽都需要是 16 的倍数, 否则会出现画面拉伸的现象