exEasyUI 扩展库

一、概述

• exEasyUI 是基于 LuatOS 打造的简化 UI 组件库，内聚了组件管理、渲染与触摸事件分发能力。
• 主要组件：Button、Label、ProgressBar、MessageBox、Picture、CheckBox、Window。
• 用 exEasyUI 以更少代码快速搭建可量产的触控界面，内置触摸/渲染/组件与示例。
• 提供 LuatOS PC 模拟器快速验证效果，无需等待烧录。
• 更多组件持续更新中。

二、组件效果及演示代码

2.1 Window（窗口容器）+Label（文本）静态方式

2.1.1 演示效果

默认使用12号中文字体	显示效果	可设置颜色	使用gtfont字库可设置字体大小可设置字体大小
黑色/白色，跟随主题	Hello exEasyUI	Hello exEasyUI	Hello exEasyUI

2.1.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

    -- 创建Window（窗口容器），设置背景为黑色，命名为page1
    local page1 = ui.Window({ backgroundColor = 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
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30) 
    end
end

sys.taskInit(exEasyUI_demo)

sys.run()

2.1.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.1Window+Label\

2.2 Window（窗口容器）+Label（文本）+ 循环刷新

2.2.1 演示效果

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

2.2.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

    -- 创建Window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.Window({ backgroundColor = 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
        -- 清除显示
        ui.clear()
        -- 更新时间给文本组件lbl
        lbl:setText("时间:"..os.date("%Y-%m-%d %H:%M:%S"))           
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.2.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.2Window+Label\

2.3 Window（窗口容器）+ Button（按钮）文本模式

2.3.1 演示效果

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

2.3.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

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

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

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

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30) 
    end
end

sys.taskInit(exEasyUI_demo)

sys.run()

2.3.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.3Window+Button\

2.4 Window（窗口容器）+ Button（按钮）图标模式

2.4.1 演示效果

设置默认图标
设置点击后图标

2.4.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

    -- 创建Window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.Window({ backgroundColor = 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)

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.4.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.4Window+Button\

2.5 Window（窗口容器）+ ProgressBar（进度条）静态方式

2.5.1 演示效果

默认

2.5.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

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

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

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

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.5.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.5Window+ProgressBar\

2.6 Window（窗口容器）+ ProgressBar（进度条）动态方式

2.6.1 演示效果

默认
更改进度
自定义内容

2.6.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local direction = 1 
local current = 0

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

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

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

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

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        pb:setProgress(current)
        current = current + direction
        if current >= 100 then
            direction = -1
        elseif current <= 0 then
            direction = 1
        end  
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.6.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.5Window+ProgressBar\

2.7 Window（窗口容器）+ MessageBox（消息面板）

2.7.1 演示效果

标题消息按钮
富文本消息

2.7.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

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

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

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

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.7.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.6Window+MessageBox\

2.8 Window（窗口容器）+ CheckBox（复选框）

2.8.1 演示效果

默认状态	选中状态	选中后执行程序
		可选

2.8.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

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

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

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

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.8.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.7Window+CheckBox\

2.9 Window（窗口容器）+ Picture（图片轮播）单图模式

2.9.1 演示效果

未设置图片	设置了图片

2.9.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

    -- 创建Window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.Window({ backgroundColor = 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)

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.9.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.8Window+Picture\

2.10 Window（窗口容器）+ Picture（图片轮播）轮播模式

2.10.1 演示效果

**列表内图片，每张按设置之间循环显示**

2.10.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)

    -- 显示触摸初始化
    ui.hw.init({})

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

    -- 创建Window（窗口容器），设置背景为白色，命名为page1
    local page1 = ui.Window({ backgroundColor = 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)

    -- 显示主循环
    while true do
        -- 清除显示
        ui.clear()
        -- 刷新显示
        ui.render()
        -- 等待30ms
        sys.wait(30)
    end

end

sys.taskInit(exEasyUI_demo)

sys.run()

2.10.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.9Window+Picture\

2.11 全部控件

2.11.1 演示效果

2.11.2 演示代码

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

local function exEasyUI_demo()
    sys.wait(500)
    -- 依赖 screen_data_table.lua 内的 lcdargs/touch 参数
    -- 显示触摸初始化
    ui.hw.init({})

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

    -- 创建设置背景为白色
    local page1 = ui.Window({ backgroundColor = ui.COLOR_WHITE })

    -- 1、创建一个高度为1000像素的页面，移动超过8个像素，页面跟随
    page1:enableScroll({ direction = "vertical", contentHeight = 1000, threshold = 8 })

    -- 2、 ProgressBar进度条
    local progress = 0
    local pb = ui.ProgressBar({ x = 20, y = 170, w = 280, h = 26, progress = progress})
    -- 添加控件到page1
    page1:add(pb)

    -- 3、 MessageBox（消息框/面板）
    local box = ui.MessageBox({ x = 20, y = 160, wordWrap = true, buttons = {"接受祝福"},title = "祝福", message = "愿你前路浩荡,未来可期.愿你保持热爱,奔赴山海。愿你所有的努力都不被辜负,最终活成自己最喜欢的模样.加油!"})
    page1:add(box)
    page1:remove(box)

    -- 4、 Button
    local btn1 = ui.Button({ x = 180, y = 76, onClick = function(self)
        progress = progress + 10  pb:setProgress(progress) pb:setText("下载中"..progress.."%")
        if progress == 100 then page1:add(box) progress = 0 end
    end })
    page1:add(btn1)

    -- 5、 ToolButton，点击切换图片，可选执行程序
    local btn2 = ui.Button({x = 10, y = 64, w = 64, h = 64,
        src = "/luadb/4.jpg",           -- 默认图片
        src_toggled = "/luadb/5.jpg",   -- 切换状态时的图片
        toggle = true,                  -- 启用切换模式
    })
    page1:add(btn2)

    -- 6、创建一个三张图片轮播的控件，1.5s切换一张
    local pic = ui.Picture({ x = 20, y = 310,
    sources = {"/luadb/1.jpg", "/luadb/2.jpg", "/luadb/3.jpg"}, autoplay = true, interval = 1500 })
    -- 添加控件pic到page1
    page1:add(pic)

    -- 7、 CheckBox
    local cb = ui.CheckBox({ x = 20, y = 240, text = "Check me", checked = false, onChange = function (v)
        log.info("demo", "checkbox", v)
    end })
    page1:add(cb)

    -- 8、 Label 目前显示的是日期和时间
    lbl = ui.Label({ x = 20, y = 20, text = ""})
    page1:add(lbl)

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

    -- 显示主循环
    while true do
        ui.clear()
        -- 更新时间给文本组件
        lbl:setText("时间:"..os.date("%Y-%m-%d %H:%M:%S"))
        ui.render()
        sys.wait(30)
    end
end
sys.taskInit(exEasyUI_demo)
sys.run()

2.11.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.10_all\

2.12 Window（窗口容器）+ 水平滑动

2.12.1 演示效果

2.12.2 演示代码

-- exEasyUI v1.6.0
local ui = require("exeasyui")

sys = require("sys")

sys.taskInit(function()
    sys.wait(500)
    ui.hw.init({})
    ui.init({ theme = "light" })

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

    local function makeGrid(offsetX, labelPrefix)
        local cols, rows = 3, 3
        local bw, bh = 90, 80
        local mx, my = 20 + offsetX, 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)

    while true do
        ui.clear()
        ui.render()
        sys.wait(30)
    end
end)

sys.run()

2.12.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.11Horizontal_slidin_page\

2.13 Window（窗口容器）+ 纵向滑动

2.13.1 演示效果

2.13.2 演示代码

-- exEasyUI v1.6.0
local ui = require("exeasyui")

sys = require("sys")

sys.taskInit(function()
    sys.wait(500)
    -- 依赖 screen_data_table.lua 内的 lcdargs/touch 参数
    ui.hw.init({})
    ui.init({ theme = "light" })

    local win = ui.Window({ backgroundColor = 0xFFFF })
    -- 启用纵向分页滚动，将两页内容上下排布到一个高画布
    local pageW, pageH = 320, 480
    local totalH = pageH * 2
    win:enableScroll({ direction = "vertical", contentHeight = totalH, threshold = 8, pagingEnabled = true, pageHeight = pageH })

    local function makeButtons(offsetY, 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 = offsetY + 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)

    while true do
        ui.clear()
        ui.render()
        sys.wait(30)
    end
end)

sys.run()

2.13.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.12Vertical_sliding_page\

2.14 页面切换

2.14.1 演示效果

2.14.2 演示代码

代码有多个文件夹，详情可见 demo 文件

2.14.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.13Switch_page\

2.15 矢量字体

2.15.1 演示效果

2.15.2 演示代码

PROJECT = "exEasyUI_gfont_demo"
VERSION = "1.0.0"

sys = require("sys")

-- exEasyUI v1.6.0
local ui = require("exeasyui")

sys.taskInit(function()
    sys.wait(500)
    -- 打开iic供电
    gpio.setup(141, 1, gpio.PULLUP)
    -- 启用 gtfont 字体后端
    ui.hw.init({ lcd_sn = "AirLCD_1001", tp = "gt911", font = { type = "gtfont", spi = { id = 1, cs = 12, clock = 20*1000*1000 }, gray = false, size = 32 } })
    ui.init({ theme = "light" })

    local win = ui.Window({ backgroundColor = ui.COLOR_WHITE })
    ui.add(win)

    local text1 = ui.Label({ x = 10, y = 20, text = "ABCDEFG", color = ui.COLOR_BLACK })
    local text2 = ui.Label({ x = 10, y = 100, text = "abcdefg", color = ui.COLOR_RED })
    local text3 = ui.Label({ x = 10, y = 180, text = "1234567", color = ui.COLOR_GREEN })
    local text4 = ui.Label({ x = 10, y = 260, text = "!@#$%^&*", color = ui.COLOR_BLUE })
    local text5 = ui.Label({ x = 10, y = 340, text = "Hello GTFont", color = ui.COLOR_ORANGE })
    local text6 = ui.Label({ x = 10, y = 420, text = "中英混排 ABC 合宙", color = ui.COLOR_PINK })

    ui.add(text1)
    ui.add(text2)
    ui.add(text3)
    ui.add(text4)
    ui.add(text5)
    ui.add(text6)

    while true do
        ui.clear()
        ui.render()
        sys.wait(200)
    end
end)

sys.run()

2.15.3 PC 模拟器快捷命令

.\luatos-lua.exe .\lib\ .\demo\2.14gtfont\

三、运行环境说明

3.1 演示文件说明

1. cmd 启动 LuatOS PC 模拟器的快捷键；
2. luatos-lua.exe，LuatOS PC 模拟器；
3. lib 文件夹，exEasyUI 库文件，无需修改；
4. 各 demo 文件夹，演示的 demo 文件，其中 main.lua 为主程序；

3.2 演示步骤

1. 双击 cmd 快捷键运行 LuatOS PC 模拟器；
2. 把代码下方 PC 模拟器快捷命令复制到 LuatOS PC 模拟器里面

3、按回车运行 LuatOS PC 模拟器和 demo 代码

4、退出 pc 模拟器运行的代码，使用快捷键 ctrl+c

5、查看 pc 模拟器历史运行的 PC 模拟器快捷命令，使用快捷键 ↑

3.3 快捷命令汇总

序号	运行demo文件	PC模拟器快捷命令
1	2.1Window+Label文本	.\luatos-lua.exe .\lib\ .\demo\2.1Window+Label\
2	2.2Window+Label+循环刷新	.\luatos-lua.exe .\lib\ .\demo\2.2Window+Label\
3	2.3Window+Button文本模式	.\luatos-lua.exe .\lib\ .\demo\2.3Window+Button\
4	2.4Window+Button图标模式	.\luatos-lua.exe .\lib\ .\demo\2.4Window+Button\
5	2.5Window+ProgressBar静态	.\luatos-lua.exe .\lib\ .\demo\2.5Window+ProgressBar\
6	2.6Window+ProgressBar动态	.\luatos-lua.exe .\lib\ .\demo\2.6Window+ProgressBar\
7	2.7Window+MessageBox	.\luatos-lua.exe .\lib\ .\demo\2.7Window+MessageBox\
8	2.8Window+CheckBox	.\luatos-lua.exe .\lib\ .\demo\2.8Window+CheckBox\
9	2.9Window+Picture单图模式	.\luatos-lua.exe .\lib\ .\demo\2.9Window+Picture\
10	2.10Window+Picture轮播模式	.\luatos-lua.exe .\lib\ .\demo\2.10Window+Picture\
11	2.11Allcomponent全部控组	.\luatos-lua.exe .\lib\ .\demo\2.11Allcomponent\
12	2.12Horizontal_slidin_page横向滑动	.\luatos-lua.exe .\lib\ .\demo\2.12Horizontal_slidin_page\
13	2.13Vertical_sliding_page纵向滑动	.\luatos-lua.exe .\lib\ .\demo\2.13Vertical_sliding_page\
14	2.14Switch_page页面切换	.\luatos-lua.exe .\lib\ .\demo\2.14Switch_page\
15	2.15gtfont矢量字体	.\luatos-lua.exe .\lib\ .\demo\2.15gtfont\

四、客户可能的疑问

1、PC 模拟器实现的功能，真实模组能否实现；

答：提供的 demo 根据实际接线配置好引脚，能够直接烧录到支持 lcd 库的设备上进行运行，需要显示中文的则要使用支持 12 号中文字体的型号；

2、PC 模拟器上体现的速度和真实设备有区别吗？

答：pc 性能更强刷新率会稳定一些，soc 上图片比较多时，刷新率会降低，实现效果相同；

五、核心示例（滑动窗口从上到下展示各组件）

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

PROJECT = "exEasyUI_demo"
VERSION = "1.0.0"

sys = require("sys")
local ui = require("exeasyui")

sys.taskInit(function()
    sys.wait(500)
    -- 依赖 screen_data_table.lua 内的 lcdargs/touch 参数
    ui.hw.init({})
    ui.init({ theme = "light" })

    local win = ui.Window({ backgroundColor = ui.COLOR_WHITE })
    -- 内容高度较大，启用纵向滚动
    win:enableScroll({ direction = "vertical", contentHeight = 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", onClick = function(self)
        log.info("demo", "button clicked")
    end })
    win:add(btn)

    -- 2) Toggle按钮（v1.6.0：Button支持toggle功能）
    local tb = ui.Button({ x = 20, y = place(64), w = 64, h = 64, 
        src = "/luadb/icon.jpg", toggle = true, 
        onToggle = function(t) log.info("demo", "toggled", t) end 
    })
    win:add(tb)

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

    -- 4) Label（v1.6.0：支持自动换行）
    local lbl = ui.Label({ x = 20, y = place(60), w = 280, wordWrap = 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) MessageBox（作为静态面板展示）
    local box = ui.MessageBox({ x = 20, y = place(120), w = 280, h = 120, title = "MessageBox", message = "Info Panel", buttons = {"OK"}, onResult = function(r)
        log.info("demo", "msgbox", r)
    end })
    win:add(box)

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

    ui.add(win)

    while true do
        ui.clear()
        ui.render()
        sys.wait(30)
    end
end)

sys.run()

六、常量详解

6.1 基础颜色常量

6.2 Windows 11 风格颜色（v1.6.0 新增）

Light 模式：

Dark 模式：

以上颜色常量均由 ui 导出，可直接通过 ui.COLOR_WHITE 等方式使用。 Window 和 Button 组件在 light 主题下默认使用 Windows 11 Light 配色，dark 主题下使用 Dark 配色。

七、组件 API 详解

本节对每个组件提供：功能说明、构造参数、方法、事件、示例。

7.1 Button（按钮）

功能

多功能按钮组件，支持文本按钮、图片按钮、Toggle 切换按钮（v1.6.0 合并 ToolButton 功能）。

构造：ui.Button(args)

参数 ：args

{
    x = , y = ,
    -- 参数含义：左上角坐标；
    -- 数据类型：number；
    -- 是否必选：可选，默认0；

    w = , h = ,
    -- 参数含义：宽/高；
    -- 数据类型：number；
    -- 是否必选：可选，默认 w=100, h=36；

    -- 文本模式参数
    text = ,
    -- 参数含义：按钮文字；
    -- 数据类型：string；
    -- 是否必选：可选，默认"Button"；

    textSize = ,
    -- 参数含义：文字字号；
    -- 数据类型：number；
    -- 是否必选：可选；

    bgColor = , textColor = , borderColor = ,
    -- 参数含义：背景/文本/边框颜色；
    -- 数据类型：number（RGB565）；
    -- 是否必选：可选，浅色主题默认Windows 11配色；

    -- 图片模式参数（v1.6.0新增）
    src = ,
    -- 参数含义：普通态图片路径；
    -- 数据类型：string；
    -- 是否必选：可选，有此参数时按钮显示为图片；
    -- 说明：v1.6.1起会检查文件是否存在，不存在时显示占位符并输出警告日志；

    src_pressed = ,
    -- 参数含义：按下态图片路径；
    -- 数据类型：string；
    -- 是否必选：可选；

    src_toggled = ,
    -- 参数含义：切换态图片路径（toggle=true时使用）；
    -- 数据类型：string；
    -- 是否必选：可选；

    -- Toggle模式参数（v1.6.0新增）
    toggle = ,
    -- 参数含义：是否为Toggle切换按钮；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认false；

    toggled = ,
    -- 参数含义：初始切换状态；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认false；

    onToggle = ,
    -- 参数含义：切换回调；
    -- 数据类型：function(toggled, self)；
    -- 是否必选：可选；

    onClick = 
    -- 参数含义：点击回调；
    -- 数据类型：function(self)；
    -- 是否必选：可选；
}

方法

setText(newText)         -- 设置按钮文字

事件

SINGLE_TAP: 调用 onClick(self)

示例

-- 1. 文本按钮（使用默认配色）
local btn1 = ui.Button({
    x = 20, y = 40, w = 120, h = 44,
    text = "确定",
    onClick = function() log.info("btn", "clicked") end
})

-- 2. 图片按钮（有按下态）
local btn2 = ui.Button({
    x = 20, y = 100, w = 64, h = 64,
    src = "/luadb/icon.jpg",
    src_pressed = "/luadb/icon_pressed.jpg",
    onClick = function() log.info("img btn", "clicked") end
})

-- 3. Toggle按钮
local btn3 = ui.Button({
    x = 20, y = 180, w = 64, h = 64,
    src = "/luadb/off.jpg",
    src_toggled = "/luadb/on.jpg",
    toggle = true,
    onToggle = function(state)
        log.info("toggle", state and "ON" or "OFF")
    end
})

Button.setText

功能

设置按钮文字。

签名

Button:setText(newText)

参数

newText
-- 参数含义：新的按钮文本
-- 数据类型：string
-- 是否必选：是

返回值

无

示例

local b = ui.Button({ x = 20, y = 40, text = "原文" })
b:setText("确定")

7.2 CheckBox（复选框）

功能

布尔选择控件。

构造：ui.CheckBox(args)

参数 ：args

{
    x = , y = ,
    -- 参数含义：位置；
    -- 数据类型：number；

    boxSize = ,
    -- 参数含义：复选框边长；
    -- 数据类型：number；
    -- 是否必选：可选，默认16；

    text = ,
    -- 参数含义：右侧文本；
    -- 数据类型：string；

    checked = ,
    -- 参数含义：初始选中状态；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认false；

    onChange = ,
    -- 参数含义：状态改变回调；
    -- 数据类型：function(checked)；

    textColor = , borderColor = , bgColor = , tickColor = ,
    -- 参数含义：颜色（文本/边框/背景/选中块）；
    -- 数据类型：number；
}

方法

setChecked(v)
toggle()

CheckBox.setChecked

功能

设置复选框选中状态。

签名

CheckBox:setChecked(v)

参数

v
-- 参数含义：目标选中状态
-- 数据类型：boolean
-- 是否必选：是

返回值

无

示例

local cb = ui.CheckBox({ x=20, y=160, text="启用" })
cb:setChecked(true)

CheckBox.toggle

功能

切换当前选中状态。

签名

CheckBox:toggle()

参数 / 返回值

无

示例

cb:toggle()

事件

SINGLE_TAP: 点击区域内部时切换并调用 onChange(checked)

示例

local cb = ui.CheckBox({ 
    x = 20, y = 160, text = "启用", 
    onChange = function(v) log.info("cb", v) end 
})

7.3 Label（文本标签）

功能

静态文本显示，支持自动换行（v1.6.0 新增）。

构造：ui.Label(args)

参数 ：args

{
    x = , y = ,
    -- 参数含义：位置；
    -- 数据类型：number；

    text = ,
    -- 参数含义：文本内容；
    -- 数据类型：string；

    w = ,
    -- 参数含义：最大宽度（v1.6.0）；
    -- 数据类型：number；
    -- 是否必选：可选，未指定时自动计算；
    -- 说明：指定后，无换行时超出部分截断，有换行时在此宽度内换行；

    wordWrap = ,
    -- 参数含义：是否启用自动换行（v1.6.0）；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认false；
    -- 说明：启用后在w宽度内智能换行（英文按单词，中文按字符）；

    color = ,
    -- 参数含义：文本颜色；
    -- 数据类型：number；
    -- 是否必选：可选，默认随主题；

    size = ,
    -- 参数含义：字号；
    -- 数据类型：number；
    -- 是否必选：可选；

    font = 
    -- 参数含义：自定义字体句柄（默认后端时生效）；
    -- 数据类型：userdata；
}

方法

setText(t)
setSize(sz)

Label.setText

功能

设置文本内容。

签名

Label:setText(t)

参数

t
-- 参数含义：新文本
-- 数据类型：string
-- 是否必选：是

返回值

无

示例

local lbl = ui.Label({ x = 20, y = 200, text = "Hello" })
lbl:setText("World")

Label.setSize

功能

设置字号，并按需调整宽高。

签名

Label:setSize(sz)

参数

sz
-- 参数含义：字号
-- 数据类型：number
-- 是否必选：是

返回值

无

示例

lbl:setSize(20)

示例

-- 1. 基础文本
local lbl1 = ui.Label({ x = 20, y = 200, text = "Hello exEasyUI" })

-- 2. 文本截断（超出w则截断）
local lbl2 = ui.Label({ 
    x = 20, y = 230, w = 200,
    text = "这是一段很长的文本会被截断" 
})

-- 3. 自动换行（v1.6.0）
local lbl3 = ui.Label({ 
    x = 20, y = 260, w = 280, wordWrap = true,
    text = "This is a long text that demonstrates automatic word wrapping feature in exEasyUI v1.6.0."
})

7.4 Picture（图片/轮播）

功能

显示单图或多图轮播。v1.6.1 起，图片文件不存在时会显示占位符（灰色背景 + 白色边框 +X 叉）。

构造：ui.Picture(args)

参数 ：args

{
    x = , y = , w = , h = ,
    -- 参数含义：位置与尺寸；
    -- 数据类型：number；
    -- 说明：v1.6.1建议使用正方形或接近正方形尺寸以获得最佳占位符显示效果；

    src = ,
    -- 参数含义：单张图片路径；
    -- 数据类型：string；
    -- 说明：v1.6.1起会检查文件是否存在，不存在时显示占位符并输出警告日志；

    sources = ,
    -- 参数含义：多张图片路径列表；
    -- 数据类型：table，如 { "/luadb/a.jpg", "/luadb/b.jpg" }；

    autoplay = ,
    -- 参数含义：是否自动轮播（sources 有多图时生效）；
    -- 数据类型：boolean，默认false；

    interval = 
    -- 参数含义：轮播间隔（毫秒）；
    -- 数据类型：number，默认1000；
}

方法

setSources(list)
next()
prev()
play()
pause()

Picture.setSources

功能

设置图片列表并重置索引。

签名

Picture:setSources(list)

参数

list
-- 参数含义：图片路径数组
-- 数据类型：table，如 {"/luadb/a.jpg", "/luadb/b.jpg"}

返回值

无

示例

pic:setSources({ "/luadb/1.jpg", "/luadb/2.jpg" })

Picture.next / Picture.prev

功能

切换到下一张 / 上一张（在 sources 存在时）。

签名

Picture:next()
Picture:prev()

参数 / 返回值

无

示例

pic:next()
pic:prev()

Picture.play / Picture.pause

功能

开启 / 暂停自动轮播。

签名

Picture:play()
Picture:pause()

参数 / 返回值

无

示例

pic:play()
sys.wait(2000)
pic:pause()

示例

-- 单图显示
local pic1 = ui.Picture({ 
    x = 20, y = 240, w = 120, h = 90,
    src = "/luadb/image.jpg" 
})

-- 自动轮播
local pic2 = ui.Picture({ 
    x = 20, y = 350, w = 120, h = 90,
    sources = {"/luadb/a.jpg", "/luadb/b.jpg"}, 
    autoplay = true 
})

7.5 MessageBox（消息框/面板）

功能

展示标题、内容与按钮组，支持消息自动换行（v1.6.0 新增），支持复用与动态更新（v1.6.1 新增）。

构造：ui.MessageBox(args)

参数 ：args

{
    x = , y = , w = , h = ,
    -- 参数含义：位置与尺寸；
    -- 数据类型：number；

    title = ,
    -- 参数含义：标题文本；
    -- 数据类型：string，默认"Info"；

    message = ,
    -- 参数含义：内容文本；
    -- 数据类型：string；

    wordWrap = ,
    -- 参数含义：消息是否自动换行（v1.6.0）；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认true（v1.6.1起）；
    -- 说明：启用后消息在固定高度内智能换行，超出部分截断；

    visible = ,
    -- 参数含义：初始是否可见（v1.6.1修复）；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认true；

    enabled = ,
    -- 参数含义：初始是否可交互（v1.6.1修复）；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认true；

    textSize = ,
    -- 参数含义：文本字号；
    -- 数据类型：number；
    -- 是否必选：可选；

    buttons = ,
    -- 参数含义：按钮文本数组；
    -- 数据类型：table，默认 {"OK"}；
    -- 说明：可传入空数组 {} 创建无按钮的MessageBox；

    onResult = ,
    -- 参数含义：按钮点击回调；
    -- 数据类型：function(label)；

    borderColor = , textColor = , bgColor = ,
    -- 参数含义：边框/文本/背景颜色；
    -- 数据类型：number；
}

方法

show()                   -- 显示MessageBox（v1.6.1新增）
hide()                   -- 隐藏MessageBox（v1.6.1新增）
setTitle(title)          -- 动态更新标题（v1.6.1新增）
setMessage(message)      -- 动态更新消息内容（v1.6.1新增）

事件

内部按钮 SINGLE_TAP: 调用 onResult(label)

MessageBox 子方法

MessageBox.show

功能

显示 MessageBox（设置 visible 和 enabled 为 true）。v1.6.1 新增，用于 MessageBox 复用。

签名

MessageBox:show()

参数 / 返回值

无

示例

msgbox:show()

MessageBox.hide

功能

隐藏 MessageBox（设置 visible 为 false）。v1.6.1 新增，用于 MessageBox 复用。

签名

MessageBox:hide()

参数 / 返回值

无

示例

msgbox:hide()

MessageBox.setTitle

功能

动态更新 MessageBox 标题。v1.6.1 新增。

签名

MessageBox:setTitle(title)

参数

title
-- 参数含义：新标题文本
-- 数据类型：string
-- 是否必选：是

返回值

无

示例

msgbox:setTitle("警告")

MessageBox.setMessage

功能

动态更新 MessageBox 消息内容。v1.6.1 新增，如启用了自动换行会自动重新计算行数。

签名

MessageBox:setMessage(message)

参数

message
-- 参数含义：新消息文本
-- 数据类型：string
-- 是否必选：是

返回值

无

示例

msgbox:setMessage("更新后的消息内容")

示例

-- 1. 简单提示
local box1 = ui.MessageBox({ 
    x = 20, y = 340, w = 280, h = 120,
    title = "提示", message = "操作成功", 
    buttons = {"确定"},
    onResult = function(r) log.info("msg", r) end 
})

-- 2. 长消息自动换行（v1.6.0，v1.6.1起默认开启）
local box2 = ui.MessageBox({ 
    x = 20, y = 340, w = 280, h = 160,
    title = "提示",
    message = "这是一段很长的提示消息，启用自动换行后会在固定宽度内智能分行显示，超出高度的部分会被截断。",
    buttons = {"知道了"}
})

-- 3. MessageBox复用（v1.6.1推荐方式）
-- 创建时设置为初始隐藏
local msgbox = ui.MessageBox({ 
    x = 20, y = 340, w = 280, h = 120,
    title = "提示", 
    message = "初始消息", 
    visible = false,  -- 初始隐藏
    buttons = {"确定"},
    onResult = function(r) 
        msgbox:hide()  -- 点击后隐藏而非禁用
    end 
})
win:add(msgbox)

-- 多次复用同一个MessageBox
local btn1 = ui.Button({ 
    x = 20, y = 40, w = 120, h = 44, 
    text = "显示消息1",
    onClick = function()
        msgbox:setTitle("通知")
        msgbox:setMessage("这是第一条消息")
        msgbox:show()
    end 
})

local btn2 = ui.Button({ 
    x = 160, y = 40, w = 120, h = 44, 
    text = "显示消息2",
    onClick = function()
        msgbox:setTitle("警告")
        msgbox:setMessage("这是第二条消息")
        msgbox:show()
    end 
})

-- 4. 无按钮MessageBox（信息面板）
local infoPanel = ui.MessageBox({ 
    x = 20, y = 480, w = 280, h = 100,
    title = "系统状态",
    message = "运行正常\n内存使用: 45%",
    buttons = {}  -- 无按钮
})

-- 5. 动态更新示例（如实时显示时间）
sys.taskInit(function()
    while true do
        local time = os.date("%H:%M:%S")
        msgbox:setMessage("当前时间: " .. time)
        sys.wait(1000)
    end
end)

7.6 ProgressBar（进度条）

功能

显示百分比进度，可附带文本。

构造：ui.ProgressBar(args)

参数 ：args

{
    x = , y = , w = , h = ,
    -- 参数含义：位置与尺寸；
    -- 数据类型：number；

    progress = ,
    -- 参数含义：进度百分比 0~100；
    -- 数据类型：number，默认0；

    text = , textSize = ,
    -- 参数含义：文本与字号；
    -- 数据类型：string/number；

    backgroundColor = , progressColor = , borderColor = , textColor = ,
    -- 参数含义：配色（背景/进度/边框/文本）；
    -- 数据类型：number；

    showPercentage = 
    -- 参数含义：是否显示百分比文本；
    -- 数据类型：boolean，默认true；
}

方法

setProgress(v)
getProgress()
setText(text)

ProgressBar.setProgress

功能

设置进度百分比。

签名

ProgressBar:setProgress(v)

参数

v
-- 参数含义：目标进度 0~100
-- 数据类型：number
-- 是否必选：是

返回值

无

示例

pb:setProgress(75)

ProgressBar.getProgress

功能

获取当前进度值。

签名

ProgressBar:getProgress()

参数

无

返回值

number -- 当前进度 0~100

示例

local v = pb:getProgress()
log.info("pb", v)

ProgressBar.setText

功能

设置显示文本（可覆盖百分比显示）。

签名

ProgressBar:setText(text)

参数

text
-- 参数含义：文本内容
-- 数据类型：string
-- 是否必选：是

返回值

无

示例

pb:setText("下载中...")

示例

-- 基础进度条
local pb = ui.ProgressBar({ 
    x = 20, y = 480, w = 280, h = 26, 
    progress = 40 
})

-- 带自定义文本
local pb2 = ui.ProgressBar({ 
    x = 20, y = 520, w = 280, h = 26, 
    progress = 65, text = "下载中..." 
})

八、Window 使用模式说明

本节采用与上文一致的结构，分别介绍 Window 的创建与参数、子方法以及子页面（子窗口）使用方式。

8.1 Window（窗口容器）创建与参数

功能

窗口容器，用作页面根节点或子页面载体。支持背景色/背景图、子组件管理、滚动与分页、子页面导航等。

构造：ui.Window(args)

参数 ：args

{
    x = , y = ,
    -- 参数含义：窗口左上角坐标；
    -- 数据类型：number；
    -- 是否必选：可选，默认0；

    w = , h = ,
    -- 参数含义：窗口宽/高；
    -- 数据类型：number；
    -- 是否必选：可选，默认填满屏幕（lcd.getSize()）；

    backgroundImage = ,
    -- 参数含义：背景图片路径（.jpg）；
    -- 数据类型：string；
    -- 是否必选：可选；

    backgroundColor = ,
    -- 参数含义：背景颜色（RGB565）；
    -- 数据类型：number；
    -- 是否必选：可选，浅色主题默认Windows 11配色；

    visible = , enabled = ,
    -- 参数含义：可见/可交互；
    -- 数据类型：boolean；
    -- 是否必选：可选，默认 true；
}

示例

-- 使用默认配色（v1.6.0：浅色主题自动使用Windows 11配色）
local win = ui.Window()
ui.add(win)

8.2 Window 子方法

方法

add(child)                    -- 添加子组件
remove(child)                 -- 移除子组件
clear()                       -- 清空子组件

setBackgroundImage(path)      -- 设置背景图
setBackgroundColor(color)     -- 设置背景色（并清除背景图）

enableScroll(opts)            -- 启用滚动/分页（纵向/横向/双向）
setContentSize(w, h)          -- 设置内容区尺寸（影响滚动边界）

enableSubpageManager(opts)    -- 启用子页面管理（一次开启即可）
configureSubpages(factories)  -- 注册子页面工厂{name->function}
showSubpage(name[, factory])  -- 显示子页面；如未缓存则调用工厂创建
back()                        -- 关闭当前子页面，返回父窗口
closeSubpage(name, opts)      -- 关闭指定子页面；opts.destroy=true 彻底销毁

enableScroll(opts)

opts = {
    direction = "vertical" | "horizontal" | "both", -- 滚动方向，默认 "vertical"
    contentWidth  = <number>,  -- 内容宽度（默认等于窗口宽度）
    contentHeight = <number>,  -- 内容高度（默认等于窗口高度）
    threshold = <number>,      -- 判定拖拽门限像素，默认10
    pagingEnabled = <boolean>, -- 横向分页吸附开关（横向/双向时生效）
    pageWidth = <number>,      -- 分页宽度，默认窗口宽度
}

示例：纵向滚动列表

local win = ui.Window({ backgroundColor = ui.COLOR_WHITE })
win:enableScroll({ direction = "vertical", contentHeight = 1200, threshold = 8 })
-- 之后 add 的子组件会随滚动偏移显示

示例：横向分页（桌面式）

local win = ui.Window({ backgroundColor = ui.COLOR_WHITE })
win:enableScroll({ direction = "horizontal", pagingEnabled = true, pageWidth = 320, contentWidth = 320 * 3 })

8.2.1 Window.add

功能

向窗口添加一个子组件（任何实现了 draw/handleEvent 的组件）。

签名

Window:add(child)

参数

child
-- 参数含义：要添加的组件实例
-- 数据类型：table（组件对象）
-- 是否必选：是

返回值

无

示例

local btn = ui.Button({ x=20, y=40, w=120, h=44, text="OK" })
win:add(btn)

8.2.2 Window.remove

功能

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

签名

Window:remove(child)

参数

child
-- 参数含义：要移除的组件实例
-- 数据类型：table（组件对象）
-- 是否必选：是

返回值

boolean -- 是否成功移除

示例

win:remove(btn)

8.2.3 Window.clear

功能

清空窗口的所有子组件。

签名

Window:clear()

参数 / 返回值

无

示例

win:clear()

8.2.4 Window.setBackgroundImage

功能

设置窗口背景图。

签名

Window:setBackgroundImage(path)

参数

path
-- 参数含义：.jpg 图片路径
-- 数据类型：string
-- 是否必选：是

返回值

无

示例

win:setBackgroundImage("/luadb/wallpaper.jpg")

8.2.5 Window.setBackgroundColor

功能

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

签名

Window:setBackgroundColor(color)

参数

color
-- 参数含义：RGB565 颜色值
-- 数据类型：number
-- 是否必选：是

返回值

无

示例

win:setBackgroundColor(ui.COLOR_WHITE)

8.2.6 Window.enableScroll

功能

启用窗口内容的拖拽滚动与可选的横向分页吸附。

签名

Window:enableScroll(opts)

参数

opts
-- 参数含义：滚动/分页配置
-- 数据类型：table（见上文 enableScroll(opts) 配置项）
-- 是否必选：否

返回值

Window -- 返回自身，便于链式调用

示例

win:enableScroll({ direction = "vertical", contentHeight = 1200 })

8.2.7 Window.setContentSize

功能

设置内容区尺寸（影响滚动边界的计算），通常在 enableScroll 后调用。

签名

Window:setContentSize(w, h)

参数

w, h
-- 参数含义：内容宽/高
-- 数据类型：number
-- 是否必选：至少提供其一

返回值

无

示例

win:setContentSize(320, 1200)

8.3 子页面（Subpage）使用

Window 内置子页面管理能力，便于在单窗口内组织多级页面与导航返回。

启用与注册

local home = ui.Window({ backgroundColor = 0xFFFF })
-- 一次启用（可省略，首次调用会自动启用）
home:enableSubpageManager({
    backEventName = "NAV.BACK",          -- 可选；默认 "NAV.BACK"
    onBack = function() log.info("nav", "back pressed") end, -- 可选
})

-- 注册子页面工厂（返回一个 Window 实例）
home:configureSubpages({
    settings = function() return require("settings_page").create(ui) end,
    about    = function() return require("about_page").create(ui) end,
})

8.3.1 Window.enableSubpageManager

功能

启用子页面管理能力，注册返回事件及可选回调；通常调用一次即可。

签名

Window:enableSubpageManager(opts)

参数

opts
-- 参数含义：可选项
-- 数据类型：table
-- 字段：
--   backEventName: string，返回事件名，默认 "NAV.BACK"
--   onBack: function()，收到返回事件时回调（在父窗口范围）

返回值

Window -- 返回自身

示例

home:enableSubpageManager({ backEventName = "NAV.BACK" })

8.3.2 Window.configureSubpages

功能

注册子页面工厂表；当使用 showSubpage 时按名称创建并缓存子页面。

签名

Window:configureSubpages(factories)

参数

factories
-- 参数含义：工厂表 { name -> function() return Window end }
-- 数据类型：table
-- 是否必选：是

返回值

Window -- 返回自身

示例

home:configureSubpages({ settings = function() return require("settings_page").create(ui) end })

8.3.3 Window.showSubpage

功能

显示指定名称的子页面；如未创建则调用工厂创建并缓存；显示子页面时会隐藏当前窗口。

签名

Window:showSubpage(name[, factory])

参数

name
-- 参数含义：子页面名称
-- 数据类型：string
-- 是否必选：是

factory
-- 参数含义：备用工厂（当未通过 configureSubpages 注册时提供）
-- 数据类型：function() -> Window
-- 是否必选：否

返回值

无

示例

home:showSubpage("settings")

8.3.4 Window.back

功能

在子页面中调用，使当前子页面隐藏，并在父窗口无其他子页面可见时恢复父窗口可见/可交互。

签名

Window:back()

参数 / 返回值

无

示例

self:back()

8.3.5 Window.closeSubpage

功能

关闭指定名称的子页面；当 opts.destroy=true 时从缓存中删除并触发垃圾回收。

签名

Window:closeSubpage(name, opts)

参数

name
-- 参数含义：子页面名称
-- 数据类型：string
-- 是否必选：是

opts
-- 参数含义：关闭选项
-- 数据类型：table
-- 字段：
--   destroy: boolean，是否销毁缓存

返回值

boolean -- 是否存在并处理该子页面

示例

home:closeSubpage("settings", { destroy = true })

8.3.6 返回事件（NAV.BACK）

功能

通过发布返回事件触发 onBack 回调；若没有任一子页面可见，则自动恢复父窗口可见。

签名

sys.publish("NAV.BACK")

示例

sys.publish("NAV.BACK")

完整示例

local home = ui.Window({ backgroundColor = 0xFFFF })
home:configureSubpages({
    checkbox = function() return require("checkbox_page").create(ui) end,
    msgbox   = function() return require("msgbox_page").create(ui) end,
})

local btn = ui.Button({ x = 20, y = 60, w = 280, h = 50, text = "进入子页", onClick = function()
    home:showSubpage("checkbox")
end })
home:add(btn)
ui.add(home)