跳转至

3 airui-功能强大的图形化开发

作者：江访　|　最后修改：2026-05-13

一、概述

  • airui 是基于 LVGL 9.4 版本进行图形层封装的 LuatOS 核心库，把常用组件、事件管理、输入和基础视觉主题封装为更易上手的 Lua 接口，便于在支持 LuatOS 的设备和 PC 上统一开发。

  • 推荐搭配exwin UI 窗口管理扩展库 一起使用

  • 当前最新版本为 V1.2.1 支持组件 20+ 个，组件分类如下：

显示类组件
标签、图片、进度条、表格、曲线图、二维码、动画图像、形状、加载指示器(spinner)、视频(video)
交互类组件
标签、图片、开关、按钮、下拉框、消息框、容器
输入类组件
下拉框、输入框(支持中文输入)、键盘
布局类组件
容器、选项卡、窗口

AirUI 更新内容请看：七、AirUI更新说明，最新 V1.2.1 配套固件和 PC 端下载链接如下：

AirUI最新版本
支持模块
支持固件版本
支持PC端版本
demo链接
V1.1.6
Air8101
V2012 104号

V2023
点击跳转Air8101 demo
Air8000
V2032
14/114/15/115/
16/116号

1、点击跳转Air8000 组件基本功能演示demo
2、点击跳转Air8000 组件详细功能演示demo
3、点击跳转Air8000 UI+业务功能演示demo
Air700ECH
V2032
14/114/15/115/
16/116号

点击跳转Air780EHX系列 demo
Air780EHM/EGH/EHV/EHU/EHN
Air1601/Air1602
V2004

点击跳转Air1601 demo

主要特性

  1. 组件丰富：内置标签、图片、按钮、开关、进度条、下拉框、输入框、键盘、表格、容器、选项卡、窗口、曲线图、二维码、动画图像、形状、加载指示器(spinner)、视频(video) 等 20+ 核心组件;
  2. 更低成本：可选 免费的 hzfont 矢量字体支持 12-255 号，节省字库成本;
  3. 开发高效：用更少代码快速搭建可量产的触控界面，参考示例代码能快速掌握原理，还可以参考使用 AI 生成 AirUI 项目使开发更快;
  4. 验证便捷：提供 LuatOS windows桌面系统 快速验证效果，无需烧录就能看到代码运行效果;
  5. 持续更新：更多组件持续更新中。当前版本为：V1.2.1，点击下载 AirUI 演示 demo 搭配 V2023 及以上版本 LuatOS windows桌面系统进行体验，更新细节请看：章节七、AirUI更新说明

  6. 支持 LuatOS windows桌面系统 (SDL2) 和真机两种模式：

  7. 当前LuatOS windows桌面系统支持Lottie动画和键盘输入；

  8. PC端仅支持window 10/11系统；
  9. 真机支持Air8101、Air8000系列、Air780EHM/EGH/EHV、Air1601/Air1602等；

  1. 支持中文输入

  2. 初始化hzfont是中文输入的前提条件，按4.1.4 airui.font_load(config)进行字体初始化

  3. 先按4.2.9.1 airui.keyboard(config)创建键盘
  4. 再按4.2.10.1 airui.textarea(config)创建输入框并通过keyboard参数绑定键盘，点击输入框即可进行中文/英文/数字/符号的输入

注意事项

  • 如需想快速知道哪些设备支持 AirUI 核心库，可以查看选型手册对应型号及固件是否支持，
  • AirUI 使用的是 lcd 核心库初始化显示设备，详细说明见 lcd 核心库内置驱动型号，当前 lcd 核心库内置显示驱动的型号有
序号
内置显示IC驱动型号
已支持的模组型号
支持接口
支持最大分辨率
模组开发板购买链接
LCD模组购买链接
LCD模组使用文档/demo
1
st7735/s/v
Air780EPM
Air780EHM/EGH/
EGG/EHV/
EHU/EHN/
Air700ECH
Air8000
LCD专业SPI接口/通用SPI接口
480*320
-
-
-
2
st7789
-
-
-
3
st7796
模组开发板购买链接
LCD模组购买链接
LCD模组使用demo
4
gc9a01
-
-
-
5
gc9106l
-
-
-
6
gc9306x
-
-
-
7
ili9341
-
-
-
8
ili9486
-
-
-
9
nv3037
-
-
-
10
hx8282
Air8101
Air1601
RGB接口
1280*720
-
-
-
11
nv3052c
-
-
-
12
st7701sn
-
-
-
13
h050iwv
模组开发板购买链接
LCD模组购买链接
LCD模组使用demo
14
co5300
Air780EHM/EGH
/EGG/EHV/
EHU/EHN
Air8000
QSPI接口
720*720
-
-
-
15
jd9261t
-
-
-
16
sh8601z
-
-
-
  • AirUI 使用的是 tp 核心库初始化触摸设备，详细说明见 tp 核心库内置驱动型号，当前 tp 核心库内置显示驱动的型号有
序号
支持触摸IC型号
已支持的模组型号
支持接口
1
gt911
Air780EPM
Air780EHM/EGH
/EGG/EHV
/EHU/EHN/
Air700ECH
Air8000系列
Air8101
Air1601
硬件I2C
软件I2C
2
gt9157
3
cst820
4
jd9261t
5
ft3x68
  • 触摸初始化得到的数据result，需要传给airui.indev_bind_touch(result)进行绑定触摸才能生效
  • SPI接口、QSPI的屏幕如需修改屏幕显示尺寸、方向等参数，可以参考lcd核心库显示初始化接口说明,目前RGB接口的屏幕不支持修改屏幕显示方向
  • 触摸初始化和显示初始化有两个相同的参数，w和h，这两个参数加上显示的方向，确定触摸和显示的原点(0,0)位置；
  • 当触摸初始化在显示初始化后面，触摸的w和h参数不传入默认使用的显示初始所设置w和h参数；
  • 当触摸初始化在显示初始化前面，触摸的w和h参数就必须要传入；

  • 当触摸初始化的w和h参数传入了，在设置显示方向旋转90度或270度时，显示和触摸的w和h参数也需要随之对调；

  • AirUI、hzfont、12 号中文字库属于不同的核心库，如需显示中文，选择固件除支持 AirUI 核心库外须再支持 hzfont 和 12 号中文字库中的一种

二、核心示例

2.1 核心代码

本演示项目采用模块化设计，通过 main.lua 统一管理各演示模块的加载。 硬件初始化在 lcd_drv.lua（或 lcd_inner_drv.lua/lcd_custom_drv.lua）和 tp_drv.lua 中完成，各演示模块只需关注 UI 组件创建。

屏幕分辨率适配说明： - Air8101：800x480（横屏），demo 使用 800x480 布局 - Air8000/Air780E 系列：320x480（竖屏），demo 已适配 320x480 布局 - Air1601/Air1602：1024x600（横屏），demo 使用页面模块架构，适配 1024x600 布局 - 演示代码以 Air8101（800x480）为例；其他型号请参考对应型号的 demo 目录

main.lua - 程序入口：

-- 加载显示驱动（自动初始化LCD和AirUI）
require("lcd_drv")
-- 加载触摸驱动（自动初始化触摸并绑定AirUI）
require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
-- require("airui_label")     -- 动态更新标签演示
-- require("airui_button")    -- 按钮演示
-- require("airui_image")     -- 图片显示演示
-- require("airui_container") -- 容器演示
-- require("airui_bar")       -- 动态进度条演示
-- require("airui_dropdown")  -- 下拉框演示
-- require("airui_switch")    -- 开关组件演示
-- require("airui_msgbox")    -- 消息框组件演示
-- require("airui_input")     -- 输入框和键盘演示
-- require("airui_tabview")   -- 选项卡演示
-- require("airui_table")     -- 表格演示
-- require("airui_win")       -- 窗口演示
-- require("airui_all_component") -- 所有组件综合演示
-- require("airui_switch_page")   -- 页面切换演示
-- require("airui_hzfont")    -- 内置软件矢量字体演示
-- require("airui_chart")     -- 图表组件演示
-- require("airui_qrcode")    -- 二维码组件演示
-- require("airui_animimg")   -- 动画图像组件演示
-- require("airui_shape")     -- 形状组件演示
-- require("airui_spinner")   -- 加载指示器组件演示
-- require("airui_video")     -- 视频组件演示

lcd_drv.lua - LCD 显示驱动（自动初始化）：

local function lcd_drv_init()
    local result = lcd.init("h050iwv",
        {
            pin_pwr = 8,
            port = lcd.RGB,
            direction = 0,
            w = 800,
            h = 480,
            xoffset = 0,
            yoffset = 0,
        })
    log.info("lcd.init", result)

    if result then
        lcd.setupBuff(nil, true)
        lcd.autoFlush(false)

        -- 初始化AirUI
        local width, height = lcd.getSize()
        local result = airui.init(width, height)
        if not result then
            log.error("airui", "init failed")
            return result
        end

        -- 加载中文字体（根据平台选择）
        if rtos.bsp() ~= "Air8101" then
            -- Air8000/780EHM 从14号/114号固件中加载内置hzfont字库
            airui.font_load({
                type = "hzfont",
                path = nil,
                size = 20,
                cache_size = 1024,
                antialias = 1,
            })
        else
            -- Air8101 使用104号固件从文件系统加载ttf字库
            airui.font_load({
                type = "hzfont",
                path = "/MiSans_gb2312.ttf",
                size = 20,
                cache_size = 1024,
                antialias = 1,
                global = true
            })
        end

        -- 开启背光引脚供电
        gpio.setup(8, 1)

        -- 查询AirUI版本
        log.info("airui", "version -> " .. airui.version())
        return result
    end
end

lcd_drv_init()

tp_drv.lua - 触摸面板驱动（自动初始化）：

local function tp_drv_init()
    local result = i2c.createSoft(0, 1)
    if type(result) ~= "userdata" then
        log.error("tp_drv.init i2c.createSoft error")
        return false
    end

    result = tp.init("gt911", {
        port = result,
        pin_rst = 28,
        pin_int = 7,
        w = 800,
        h = 480
    })
    log.info("tp.init", result)

    if rtos.bsp() ~= "PC" then
        airui.device_bind_touch(result)
    else
        if not result then
            log.error("ui_main", "触摸初始化失败")
            return result
        else
            return airui.device_bind_touch(result)
        end
    end
end

tp_drv_init()

演示模块代码结构（以标签为例）：

local function ui_main()
    -- 初始化硬件（由main.lua中的lcd_drv和tp_drv自动完成）

    -- 创建标签
    local label = airui.label({
        text = "Hello, World!",
        x = 20,
        y = 80,
        w = 100,
        h = 40,
    })

end

sys.taskInit(ui_main)

2.2 使用合宙 LuatOS windows桌面系统运行 AirUI

2.2.1 LuatOS windows桌面系统运行 AirUI效果

组件
输入法



2.2.2 LuatOS windows桌面系统安装步骤

  1. 点击下载：Luatools v3 下载调试工具
  2. 通过 LuaTools 工具下载 LuatOS windows桌面系统
  3. LuaTools 工具安装完毕后，点击首页面左上角的--账户--打开资源下载
  4. 选择-公共资源--LuatOS 的 LuatOS windows桌面系统--选择最新版本 LuatOS windows桌面系统--点击开始下载（非刷机）

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

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

2.2.4 使用 LuatOS windows桌面系统 运行 AirUI 演示 demo

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

  1. 创建一个项目并命名

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

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

  1. 如需切换 demo 内的演示内容，可打开下载脚本文件中的 mian.lua 文件，将需要演示 demo 的 require 前面的注释符"--"去掉，将不需要演示 demo 的 require 前面加上注释符“--”。修改后保存代码文件，再点击LuatOS 桌面系统运行，就会出现所 require 的 demo 对应的界面仿真。
  2. 比如：需要演示下拉框组件，将 main.lua 文件中的-- require("airui_dropdown") 改为 require("airui_dropdown") ，并把其他加载的组件改为注释状态。

2.3 组件效果及其 demo

2.3.1 label（标签）

2.3.1.1 演示效果

默认使用12号英文字体
文本内容动态变化
可设置颜色
使用HZfont字库可显示更大字体
黑色
Hello, World!

Hello, World!
Hello, World!

2.3.1.2 演示代码

--[[
@module label_page
@summary 标签组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.label组件的用法，展示文本标签功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建文本标签
    local label1 = airui.label({
        text = "Hello, World!",
        x = 20,
        y = 80,
        w = 100,
        h = 40,
    })

    -- 创建图标标签
    local label2 = airui.label({
        symbol = airui.SYMBOL_SETTINGS,
        x = 120,
        y = 80,
        w = 20,
        h = 20,
        on_click = function(self)
            log.info("label2", "设置图标被点击")
        end
    })

end

sys.taskInit(ui_main)

2.3.1.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_label") --动态更新标签演示

2.3.2 button（按钮）

2.3.2.1 演示效果


默认状态

按下反馈
默认按钮


自定义命名


2.3.2.2 演示代码

--[[
@module button_page
@summary 按钮组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.button组件的用法，展示可点击按钮。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建按钮
    -- 示例1：创建一个基础按钮
    local btn1 = airui.button({ 
        text = "点我", 
        x = 20, 
        y = 80, 
        on_click = function() 
            log.info("btn", "tap") 
        end 
    })

    -- 示例2：创建一个支持切换显示内容的按钮，V1.0.3更新
    local is_play = false
    local btn2 = airui.button({
        text = "播放",
        x = 20,
        y = 180,
        on_click = function(self)
            if is_play then
                self:set_text("播放") 
                is_play = false
            else
                self:set_text("停止") 
                is_play = true
            end
        end
    })

end

sys.taskInit(ui_main)

2.3.2.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_button")  --按钮演示

2.3.3 image（图片）

2.3.3.1 演示效果

不透明

半透明

2.3.3.2 演示代码

--[[
@module image_page
@summary 图片组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.image组件的用法，展示图片显示功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建可点击图片
    local img = airui.image({
        src = "/luadb/dingwei_50x50.png",
        x = 336,
        y = 176,
        w = 128,
        h = 128,
        opacity = 100,
        on_click = function(self)
            log.info("image", "图片被点击了")
        end
    })

    -- 创建半透明图片
    local img1 = airui.image({
        src = "/luadb/logo.jpg",
        x = 20,
        y = 20,
        w = 80,
        h = 80,
    })

end

sys.taskInit(ui_main)

2.3.3.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_image")  --图片显示演示

2.3.4 container（容器）

2.3.4.1 演示效果

默认白色

更改颜色

2.3.4.2 演示代码

--[[
@module container_page
@summary 容器组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.container组件的用法，展示如何创建容器并添加子组件。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建红色容器
    local box = airui.container({
        x = 100,
        y = 100,
        w = 100,
        h = 100,
        color = 0xff0000
    })

    -- 在容器中添加标签
    local label = airui.label({
        parent = box, -- 指定父容器
        text = "容器中的标签",
        x = 10,
        y = 50,
        w = 100,
        h = 100,
    })

end

sys.taskInit(ui_main)

2.3.4.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_container")  --容器演示

2.3.5 bar（进度条）动态方式

2.3.5.1 演示效果

默认

更改值

2.3.5.2 演示代码

--[[
@module bar_page
@summary 进度条组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.bar组件的用法，展示动态变化的进度条。
]]

local direction = 1 -- 变化方向
local current = 0   -- 当前值

local function ui_main()
    -- 初始化硬件

    -- 创建进度条
    local progress = airui.bar({
        x = 100,
        y = 200,
        w = 280,
        value = 30
    })

    -- 主循环
    while true do
        -- 更新进度条值
        current = current + direction
        if current >= 100 then
            direction = -1
        elseif current <= 0 then
            direction = 1
        end

        progress:set_value(current, true)
        sys.wait(50)
    end
end

sys.taskInit(ui_main)

2.3.5.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_bar")  --动态进度条演示

2.3.6 dropdown（下拉框）

2.3.6.1 演示效果

未点击

点击下拉框

2.3.6.2 演示代码

--[[
@module dropdown_page
@summary 下拉框组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.dropdown组件的用法，展示下拉选择功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建标签显示选择结果
    local label = airui.label({
        text = "请选择选项",
        x = 50,
        y = 80,
        w = 200,
        h = 40,
    })

    -- 创建下拉框
    local dd = airui.dropdown({
        x = 50,
        y = 120,
        w = 120,
        h = 40,
        options = { "选项A", "选项B", "选项C" },
        default_index = 1,
        on_change = function(self, index)
            local texts = { "选项A", "选项B", "选项C" }
            label:set_text("选择了: " .. texts[index + 1])
        end
    })

end

sys.taskInit(ui_main)

2.3.6.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_dropdown")  --下拉框演示

2.3.7 switch（开关按钮）

2.3.7.1 演示效果

默认状态

打开状态

2.3.7.2 演示代码

--[[
@module switch_page
@summary 开关组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.switch组件的用法，展示开关切换功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建标签显示状态
    local label = airui.label({
        text = "当前状态: 开",
        x = 20,
        y = 80,
        w = 150,
        h = 40,
    })

    -- 创建开关
    local is_on = true
    local sw = airui.switch({
        x = 20,
        y = 120,
        on_change = function()
            is_on = not is_on
            if is_on then
                label:set_text("当前状态: 开")
            else
                label:set_text("当前状态: 关")
            end
        end
    })

end

sys.taskInit(ui_main)

2.3.7.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_switch")  --开关组件演示

2.3.8 msgbox（消息窗）

2.3.8.1 演示效果


2.3.8.2 演示代码

--[[
@module msgbox_page
@summary 消息框组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.msgbox组件的用法，展示消息提示框功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建消息框
    local box = airui.msgbox({
        title = "通知",
        text = "2026年你会发财！",
        buttons = { "确定" },
        on_action = function(self, label)
            if label == "确定" then
                self:hide()
            end
        end
    })

end

sys.taskInit(ui_main)

2.3.8.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_msgbox")  --消息框组件演示

2.3.9 textarea（输入框）+ keyboard（键盘）

2.3.9.1 演示效果


2.3.9.2 演示代码

--[[
@module input_page
@summary 输入框和键盘演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.textarea和airui.keyboard组件的用法，展示文本输入功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建虚拟键盘
    local keyboard = airui.keyboard({
        x = 0,
        y = -20, -- 底部留20像素边距
        w = 800,
        h = 250,
        mode = "text",
        auto_hide = true,
    })

    -- 创建文本输入框
    local textarea = airui.textarea({
        x = 0,
        y = 0,
        w = 800,
        h = 150,
        max_len = 512,
        text = "在这里输入文字",
        placeholder = "点击输入...",
        keyboard = keyboard
    })

    -- 创建按钮
    local btn = airui.button({
        x = 20,
        y = 180,
        text = "提交",
        on_click = function()
            airui.msgbox({
                title = "提交内容为",
                text = textarea:get_text(),
                buttons = { "确定" },
                on_action = function(self, label)
                    if label == "确定" then
                        self:hide()
                    end
                end
            })
        end
    })

end

sys.taskInit(ui_main)

2.3.9.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_input")  --输入框和键盘演示

2.3.10 tabview（选项卡）

2.3.10.1 演示效果


2.3.10.2 演示代码

--[[
@module tabview_page
@summary 选项卡组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.tabview组件的用法，展示多页面切换功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建选项卡视图
    local tv = airui.tabview({
        x = 0,
        y = 0,
        w = 800,
        h = 480,
        tabs = { "页面A", "页面B", "页面C", "页面D", "页面E" }
    })

    -- 获取各个页面容器
    local page1 = tv:get_content(0)
    local page2 = tv:get_content(1)
    local page3 = tv:get_content(2)
    local page4 = tv:get_content(3)
    local page5 = tv:get_content(4)

    -- 在每个页面中添加标签
    airui.label({ parent = page1, text = "这是页面A", x = 200, y = 80 })
    airui.label({ parent = page2, text = "这是页面B", x = 200, y = 80 })
    airui.label({ parent = page3, text = "这是页面C", x = 200, y = 80 })
    airui.label({ parent = page4, text = "这是页面D", x = 200, y = 80 })
    airui.label({ parent = page5, text = "这是页面E", x = 200, y = 80 })

end

sys.taskInit(ui_main)

2.3.10.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_tabview")  --选项卡演示

2.3.11 table（表格）

2.3.11.1 演示效果


2.3.11.2 演示代码

--[[
@module table_page
@summary 表格组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.table组件的用法，展示表格功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建3行3列的表格
    local tbl = airui.table({ 
        x = 10, 
        y = 10, 
        h = 200,
        w = 410,
        rows = 3, 
        cols = 3
    })

    -- 设置表格标题
    tbl:set_cell_text(0, 0, "姓名")
    tbl:set_cell_text(0, 1, "年龄")
    tbl:set_cell_text(0, 2, "城市")

    -- 设置表格内容
    tbl:set_cell_text(1, 0, "张三")
    tbl:set_cell_text(1, 1, "25")
    tbl:set_cell_text(1, 2, "北京")

    tbl:set_cell_text(2, 0, "李四")
    tbl:set_cell_text(2, 1, "30")
    tbl:set_cell_text(2, 2, "上海")

end

sys.taskInit(ui_main)

2.3.11.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_table") --表格演示

2.3.12 win（窗口容器）

2.3.12.1 演示效果


2.3.12.2 演示代码

--[[
@module win_page
@summary 窗口组件演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示airui.win组件的用法，展示窗口功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建窗口
    local win1 = airui.win({
        title = "示例窗口",
        x = 10,
        y = 10,
        w = 600,
        h = 400,
        close_btn = true,
        auto_center = false,
        style = "radius",
        on_close = function(self)
            log.info("win", "窗口已关闭")
        end
    })

    -- 在窗口中添加标签
    local label1 = airui.label({
        parent = win1,
        text = "窗口中的内容",
        x = 20,
        y = 20,
    })

end

sys.taskInit(ui_main)

2.3.12.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_win")  --标签窗口演示

2.3.13 全部控件

2.3.13.1 演示效果

组件
输入法



2.3.13.2 演示代码

--[[
@module all_component_page
@summary 所有组件综合演示
@version 2.0
@date 2026.03.09
@author 江访
@usage
本文件演示所有AirUI组件的综合用法。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建主容器
    local main_container = airui.container({
        x = 0,
        y = 0,
        w = 800,
        h = 480,
        color = 0xF5F5F5,
    })

    -- 1. 标题区域
    local title_bar = airui.container({
        parent = main_container,
        x = 0,
        y = 0,
        w = 800,
        h = 60,
        color = 0x007AFF,
    })

    local title_label = airui.label({
        parent = title_bar,
        text = "AirUI 全部组件演示",
        x = 20,
        y = 20,
        w = 760,
        h = 30,
    })

    -- 2. 左列组件
    local left_col = airui.container({
        parent = main_container,
        x = 20,
        y = 70,
        w = 380,
        h = 380,
        color = 0xFFFFFF,
        radius = 8,
    })

    -- 2.1 文本输入框组件
    airui.label({
        parent = left_col,
        text = "文本输入",
        x = 20,
        y = 20,
        w = 100,
        h = 25,
    })

    -- 创建虚拟键盘
    local keyboard = airui.keyboard({
        x = 0,
        y = -20,
        w = 800,
        h = 250,
        mode = "text",
        auto_hide = true,
    })

    -- 创建输入框并绑定键盘
    local text_input = airui.textarea({
        parent = left_col,
        x = 20,
        y = 50,
        w = 340,
        h = 60,
        max_len = 50,
        text = "示例文本",
        placeholder = "请输入...",
        keyboard = keyboard,
        on_text_change = function(text)
            log.info("textarea", text)
        end
    })

    -- 2.2 进度条组件
    airui.label({
        parent = left_col,
        text = "进度条",
        x = 20,
        y = 130,
        w = 100,
        h = 25,
    })

    local progress_bar = airui.bar({
        parent = left_col,
        x = 20,
        y = 160,
        w = 340,
        h = 20,
        value = 65,
        bg_color = 0xE0E0E0,
        indicator_color = 0x4CAF50,
        radius = 10,
    })

    -- 2.3 按钮组件
    local test_btn = airui.button({
        parent = left_col,
        x = 20,
        y = 200,
        w = 150,
        h = 40,
        text = "更新进度条",
        on_click = function()
            local current = progress_bar:get_value()
            local new_value = current + 10
            if new_value > 100 then
                new_value = 0
            end
            progress_bar:set_value(new_value, true)
            log.info("progress", "进度更新为: " .. new_value .. "%")
        end
    })

    -- 2.4 消息框按钮
    local msgbox_btn = airui.button({
        parent = left_col,
        x = 200,
        y = 200,
        w = 150,
        h = 40,
        text = "显示消息框",
        on_click = function()
            local msgbox = airui.msgbox({
                title = "提示",
                text = "这是消息框演示\n点击确定关闭",
                buttons = { "确定", "取消" },
                timeout = 2000,
                on_action = function(self, label)
                    log.info("msgbox", "点击了: " .. label)
                    self:hide()
                end
            })
        end
    })

    -- 2.5 下拉框组件
    airui.label({
        parent = left_col,
        text = "下拉选择",
        x = 20,
        y = 250,
        w = 100,
        h = 25,
    })

    local dropdown = airui.dropdown({
        parent = left_col,
        x = 20,
        y = 280,
        w = 200,
        h = 40,
        options = { "选项一", "选项二", "选项三", "选项四" },
        default_index = 0,
        on_change = function(self, index)
            local texts = { "选项一", "选项二", "选项三", "选项四" }
            log.info("dropdown", "选择了: " .. texts[index + 1])
        end
    })

    -- 2.6 开关组件
    airui.label({
        parent = left_col,
        text = "开关",
        x = 240,
        y = 250,
        w = 60,
        h = 30,
    })

    local is_on = true
    local toggle_switch = airui.switch({
        parent = left_col,
        x = 240,
        y = 280,
        checked = true,
        on_change = function(self)
            is_on = not is_on
            if is_on then
                log.info("当前状态: 开")
            else
                log.info("当前状态: 关")
            end
        end
    })

    -- 2.7 在左列底部添加图表组件（折线图）
    airui.label({
        parent = left_col,
        text = "图表（简化）",
        x = 20,
        y = 320,
        w = 100,
        h = 20,
    })

    local chart = airui.chart({
        parent = left_col,
        x = 20,
        y = 340,
        w = 340,
        h = 40,
        type = "line",
        y_min = 0,
        y_max = 100,
        point_count = 30,
        line_color = 0x00b4ff,
        line_width = 1,
        point_radius = 1,
        legend = false,
        x_axis = { enable = false },
        y_axis = { enable = false },
    })
    chart:set_values(1, {30, 45, 60, 55, 70, 65, 80, 75, 90, 85, 95})

    -- 3. 右列组件
    local right_col = airui.container({
        parent = main_container,
        x = 420,
        y = 70,
        w = 360,
        h = 380,
        color = 0xFFFFFF,
        radius = 8,
    })

    -- 右列标题
    airui.label({
        parent = right_col,
        text = "数据表格",
        x = 20,
        y = 20,
        w = 320,
        h = 25,
    })

    -- 3.1 表格组件
    local data_table = airui.table({
        parent = right_col,
        x = 20,
        y = 60,
        w = 320,
        h = 220,
        rows = 3,
        cols = 3,
        col_width = { 100, 100, 100 },
        border_color = 0xCCCCCC
    })

    -- 设置表格内容
    data_table:set_cell_text(0, 0, "姓名")
    data_table:set_cell_text(0, 1, "年龄")
    data_table:set_cell_text(0, 2, "城市")
    data_table:set_cell_text(1, 0, "张三")
    data_table:set_cell_text(1, 1, "25")
    data_table:set_cell_text(1, 2, "北京")
    data_table:set_cell_text(2, 0, "李四")
    data_table:set_cell_text(2, 1, "30")
    data_table:set_cell_text(2, 2, "上海")

    -- 3.2 二维码组件
    airui.label({
        parent = right_col,
        text = "二维码",
        x = 20,
        y = 290,
        w = 100,
        h = 20,
    })

    local qrcode = airui.qrcode({
        parent = right_col,
        x = 125,
        y = 310,
        size = 70,
        data = "https://docs.openluat.com/",
        dark_color = 0x000000,
        light_color = 0xFFFFFF,
        quiet_zone = true
    })

    -- 4. 底部状态栏
    local status_bar = airui.container({
        parent = main_container,
        x = 0,
        y = 460,
        w = 800,
        h = 20,
        color = 0xCFCFCF,
    })

    airui.label({
        parent = status_bar,
        text = "AirUI Demo v1.1",
        x = 20,
        y = 2,
        w = 760,
        h = 16,
    })

end

sys.taskInit(ui_main)

2.3.13.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_all_component") --所有组件综合演示

2.3.14 页面切换

2.3.14.1 演示效果

页面2
页面3



2.3.14.2 演示代码

--[[
@module switch_page_demo
@summary 页面切换功能演示
@version 1.0
@date 2026.01.27
@author 江访
@usage
本文件演示如何使用容器组件实现多页面切换功能。
]]

local current_page = 1
local total_pages = 3
local pages = {}

local function ui_main()
    -- 初始化硬件

    -- 创建主容器
    local main_container = airui.container({
        x = 0,
        y = 0,
        w = 800,
        h = 480,
        color = 0xF8F9FA,
    })

    -- 创建标题栏
    local title_bar = airui.container({
        parent = main_container,
        x = 0,
        y = 0,
        w = 800,
        h = 80,
        color = 0x007AFF,
    })

    local title_label = airui.label({
        parent = title_bar,
        text = "页面切换演示",
        x = 20,
        y = 20,
        w = 760,
        h = 40,
    })

    local page_indicator = airui.label({
        parent = title_bar,
        text = "第1页 / 共3页",
        x = 600,
        y = 20,
        w = 180,
        h = 40,
    })

    -- 创建内容区域
    local content_area = airui.container({
        parent = main_container,
        x = 20,
        y = 100,
        w = 760,
        h = 320,
        color = 0xFFFFFF,
        radius = 10,
    })

    -- 创建三个页面
    for i = 1, total_pages do
        pages[i] = airui.container({
            parent = content_area,
            x = 0,
            y = 0,
            w = 760,
            h = 320,
            color = 0xFFFFFF,
        })

        -- 设置页面初始状态（只显示第一个页面）
        if i ~= 1 then
            pages[i]:set_hidden(true)
        end

        -- 为每个页面添加不同的内容
        if i == 1 then
            -- 第一页：欢迎页面
            local welcome_label = airui.label({
                parent = pages[i],
                text = "欢迎使用页面切换演示",
                x = 0,
                y = 50,
                w = 760,
                h = 50,
            })

            local desc_label = airui.label({
                parent = pages[i],
                text = "这是一个演示多页面切换功能的示例\n使用容器组件实现页面切换\n点击下方按钮切换页面",
                x = 0,
                y = 120,
                w = 760,
                h = 100,
            })

        elseif i == 2 then
            -- 第二页：设置页面
            airui.label({
                parent = pages[i],
                text = "设置页面",
                x = 0,
                y = 30,
                w = 760,
                h = 40,
            })

            -- 设置项目1
            airui.label({
                parent = pages[i],
                text = "开关设置",
                x = 50,
                y = 90,
                w = 200,
                h = 30,
            })

            local switch1 = airui.switch({
                parent = pages[i],
                x = 250,
                y = 95,
                checked = true,
                on_change = function()
                    log.info("page2", "开关1状态改变")
                end
            })

            -- 设置项目2
            airui.label({
                parent = pages[i],
                text = "亮度调节",
                x = 50,
                y = 140,
                w = 200,
                h = 30,
            })

            local brightness_bar = airui.bar({
                parent = pages[i],
                x = 250,
                y = 145,
                w = 200,
                h = 20,
                value = 75,
                indicator_color = 0xFF9800,
            })

            -- 设置项目3
            airui.label({
                parent = pages[i],
                text = "模式选择",
                x = 50,
                y = 190,
                w = 200,
                h = 30,
            })

            local mode_dropdown = airui.dropdown({
                parent = pages[i],
                x = 250,
                y = 190,
                w = 200,
                h = 40,
                options = { "自动模式", "手动模式", "节能模式" },
                default_index = 0,
            })

        elseif i == 3 then
            -- 第三页：数据页面
            airui.label({
                parent = pages[i],
                text = "数据展示",
                x = 0,
                y = 30,
                w = 760,
                h = 40,
            })

            -- 创建数据表格
            local data_table = airui.table({
                parent = pages[i],
                x = 50,
                y = 70,
                w = 660,
                h = 240,
                rows = 5,
                cols = 4,
                col_width = { 200, 150, 150, 150 },
                border_color = 0xCCCCCC
            })

            -- 设置表头
            data_table:set_cell_text(0, 0, "设备名称")
            data_table:set_cell_text(0, 1, "温度")
            data_table:set_cell_text(0, 2, "湿度")
            data_table:set_cell_text(0, 3, "状态")

            -- 设置数据
            data_table:set_cell_text(1, 0, "传感器1")
            data_table:set_cell_text(1, 1, "25°C")
            data_table:set_cell_text(1, 2, "65%")
            data_table:set_cell_text(1, 3, "正常")

            data_table:set_cell_text(2, 0, "传感器2")
            data_table:set_cell_text(2, 1, "28°C")
            data_table:set_cell_text(2, 2, "70%")
            data_table:set_cell_text(2, 3, "正常")

            data_table:set_cell_text(3, 0, "传感器3")
            data_table:set_cell_text(3, 1, "22°C")
            data_table:set_cell_text(3, 2, "60%")
            data_table:set_cell_text(3, 3, "正常")

            data_table:set_cell_text(4, 0, "传感器4")
            data_table:set_cell_text(4, 1, "30°C")
            data_table:set_cell_text(4, 2, "75%")
            data_table:set_cell_text(4, 3, "警告")
        end
    end

    -- 创建底部导航栏
    local nav_bar = airui.container({
        parent = main_container,
        x = 0,
        y = 430,
        w = 800,
        h = 50,
        color = 0xFFFFFF,
    })

    -- 创建导航按钮容器
    local btn_container = airui.container({
        parent = nav_bar,
        x = 100,
        y = 5,
        w = 600,
        h = 40,
        color = 0xFFFFFF,
    })

    -- 创建上一页按钮
    local prev_btn = airui.button({
        parent = btn_container,
        x = 0,
        y = 0,
        w = 120,
        h = 40,
        text = "上一页",
        on_click = function()
            if current_page > 1 then
                -- 隐藏当前页面
                pages[current_page]:set_hidden(true)
                current_page = current_page - 1
                -- 显示新页面
                pages[current_page]:set_hidden(false)
                page_indicator:set_text("第" .. current_page .. "页 / 共3页")
                log.info("page_switch", "切换到第 " .. current_page .. " 页")
            end
        end
    })

    -- 创建页面按钮
    local page_btn_x = 140
    for i = 1, total_pages do
        local btn_text = "第" .. i .. "页"
        local page_btn = airui.button({
            parent = btn_container,
            x = page_btn_x,
            y = 0,
            w = 80,
            h = 40,
            text = btn_text,
            on_click = function()
                -- 隐藏所有页面
                for j = 1, total_pages do
                    pages[j]:set_hidden(true)
                end
                -- 显示选中的页面
                current_page = i
                pages[current_page]:set_hidden(false)
                page_indicator:set_text("第" .. current_page .. "页 / 共3页")
                log.info("page_switch", "跳转到第 " .. current_page .. " 页")
            end
        })
        page_btn_x = page_btn_x + 90
    end

    -- 创建下一页按钮
    local next_btn = airui.button({
        parent = btn_container,
        x = 480,
        y = 0,
        w = 120,
        h = 40,
        text = "下一页",
        on_click = function()
            if current_page < total_pages then
                -- 隐藏当前页面
                pages[current_page]:set_hidden(true)
                current_page = current_page + 1
                -- 显示新页面
                pages[current_page]:set_hidden(false)
                page_indicator:set_text("第" .. current_page .. "页 / 共3页")
                log.info("page_switch", "切换到第 " .. current_page .. " 页")
            end
        end
    })


end

sys.taskInit(ui_main)

2.3.14.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_switch_page")  --页面切换演示

2.3.15 hzfont 矢量字体

2.3.15.1 演示效果


2.3.15.2 演示代码

--[[
@module hzfont_page
@summary HzFont矢量字体演示
@version 1.0.0
@date    2025.11.28
@author  江访
@usage
本文件演示HzFont矢量字体的各项特性，包括全字号无级缩放、抗锯齿优化和字体使用自由。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建主容器（白色背景）
    local main_container = airui.container({
        x = 0,
        y = 0,
        w = 800,
        h = 480,
        color = 0xFFFFFF,
    })

    -- 标题栏（蓝色）
    local title_bar = airui.container({
        parent = main_container,
        x = 0,
        y = 0,
        w = 800,
        h = 80,
        color = 0x2196F3,
    })

    -- 标题：使用大字号 + 白色
    local title_label = airui.label({
        parent = title_bar,
        text = "HzFont 矢量字体演示 (Vector Font Demo)",
        x = 10,
        y = 20,
        w = 780,
        h = 40,
        font_size = 32,
        color = 0xFFFFFF,
        align = airui.TEXT_ALIGN_CENTER
    })

    -- 内容区域（浅灰色圆角背景）
    local content_area = airui.container({
        parent = main_container,
        x = 40,
        y = 100,
        w = 720,
        h = 340,
        color = 0xF8F9FA,
        radius = 8,
    })

    -- 第1行：超大字号演示无级缩放
    local line1_label = airui.label({
        parent = content_area,
        text = "全字号无级缩放：字号 48 (Scale: 48px)",
        x = 20,
        y = 20,
        w = 680,
        h = 120,
        font_size = 48,
        color = 0xE63946,
    })

    -- 第2行：中等字号 + 智能抗锯齿
    local line2_label = airui.label({
        parent = content_area,
        text = "智能抗锯齿优化：字号 28  Anti-aliasing  中文 English",
        x = 20,
        y = 150,
        w = 680,
        h = 70,
        font_size = 28,
        color = 0x2A9D8F,
    })

    -- 第3行：小字号展示多语言和符号
    local line3_label = airui.label({
        parent = content_area,
        text = "字体使用高度自由：内置字库 / 外部.ttf。支持中英符号",
        x = 20,
        y = 240,
        w = 680,
        h = 30,
        font_size = 24,
        color = 0x264653,
    })
end

sys.taskInit(ui_main)

2.3.15.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_hzfont")  --内置软件矢量字体演示

2.3.16 chart（图表/曲线图）

2.3.16.1 演示效果


2.3.16.2 演示代码

--[[
@module chart_page
@summary 图表组件演示 (折线图)
@version 1.0
@date 2026.03.09
@author 江访
@usage
本文件演示airui.chart组件的用法，展示折线图、多系列数据。
]]

local function ui_main()
    -- 初始化硬件

    -- 标题
    airui.label({
        text = "图表组件演示（动态折线图）",
        x = 0, y = 15, w = 800, h = 30,
        font_size = 24,
        color = 0x333333,
        align = airui.TEXT_ALIGN_CENTER,
    })

    -- 创建图表（折线图）
    local chart = airui.chart({
        x = 40,
        y = 60,
        w = 720,
        h = 390,
        type = "line",
        y_min = 0,
        y_max = 100,
        point_count = 120,
        update_mode = "shift",
        line_color = 0x00b4ff,
        line_width = 2,
        point_radius = 2,
        hdiv = 6,
        vdiv = 6,
        legend = true,
        x_axis = { enable = true, min = 0, max = 120, ticks = 6, unit = "s" },
        y_axis = { enable = true, min = 0, max = 100, ticks = 6, unit = "%" }
    })

    -- 添加第二个系列
    local sid2 = chart:add_series({ color = 0xff6b35, name = "avg" })
    -- 添加第三个系列
    local sid3 = chart:add_series({ color = 0x22c55e, name = "diff" })
    -- 设置第一个系列名称
    chart:set_series_name(1, "raw")

    -- 设置初始数据
    chart:set_values(1, {50, 52, 54, 56, 58, 60, 62, 64, 66, 68, 70})
    chart:set_values(sid2, {50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60})
    chart:set_values(sid3, {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10})

    -- 模拟动态推送
    sys.timerLoopStart(function()
        local v1 = 50 + math.random(-20, 20)
        local v2 = 50 + math.random(-15, 15)
        local v3 = v1 - v2
        chart:push(1, v1)
        chart:push(sid2, v2)
        chart:push(sid3, v3)
    end, 1000)
end

sys.taskInit(ui_main)

2.3.16.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_chart")  --图表组件演示

2.3.17 qrcode（二维码）

2.3.17.1 演示效果


2.3.17.2 演示代码

--[[
@module qrcode_page
@summary 二维码组件演示
@version 1.0
@date 2026.03.09
@author 江访
@usage
本文件演示airui.qrcode组件的用法，展示二维码生成。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建二维码
    local qrcode = airui.qrcode({
        x = 40,
        y = 40,
        size = 220,                     -- 正方形尺寸
        data = "https://docs.openluat.com/",    -- 二维码内容
        dark_color = 0x000000,          -- 深色模块颜色
        light_color = 0xFFFFFF,         -- 浅色模块颜色
        quiet_zone = true                -- 四周留白
    })

    if not qrcode then
        log.error("qrcode", "创建二维码失败")
        return
    end

    -- 添加一个标签说明
    airui.label({
        x = 40,
        y = 280,
        w = 720,
        h = 40,
        text = "扫描上方二维码访问 LuatOS 官网",
        font_size = 20,
        color = 0x333333
    })
end

sys.taskInit(ui_main)

2.3.17.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_qrcode")  --二维码组件演示

2.3.18 animimg（动画图像）

2.3.18.1 演示效果


2.3.18.2 演示代码

--[[
@module animimg_page
@summary 动画图像组件演示
@version 1.0
@date 2026.05.12
@author 江访
@usage
本文件演示airui.animimg组件的用法，展示多帧动画图像播放功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建动画帧列表（fly_man_01~08.png, 350x350）
    local frames = {
        "/luadb/fly_man_01.png",
        "/luadb/fly_man_02.png",
        "/luadb/fly_man_03.png",
        "/luadb/fly_man_04.png",
        "/luadb/fly_man_05.png",
        "/luadb/fly_man_06.png",
        "/luadb/fly_man_07.png",
        "/luadb/fly_man_08.png",
    }

    -- 标题
    airui.label({
        text = "动画图像演示",
        x = 0, y = 10, w = 800, h = 30,
        font_size = 24,
        color = 0x333333,
        align = airui.TEXT_ALIGN_CENTER,
    })

    -- 创建动画图像组件（居中显示）
    local anim = airui.animimg({
        x = 225,
        y = 55,
        w = 350,
        h = 350,
        frames = frames,
        duration = 1600,      -- 8帧，每帧约200ms
        loop = true,           -- 循环播放
        auto_play = true,      -- 自动播放
        on_complete = function()
            log.info("animimg", "一轮播放完成")
        end
    })

    -- 播放按钮
    airui.button({
        x = 220, y = 430, w = 100, h = 40,
        text = "播放",
        on_click = function()
            anim:play()
        end
    })

    -- 暂停按钮
    airui.button({
        x = 350, y = 430, w = 100, h = 40,
        text = "暂停",
        on_click = function()
            anim:pause()
        end
    })

    -- 停止按钮
    airui.button({
        x = 480, y = 430, w = 100, h = 40,
        text = "停止",
        on_click = function()
            anim:stop()
        end
    })

end

sys.taskInit(ui_main)

2.3.18.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_animimg")  --动画图像组件演示

2.3.19 shape（形状）

2.3.19.1 演示效果


2.3.19.2 演示代码

--[[
@module shape_page
@summary 形状组件演示
@version 1.0
@date 2026.05.12
@author 江访
@usage
本文件演示airui.shape组件的用法，展示直线、圆形、椭圆、矩形/圆角矩形等多种图元绘制。
]]

local function ui_main()
    -- 初始化硬件

    -- 创建主容器
    local main_container = airui.container({
        x = 0,
        y = 0,
        w = 800,
        h = 480,
        color = 0x1a1a2e,
    })

    -- 标题
    airui.label({
        parent = main_container,
        text = "Shape 形状组件演示",
        x = 0,
        y = 10,
        w = 800,
        h = 30,
        font_size = 24,
        color = 0xffffff,
        align = airui.TEXT_ALIGN_CENTER,
    })

    -- 示例1：直线（含虚线、圆头）
    airui.shape({
        parent = main_container,
        x = 20, y = 50, w = 760, h = 40,
        items = {
            {type = "line", x1 = 40, y1 = 20, x2 = 240, y2 = 20,
             color = 0xff3b30, width = 2},
            {type = "line", x1 = 280, y1 = 20, x2 = 480, y2 = 20,
             color = 0x22c55e, width = 6,
             round_start = true, round_end = true},
            {type = "line", x1 = 520, y1 = 20, x2 = 720, y2 = 20,
             color = 0x38bdf8, width = 2,
             dash_width = 8, dash_gap = 6},
        },
    })

    -- 示例2：圆形（描边/填充）
    airui.shape({
        parent = main_container,
        x = 20, y = 100, w = 760, h = 140,
        items = {
            {type = "circle", cx = 80, cy = 70, r = 60,
             color = 0xff3b30, width = 2},
            {type = "circle", cx = 240, cy = 70, r = 60,
             color = 0x22c55e, width = 2,
             fill = true, fill_color = 0x14532d, fill_opacity = 200},
            {type = "circle", cx = 400, cy = 70, r = 40,
             color = 0xfbbf24, width = 3,
             fill = true, fill_color = 0xfbbf24, fill_opacity = 80},
            {type = "circle", cx = 520, cy = 70, r = 60,
             color = 0x38bdf8, width = 4},
            {type = "circle", cx = 680, cy = 70, r = 50,
             color = 0xa855f7, width = 2,
             fill = true, fill_color = 0x3b0764, fill_opacity = 255},
        },
    })

    -- 示例3：椭圆
    airui.shape({
        parent = main_container,
        x = 20, y = 250, w = 760, h = 80,
        items = {
            {type = "ellipse", cx = 140, cy = 40, rx = 120, ry = 30,
             color = 0xff3b30, width = 2},
            {type = "ellipse", cx = 400, cy = 40, rx = 120, ry = 30,
             color = 0x22c55e, width = 2,
             fill = true, fill_color = 0x14532d, fill_opacity = 200},
            {type = "ellipse", cx = 660, cy = 40, rx = 100, ry = 30,
             color = 0x38bdf8, width = 3,
             fill = true, fill_color = 0x38bdf8, fill_opacity = 80},
        },
    })

    -- 示例4：矩形和圆角矩形
    airui.shape({
        parent = main_container,
        x = 20, y = 340, w = 760, h = 130,
        items = {
            {type = "rect", x = 40, y = 10, w = 140, h = 100,
             color = 0xff3b30, width = 2},
            {type = "rect", x = 220, y = 10, w = 140, h = 100, radius = 20,
             color = 0x22c55e, width = 2,
             fill = true, fill_color = 0x14532d, fill_opacity = 200},
            {type = "rect", x = 400, y = 10, w = 140, h = 100, radius = 50,
             color = 0x38bdf8, width = 4,
             fill = true, fill_color = 0x38bdf8, fill_opacity = 60},
            {type = "rect", x = 580, y = 10, w = 140, h = 100, radius = 10,
             color = 0xfbbf24, width = 3,
             fill = true, fill_color = 0x452c08, fill_opacity = 255},
        },
    })

end

sys.taskInit(ui_main)

2.3.19.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_shape")  --形状组件演示

2.3.20 spinner（加载指示器）

2.3.20.1 演示效果


2.3.20.2 演示代码

--[[
@module spinner_page
@summary 加载指示器组件演示
@version 1.0
@date 2026.05.12
@author 江访
@usage
本文件演示airui.spinner组件的用法，展示旋转加载动画。
]]

local function ui_main()
    -- 初始化硬件

    -- 标题
    airui.label({
        text = "Spinner 加载指示器演示",
        x = 0,
        y = 40,
        w = 800,
        h = 30,
        font_size = 24,
        color = 0x333333,
        align = airui.TEXT_ALIGN_CENTER,
    })

    -- 默认样式加载指示器
    local spinner1 = airui.spinner({
        x = 150,
        y = 120,
        w = 40,
        h = 40,
        duration = 1000,
        arc_angle = 200,
        style = {
            color = 0x00b4ff,
            track_color = 0xd0d0d0,
            line_width = 4,
            opa = 255,
        }
    })

    -- 橙色大号加载指示器
    local spinner2 = airui.spinner({
        x = 270,
        y = 100,
        w = 80,
        h = 80,
        duration = 800,
        arc_angle = 260,
        style = {
            color = 0xff7a00,
            track_color = 0x33261a,
            line_width = 6,
            opa = 255,
        }
    })

    -- 绿色小号加载指示器
    local spinner3 = airui.spinner({
        x = 420,
        y = 120,
        w = 40,
        h = 40,
        duration = 1500,
        arc_angle = 160,
        style = {
            color = 0x22c55e,
            track_color = 0x1a3522,
            line_width = 4,
            opa = 255,
        }
    })

    -- 半透明加载指示器
    local spinner4 = airui.spinner({
        x = 530,
        y = 110,
        w = 60,
        h = 60,
        duration = 1200,
        arc_angle = 220,
        style = {
            color = 0xa855f7,
            track_color = 0x2a1a35,
            line_width = 5,
            opa = 180,
        }
    })

    -- 切换样式按钮
    airui.button({
        x = 300,
        y = 330,
        w = 200,
        h = 40,
        text = "切换配色",
        on_click = function()
            spinner1:set_style({
                color = 0xff3b30,
                track_color = 0x2a1515,
                line_width = 4,
                opa = 255,
            })
            log.info("spinner", "样式已切换")
        end
    })

    -- 加速旋转按钮
    airui.button({
        x = 300,
        y = 390,
        w = 200,
        h = 40,
        text = "加速旋转",
        on_click = function()
            spinner2:set_anim_params(400, 280)
            log.info("spinner", "旋转加速")
        end
    })

end

sys.taskInit(ui_main)

2.3.20.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_spinner")  --加载指示器组件演示

2.3.21 video（视频）

2.3.21.1 演示效果

MJPG 视频播放

2.3.21.2 演示代码

--[[
@module video_page
@summary 视频组件演示
@version 1.0
@date 2026.05.12
@author 江访
@usage
本文件演示airui.video组件的用法，展示MJPG格式视频播放功能。
]]

local function ui_main()
    -- 初始化硬件

    -- 黑色背景容器
    local bg = airui.container({
        x = 0, y = 0, w = 800, h = 480,
        color = 0x000000,
    })

    -- 标题
    airui.label({
        parent = bg,
        text = "Video 视频播放演示",
        x = 0, y = 15, w = 800, h = 30,
        font_size = 24,
        color = 0xcccccc,
        align = airui.TEXT_ALIGN_CENTER,
    })

    -- 创建视频组件
    local video = airui.video({
        parent = bg,
        x = 160, y = 60,
        w = 480, h = 320,
        src = "/luadb/fly_man.mjpg",
        format = "auto",
        backend = "auto",
        decode_mode = "hw",
        interval = 33,
        loop = true,
        auto_play = false,
    })

    if not video then
        log.error("video", "创建视频组件失败")
        return
    end

    -- 播放按钮
    airui.button({
        parent = bg,
        x = 200, y = 410, w = 100, h = 40,
        text = "播放",
        on_click = function()
            video:play()
        end
    })

    -- 暂停按钮
    airui.button({
        parent = bg,
        x = 350, y = 410, w = 100, h = 40,
        text = "暂停",
        on_click = function()
            video:pause()
        end
    })

    -- 停止按钮
    airui.button({
        parent = bg,
        x = 500, y = 410, w = 100, h = 40,
        text = "停止",
        on_click = function()
            video:stop()
        end
    })

end

sys.taskInit(ui_main)

2.3.21.3 加载方式

-- 加载显示驱动脚本文件
lcd_drv = require("lcd_drv")
-- 加载触摸驱动脚本文件
tp_drv = require("tp_drv")

-- 引入演示模块（每次只选择一个运行）
require("airui_video")  --视频组件演示

三、常量详解

扩展库常量，顾名思义是由扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中直接调用；

AirUI 库定义了以下常量：

3.1 颜色格式常量

3.1.1 airui.COLOR_FORMAT_RGB565

参数含义：RGB565 颜色格式（嵌入式友好，节省显存）
数据类型：number
示例代码：
        local ok = airui.init(480, 320, airui.COLOR_FORMAT_RGB565)
        if not ok then
            log.error("airui", "初始化失败")
        end

3.1.2 airui.COLOR_FORMAT_ARGB8888

参数含义：ARGB8888 颜色格式（PC端使用，高质量，使用内存更多）
数据类型：number
示例代码：
        local ok = airui.init(800, 600, airui.COLOR_FORMAT_ARGB8888)
        if not ok then
            log.error("airui", "初始化失败")
        end

3.2 文本对齐常量

3.2.1 airui.TEXT_ALIGN_LEFT

参数含义：文本左对齐
数据类型：number
示例代码：
        -- 注：部分组件可能直接支持 align 参数
        local label = airui.label({
            text = "左对齐文本",
            x = 20, y = 80,
            align = airui.TEXT_ALIGN_LEFT
        })

3.2.2 airui.TEXT_ALIGN_CENTER

参数含义：文本水平居中
数据类型：number
示例代码：
        local label = airui.label({
            text = "居中文本",
            x = 20, y = 80,
            align = airui.TEXT_ALIGN_CENTER
        })

3.2.3 airui.TEXT_ALIGN_RIGHT

参数含义：文本右对齐
数据类型：number
示例代码：
        local label = airui.label({
            text = "右对齐文本",
            x = 20, y = 80,
            align = airui.TEXT_ALIGN_RIGHT
        })

3.3 触摸事件码常量

3.3.1 airui.TP_DOWN

参数含义：触摸按下事件
数据类型：number
示例代码：
        airui.touch_subscribe(function(state, x, y, track_id, timestamp)
            if state == airui.TP_DOWN then
                log.info("airui", "touch down at", x, y)
            end
        end)

3.3.2 airui.TP_HOLD

参数含义：触摸按住事件（触摸点保持按下状态）
数据类型：number

3.3.3 airui.TP_UP

参数含义：触摸松开事件
数据类型：number

3.4 图标符号常量

3.4.1 airui.SYMBOL_SETTINGS

参数含义：设置图标
数据类型：string
示例代码：
        local label = airui.label({
            symbol = airui.SYMBOL_SETTINGS,
            x = 200, y = 240, w = 30, h = 30,
            font_size = 20,  -- 图标尺寸不会超过20，设置大小避免被hzfont默认大小改变
            on_click = function(self)
                log.info("label3", "设置图标被点击")
            end
        })

3.4.2 airui.SYMBOL_HOME

参数含义：主页图标
数据类型：string
示例代码：
        local home_label = airui.label({
            symbol = airui.SYMBOL_HOME,
            font_size = 20,  -- 图标尺寸不会超过20，设置大小避免被hzfont默认大小改变
            x = 240, y = 240, w = 30, h = 30
        })

3.4.3 airui.SYMBOL_PLAY

参数含义：播放图标
数据类型：string
示例代码：
        local play_label = airui.label({
            symbol = airui.SYMBOL_PLAY,
            font_size = 20,  -- 图标尺寸不会超过20，设置大小避免被hzfont默认大小改变
            x = 280, y = 240, w = 30, h = 30
        })

3.4.4 airui.SYMBOL_PAUSE

参数含义：暂停图标
数据类型：string
示例代码：
        local pause_label = airui.label({
            symbol = airui.SYMBOL_PAUSE,
            font_size = 20,  -- 图标尺寸不会超过20，设置大小避免被hzfont默认大小改变
            x = 320, y = 240, w = 30, h = 30
        })

3.4.5 其他图标符号常量类似，包括

序号
图标
说明
1
SYMBOL_AUDIO
音频图标，通常表示音频相关功能，如音乐播放、声音设置等。
2
SYMBOL_VIDEO
视频图标，表示视频相关功能，如视频播放、录制等。
3
SYMBOL_LIST
列表图标，表示列表视图或菜单。
4
SYMBOL_OK
确认图标，表示确认、完成、成功等。
5
SYMBOL_CLOSE
关闭图标，表示关闭、退出、取消等。
6
SYMBOL_POWER
电源图标，表示电源开关、关机、重启等。
7
SYMBOL_DOWNLOAD
下载图标，表示下载、云端向下箭头。
8
SYMBOL_REFRESH
刷新图标，表示刷新、重新加载、同步等。
9
SYMBOL_MUTE
静音图标，表示声音被关闭。
10
SYMBOL_VOLUME_MID
中等音量图标，表示中等音量水平。
11
SYMBOL_VOLUME_MAX
最大音量图标，表示最大音量水平。
12
SYMBOL_image
图片图标，表示图像、图片相关。
13
SYMBOL_EDIT
编辑图标，表示编辑、修改。
14
SYMBOL_PREV
上一首/上一个图标，表示媒体播放中的上一首或向前翻页。
15
SYMBOL_STOP
停止图标，表示停止播放或停止某个操作。
16
SYMBOL_NEXT
下一首/下一个图标，表示媒体播放中的下一首或向后翻页。
17
SYMBOL_EJECT
弹出图标，表示弹出设备，如光盘、USB等。
18
SYMBOL_LEFT
左箭头图标，表示向左移动、返回等。
19
SYMBOL_RIGHT
右箭头图标，表示向右移动、前进等。
20
SYMBOL_PLUS
加号图标，表示增加、添加、放大等。
21
SYMBOL_MINUS
减号图标，表示减少、删除、缩小等。
22
SYMBOL_EYE_OPEN
睁眼图标，表示显示、可见（如密码可见）。
23
SYMBOL_EYE_CLOSE
闭眼图标，表示隐藏、不可见（如密码隐藏）。
24
SYMBOL_WARNING
警告图标，表示警告、注意、错误等。
25
SYMBOL_SHUFFLE
随机播放图标，表示随机播放模式。
26
SYMBOL_UP
上箭头图标，表示向上移动、增加等。
27
SYMBOL_DOWN
下箭头图标，表示向下移动、减少等。
28
SYMBOL_LOOP
循环图标，表示循环播放模式。
29
SYMBOL_DIRECTORY
目录图标，表示文件夹、目录。
30
SYMBOL_UPLOAD
上传图标，表示上传、云端向上箭头。
31
SYMBOL_CALL
电话图标，表示电话、呼叫。
32
SYMBOL_CUT
剪切图标，表示剪切操作。
33
SYMBOL_COPY
复制图标，表示复制操作。
34
SYMBOL_SAVE
保存图标，表示保存文件或设置。
35
SYMBOL_CHARGE
充电图标，表示充电状态。
36
SYMBOL_PASTE
粘贴图标，表示粘贴操作。
37
SYMBOL_BELL
铃铛图标，表示通知、提醒。
38
SYMBOL_keyboard
键盘图标，表示键盘输入。
39
SYMBOL_GPS
GPS图标，表示定位、导航。
40
SYMBOL_FILE
文件图标，表示文件。
41
SYMBOL_WIFI
WiFi图标，表示无线网络。
42
SYMBOL_BATTERY_FULL
电池满电图标，表示电池电量满。
43
SYMBOL_BATTERY_3
电池3格电图标，表示电池电量中等偏上。
44
SYMBOL_BATTERY_2
电池2格电图标，表示电池电量中等偏下。
45
SYMBOL_BATTERY_1
电池1格电图标，表示电池电量低。
46
SYMBOL_BATTERY_EMPTY
电池空电图标，表示电池电量极低或为空。
47
SYMBOL_USB
USB图标，表示USB连接或设备。
48
SYMBOL_BLUETOOTH
蓝牙图标，表示蓝牙连接。
49
SYMBOL_TRASH
垃圾桶图标，表示删除、垃圾箱。
50
SYMBOL_BACKSPACE
退格图标，表示退格、删除字符。
51
SYMBOL_SD_CARD
SD卡图标，表示存储卡。
52
SYMBOL_NEW_LINE
换行图标，表示换行（在文本编辑中）。
53
SYMBOL_DUMMY
虚拟图标，占位符，可能是一个空白或测试用图标。
54
SYMBOL_BULLET
项目符号图标，表示列表中的圆点符号。

3.5 tabview 内边距常量

3.5.1 airui.TABVIEW_PAD_ALL

参数含义：对页面应用四边 padding
数据类型：number
示例代码：
    -- 用于 tabview 样式配置
    local tv = airui.tabview({
        tabs = {"页面1", "页面2"},
        page_style = {
            pad = { method = airui.TABVIEW_PAD_ALL, value = 10 }
        }
    })

3.5.2 airui.TABVIEW_PAD_HOR

参数含义：设置左右 padding
数据类型：number
示例代码：
    local tv = airui.tabview({
        tabs = {"页面1", "页面2"},
        page_style = {
            pad = { method = airui.TABVIEW_PAD_HOR, value = 10 }
        }
    })

3.5.3 airui.TABVIEW_PAD_VER

参数含义：设置上下 padding
数据类型：number
示例代码：
    local tv = airui.tabview({
        tabs = {"页面1", "页面2"},
        page_style = {
            pad = { method = airui.TABVIEW_PAD_VER, value = 10 }
        }
    })

3.5.4 airui.TABVIEW_PAD_TOP

参数含义：只设置上 padding
数据类型：number
示例代码：
    local tv = airui.tabview({
        tabs = {"页面1", "页面2"},
        page_style = {
            pad = { method = airui.TABVIEW_PAD_TOP, value = 10 }
        }
    })

3.5.5 airui.TABVIEW_PAD_BOTTOM

参数含义：只设置下 padding
数据类型：number
示例代码：
    local tv = airui.tabview({
        tabs = {"页面1", "页面2"},
        page_style = {
            pad = { method = airui.TABVIEW_PAD_BOTTOM, value = 10 }
        }
    })

3.5.6 airui.TABVIEW_PAD_LEFT

参数含义：只设置左 padding
数据类型：number
示例代码：
    local tv = airui.tabview({
        tabs = {"页面1", "页面2"},
        page_style = {
            pad = { method = airui.TABVIEW_PAD_LEFT, value = 10 }
        }
    })

3.5.7 airui.TABVIEW_PAD_RIGHT

参数含义：只设置右 padding
数据类型：number
示例代码：
    local tv = airui.tabview({
        tabs = {"页面1", "页面2"},
        page_style = {
            pad = { method = airui.TABVIEW_PAD_RIGHT, value = 10 }
        }
    })

3.6 键盘按键常量

3.6.1 airui.KEY_0 / KEY_1 / ... / KEY_9

参数含义：数字按键 0-9
数据类型：number
示例代码：
        if key == airui.KEY_0 then
            log.info("keypad", "NUM 0")
        end

3.6.2 airui.KEY_UP

参数含义：上键，对应键盘上箭头或 W 键
数据类型：number
示例代码：
        if key == airui.KEY_UP then
            log.info("keypad", "UP")
        end

3.6.3 airui.KEY_DOWN

参数含义：下键，对应键盘下箭头或 S 键
数据类型：number
示例代码：
        if key == airui.KEY_DOWN then
            log.info("keypad", "DOWN")
        end

3.6.4 airui.KEY_LEFT

参数含义：左键，对应键盘左箭头或 A 键
数据类型：number
示例代码：
        if key == airui.KEY_LEFT then
            log.info("keypad", "LEFT")
        end

3.6.5 airui.KEY_RIGHT

参数含义：右键，对应键盘右箭头或 D 键
数据类型：number
示例代码：
        if key == airui.KEY_RIGHT then
            log.info("keypad", "RIGHT")
        end

3.6.6 airui.KEY_OK

参数含义：确认键，对应键盘回车键
数据类型：number
示例代码：
        if key == airui.KEY_OK then
            log.info("keypad", "OK")
        end

3.6.7 airui.KEY_BACK

参数含义：返回键，对应键盘 ESC 键
数据类型：number
示例代码：
        if key == airui.KEY_BACK then
            log.info("keypad", "BACK")
        end

四、函数详解

4.1 核心接口

4.1.1 airui.init(width, height, color_format)

功能

初始化 AirUI 渲染上下文，包括屏幕分辨率、颜色格式、上下文创建与绑定，使后续组件创建可用。

参数

width

参数含义：屏幕宽度
数据类型：number
取值范围：大于0的整数
是否必选：可选
注意事项：默认 480
参数示例：800
示例代码：width = 800

height

参数含义：屏幕高度
数据类型：number
取值范围：大于0的整数
是否必选：可选
注意事项：默认 320
参数示例：600
示例代码：height = 600

color_format

参数含义：颜色格式
数据类型：number
取值范围：airui.COLOR_FORMAT_RGB565（嵌入式、节省内存）或 COLOR_FORMAT_ARGB8888（PC 高质量）
是否必选：可选
注意事项：默认 RGB565
参数示例：airui.COLOR_FORMAT_ARGB8888
示例代码：color_format = airui.COLOR_FORMAT_ARGB8888

返回值

local init_result = airui.init(width, height, color_format)

init_result

含义说明：初始化操作结果
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：若重复初始化或参数非法返回 false
返回示例：true

示例

-- 初始化 AirUI，设置分辨率为 800x600，颜色格式为 ARGB8888
local ok = airui.init(800, 600, airui.COLOR_FORMAT_ARGB8888)
if not ok then
    log.error("airui", "init failed")
    return
end

4.1.2 airui.deinit()

功能

释放画布与上下文资源，清理注册表中的 airui_ctx，通常在退出或重新初始化前调用。

参数

无

返回值

无

示例

-- 退出应用时释放 AirUI 资源
airui.deinit()

4.1.3 airui.device_bind_touch(tp_cfg) --V1.0.1 前为 airui.indev_bind_touch(tp_cfg)

功能

将触摸初始化后的事件和数据与 AirUI 绑定

参数

tp_cfg

参数含义：触摸屏配置
数据类型：lightuserdata
取值范围：LuatOS tp触摸核心库初始化tp.init()返回值
是否必选：是
注意事项：包含驱动、采样方式等信息
参数示例：tp_object
示例代码：tp_cfg = tp_config

返回值

local bind_result = airui.device_bind_touch(tp_cfg)

bind_result

含义说明：绑定操作结果
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：若平台不支持或参数为空返回 false
返回示例：true

示例

-- 初始化I2C 0，设置为低速模式
i2c.setup(0, i2c.SLOW)

-- 初始化触摸芯片（GT911）
local tp_device = tp.init("gt911", {
    port = 0,         -- I2C端口号
    pin_rst = 0xff,   -- 复位引脚(有的厂家屏幕和触摸复位在一起，屏幕复位了触摸就不需要再复位，该参数可以不填或者填0xff)
    pin_int = 23      -- 中断引脚
})

-- 初始化触摸绑定到 AirUI
local ok = airui.device_bind_touch(tp_device )
if not ok then
    log.error("airui", "init failed")
    return
end

4.1.4 airui.font_load(config)

功能

加载文本渲染所需字体，目前用于支持内置矢量字库（hzfont），此接口返回字体指针将绑定到所有 airui 字符中，缺失字符则将使用 airui 默认 14 号字体，如果 airui 默认字符也没有，则会出现字符空缺。

参数

config

参数含义：字体配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：

{
    参数含义：字体类型
    数据类型：string
    取值范围："hzfont" 或 "bin"
    是否必选：是
    注意事项：无
    参数示例：type = "hzfont"
    type = ,

    参数含义：字体路径
    数据类型：string
    取值范围：有效的字体文件路径
    是否必选：可选
    注意事项：对于 "hzfont"，传 nil 则使用内置字库
    参数示例：path = nil
    path = ,

    参数含义：字体大小
    数据类型：number
    取值范围：含14-255的正整数
    是否必选：可选
    注意事项：默认 14
    参数示例：size = 16
    size = ,

    参数含义：缓存字数大小
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认 256
    参数示例：cache_size = 256
    cache_size = ,

    参数含义：抗锯齿等级 V1.1.1更新
    数据类型：number
    取值范围：整数，通常 1-3
    是否必选：可选
    注意事项：默认 -1 ，自动抗锯齿
    参数示例：antialias = 1
    antialias = ,

    参数含义：是否将字库整包拷贝到PSRAM -- V1.0.1更新
    数据类型：boolean
    取值范围：true或false；
    是否必选：可选
    注意事项：1.将字库整包拷贝至PSRAM，每个字占用内存最大空间为100b,PSRAM空间不够会初始化失败；
             2.使用rtos.meminfo("psram")接口可查询内存使用情况，
               系统运行后可以根据剩余内存空间大小选择是否加载；
             3.字库整包拷贝至PSRAM，每个字显示至屏幕所需时间约为1ms；
             4.缺省.ttf字库文件不加载到psram，显示时先从文字缓存空间搜索，
               搜索不到则从.ttf文件中搜索；     
    参数示例：load_to_psram= true
    load_to_psram = , 

    参数含义：是否全局使用此字体  -- V1.1.0 更新
    数据类型：boolean
    取值范围：true（全局默认字体）, false（仅返回字体句柄，需手动设置到组件）
    是否必选：可选
    注意事项：默认 true。若设为 false，则初始化hzfont所加载的字体不会自动应用于所有组件，
             显示文字的组件可以通过设置 font 参数指定使用hzfont字体，目前label、button组件可以设置
    参数示例：global = false
    global = false,
}

返回值

local font_object = airui.font_load(config)

font_object

含义说明：字体句柄对象
数据类型：userdata
取值范围：有效的字体指针
注意事项：返回值在lua脚本中无实际用途
返回示例：font_handle = airui.font_load(config)

示例

Air8000/780EXX 使用内置ttf字体文件的14/114号固件按示例使用

Air8000/780EXX 使用未内置ttf字体文件的15/115、16/116号固件请看

Air8101 使用未内置ttf字体文件的104号固件请看

-- 加载hzfont字库，从而支持中文显示
airui.font_load({
    type = "hzfont",       -- 字体类型，可选 "hzfont" 或 "bin"
    path = nil,            -- 字体路径，对于 "hzfont"，传 nil 则使用内置字库
    size = 16,             -- 默认显示字体大小，14号
    cache_size = 2048,     -- 缓存字数大小，默认 256
    antialias = 1,         -- 抗锯齿等级1-3，默认自动抗锯齿
})

-- 创建标签并使用加载的字体
local label = airui.label({
    text = "中文显示测试",
    x = 20, y = 80, w = 500, h = 500,
    font_size = 20
})

4.1.5 airui.version() -- V1.0.3 更新

功能

查询当前固件内 AirUI 核心库版本。

参数

无

返回值

local version_result = airui.version()

version_result

-- 查询当前固件内AirUI核心库版本
local version_result = airui.version()

-- 打印查询结果
log.info("airui", "version -> " .. version_result)

4.1.6 airui.device_bind_keypad(config) -- V1.1.0 更新

功能

将物理按键输入与 AirUI 焦点导航系统绑定，支持上下左右、确认、返回等按键，实现键盘/遥控器操作。 在 PC 模拟器上可不传参调用（airui.device_bind_keypad()），启用默认键盘映射（方向键导航，0-9/Enter/Esc 订阅）。

参数

config

参数含义：按键配置参数表
数据类型：table
是否必选：否（PC 模拟器可不传参，使用默认映射）
取值范围：包含以下子参数：
{
    参数含义：上键对应的 GPIO 引脚号
    数据类型：number
    是否必选：是
    注意事项：根据硬件实际连接定义
    参数示例：21
    up = 21,

    参数含义：下键对应的 GPIO 引脚号
    数据类型：number
    是否必选：是
    注意事项：无
    参数示例：20
    down = 20,

    参数含义：确认键对应的 GPIO 引脚号
    数据类型：number
    是否必选：是
    注意事项：无
    参数示例：gpio.PWR_KEY or 7
    ok = 7,

    参数含义：返回键对应的 GPIO 引脚号
    数据类型：number
    是否必选：是
    注意事项：无
    参数示例：gpio.USIM_DET or 79
    back = 79,

    参数含义：按键有效电平
    数据类型：boolean
    是否必选：可选
    取值范围：true（低电平有效）, false（高电平有效）
    注意事项：默认 true
    参数示例：true
    active_low = true,

    参数含义：内部上拉/下拉配置
    数据类型：string
    取值范围："pullup"（上拉）, "pulldown"（下拉）, "none"（无）
    是否必选：可选
    注意事项：默认 "pullup"
    参数示例："pullup"
    pull = "pullup",
}

返回值

local bind_ok = airui.device_bind_keypad(config)

bind_ok

含义说明：绑定操作结果
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：若引脚无效或重复绑定可能失败
返回示例：true

示例

-- 示例1：真机硬件按键绑定
local key_pins = {
    up = 21,
    down = 20,
    ok = gpio.PWR_KEY or 7,
    back = gpio.USIM_DET or 79,
}

local bind_ok = airui.device_bind_keypad({
    up = key_pins.up,
    down = key_pins.down,
    ok = key_pins.ok,
    back = key_pins.back,
    active_low = true,
    pull = "pullup",
})
log.info("keypad", "device_bind_keypad", bind_ok and "ok" or "fail")

-- 示例2：PC 模拟器使用默认键盘映射（方向键导航 + 0-9/Enter/Esc 订阅）
airui.device_bind_keypad()

4.1.7 airui.sleep(config) -- V1.1.3 更新

功能

让 AirUI 进入休眠状态，停止渲染更新，降低刷新频率，节省电量。

参数

config 

参数含义：休眠配置参数表
数据类型：table
是否必选：可选
取值范围：包含以下子参数：
{
    参数含义：是否关闭LCD电源
    数据类型：boolean
    取值范围：true（关闭）, false（不关闭）
    是否必选：可选
    注意事项：默认 false
    参数示例：true
    power_down_lcd = true,
}

返回值

无

示例

-- AirUI 进入休眠，不关闭LCD电源
airui.sleep()

-- 休眠时关闭LCD电源
airui.sleep({power_down_lcd = true})

4.1.8 airui.wakeup(config) -- V1.1.3 更新

功能

从休眠状态唤醒 AirUI，恢复正常渲染更新。

参数

config 

参数含义：唤醒配置参数表
数据类型：table
是否必选：可选
取值范围：包含以下子参数：
{
    参数含义：唤醒后是否自动刷新一次屏幕
    数据类型：boolean
    取值范围：true（自动刷新）, false（不刷新）
    是否必选：可选
    注意事项：默认 true
    参数示例：false
    auto_refresh = false,
}

返回值

无

示例

-- 唤醒 AirUI，并自动刷新屏幕
airui.wakeup()

-- 唤醒时，不自动刷新屏幕
airui.wakeup({auto_refresh = false})

4.1.9 airui.full_refresh() -- V1.1.2 更新

功能

强制执行一次全屏刷新，确保整个屏幕内容更新完整。

参数

无

返回值

无

示例

-- 强制全屏刷新
airui.full_refresh()

4.1.10 airui.set_rotation(rotation) -- V1.1.4 新增

功能

设置 AirUI 显示顺时针旋转角度，与lcd.init中的direction参数无关。

参数

rotation

参数含义：旋转角度
数据类型：number
取值范围：0（0度）、90（90度）、180（180度）、270（270度）
是否必选：是
注意事项：仅支持 0/90/180/270 度旋转
参数示例：90
示例代码：airui.set_rotation(90)

返回值

local result = airui.set_rotation(rotation)

result

含义说明：设置操作结果
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：若参数非法返回 false
返回示例：true

示例

-- 设置屏幕旋转90度
local ok = airui.set_rotation(90)
if not ok then
    log.error("airui", "set_rotation failed")
end

4.1.11 airui.get_rotation() -- V1.1.4 新增

功能

获取 AirUI 当前显示旋转角度。

参数

无

返回值

local rotation = airui.get_rotation()

rotation

含义说明：当前旋转角度
数据类型：number
取值范围：0（0度）、90（90度）、180（180度）、270（270度）
注意事项：无
返回示例：90

示例

-- 获取当前旋转角度
local rotation = airui.get_rotation()
log.info("airui", "current rotation: " .. rotation)

4.1.12 airui.touch_subscribe(callback) -- V1.1.2 更新

功能

订阅全局触摸事件，可以捕获所有触摸操作，用于自定义触摸监听。

参数

callback

参数含义：触摸事件回调函数
数据类型：function
是否必选：是
取值范围：function(state, x, y, track_id, timestamp)
说明：
  - state: 触摸状态，airui.TP_DOWN / airui.TP_HOLD / airui.TP_UP
  - x: 触摸点X坐标
  - y: 触摸点Y坐标
  - track_id: 触摸点ID（多点触摸时区分不同触点
  - timestamp: 时间戳（毫秒）
注意事项：无
参数示例：function(state, x, y, id, ts)
    log.info("airui", "touch", state, x, y)
end

返回值

无

示例

airui.touch_subscribe(function(state, x, y, track_id, timestamp)
    if state == airui.TP_DOWN then
        log.info("airui", "down", x, y)
    elseif state == airui.TP_UP then
        log.info("airui", "up", x, y)
    end
end)

4.1.13 airui.keypad_subscribe(callback) -- V1.2.1 新增

功能

订阅全局 PC 键盘按键事件，可以捕获所有键盘按键操作，用于自定义键盘监听。

参数

callback

参数含义：键盘事件回调函数
数据类型：function
是否必选：是
取值范围：function(key, pressed, timestamp)
说明：
  - key: 按键编码，airui.KEY_UP / KEY_DOWN / KEY_LEFT / KEY_RIGHT / KEY_OK / KEY_BACK / KEY_0 ~ KEY_9
  - pressed: 按键状态，true（按下）、false（释放）
  - timestamp: 时间戳（毫秒）
注意事项：仅在 PC 模拟器上有效
参数示例：function(key, pressed, ts)
    if pressed then
        log.info("airui", "key", key, ts)
    end
end

返回值

无

示例

airui.keypad_subscribe(function(key, pressed, ts)
    if not pressed then
        return
    end

    if key == airui.KEY_UP then
        log.info("keypad", "UP", ts)
    elseif key == airui.KEY_DOWN then
        log.info("keypad", "DOWN", ts)
    elseif key == airui.KEY_OK then
        log.info("keypad", "OK", ts)
    end
end)

4.1.14 airui.status() -- V1.1.6 新增

功能

获取当前屏幕的自适应分辨率信息，包括屏幕旋转方向和当前显示方向下的宽高。

参数

无

返回值

local size = airui.status()

size

含义说明：屏幕状态信息
数据类型：table
取值范围：包含以下字段：
{
    参数含义：屏幕旋转方向
    数据类型：number
    取值范围：0（0度）、90（90度）、180（180度）、270（270度）
    参数示例：90
    rotation = 90,

    参数含义：屏幕当前宽度，与当前显示方向一致
    数据类型：number
    取值范围：大于0的整数
    参数示例：480
    w = 480,

    参数含义：屏幕当前高度，与当前显示方向一致
    数据类型：number
    取值范围：大于0的整数
    参数示例：320
    h = 320,
}
注意事项：返回值随屏幕旋转方向变化而变化
返回示例：{rotation = 90, w = 320, h = 480}

示例

-- 获取屏幕自适应分辨率信息
local size = airui.status()
log.info("airui", "rotation:", size.rotation, "w:", size.w, "h:", size.h)

4.2 组件接口

4.2.1 标签（airui.label）

4.2.1.1 airui.label(config)

功能

用于静态文本和内置图标显示，可设置点击回调，支持 set_text/set_symbol。

参数

config

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

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

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

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

    参数含义：显示文本
    数据类型：string
    取值范围：任意字符串
    是否必选：可选（与symbol二选一）
    注意事项：默认空字符串
    参数示例：text = "Hello, World!"
    text = ,

    参数含义：图标常量
    数据类型：string
    取值范围：airui.SYMBOL_* 常量
    是否必选：可选（与text二选一）
    注意事项：用于显示内置图标
    参数示例：symbol = airui.SYMBOL_SETTINGS
    symbol = ,

    参数含义：字体大小 -- V1.0.1更新
    数据类型：number
    取值范围：含12-255的正整数
    是否必选：可选
    注意事项：默认 16
    参数示例：font_size = 16
    font_size = ,

    参数含义：字体颜色 -- V1.0.1更新
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x000000
    参数示例：color = 0xff0000
    color = ,

    参数含义：字体句柄或名称 -- V1.1.0 更新
    数据类型：string
    取值范围："hzfont"
    是否必选：可选
    注意事项：若未指定，则使用全局默认字体,若airui.font_load(config)中参数global = false时需要进行指定
    参数示例：font = "hzfont"
    font = ,

    参数含义：文本对齐方式 -- V1.1.0 更新
    数据类型：number
    取值范围：airui.TEXT_ALIGN_LEFT(左对齐), airui.TEXT_ALIGN_CENTER(居中), airui.TEXT_ALIGN_RIGHT(右对齐)
    是否必选：可选
    注意事项：默认 airui.TEXT_ALIGN_LEFT，参数应用是在label的宽度w内进行对齐并按非屏幕对齐
    参数示例：align = airui.TEXT_ALIGN_CENTER
    align = ,

    参数含义：点击回调函数，V1.0.3支持使用self的方式
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：点击标签时触发
    参数示例：on_click = function(self) log.info("label3", "on_click") end
    on_click = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：parent = airui.screen
    parent = ,
}

返回值

local label_object = airui.label(config)

label_object

含义说明：标签组件对象
数据类型：userdata
取值范围：包含 set_text、set_symbol、get_text、set_font、set_align、set_color、set_font_size、set_on_click、move、get_pos、set_pos、is_destroyed、destroy 等方法的标签对象
注意事项：需要添加到界面中才能显示
返回示例：label_object

示例

Air8000/780EXX 使用内置ttf字体文件的14/114号固件按示例使用

Air8000/780EXX 使用未内置ttf字体文件的15/115、16/116号固件请看

Air8101 使用未内置ttf字体文件的104号固件请看

-- 示例1：创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})

-- 示例2：创建图标标签
local label1 = airui.label({
    symbol = airui.SYMBOL_SETTINGS,
    x = 200, y = 240, w = 30, h = 30,
    on_click = function(self)
        log.info("label3", "on_click")
    end
})

-- 示例3：创建文本标签，并设置居中对齐
local label = airui.label({
    text = "居中文本",
    x = 20, y = 80, w = 500, h = 500,
    align = airui.TEXT_ALIGN_CENTER,
})

-- 示例4：若固件仅内置了16号中文字体，在需要显示更大字号且固定内容的位置，可以选择使用外置字体
airui.font_load({
    type = "hzfont",             -- 字体类型，可选 "hzfont" 或 "bin"
    path = "/MiSans_gb2312.ttf", -- 字体路径，对于 "hzfont"，传 nil 则使用内置字库
    size = 20,                   -- 默认显示字体大小，14号
    cache_size = 1048,           -- 缓存字数大小，默认 256
    antialias = 1,               -- 抗锯齿等级1-3，默认自动抗锯齿
    to_psram = true              -- 将.ttf文件加载到PSRAM中，默认不加载
})

local label = airui.label({
    text = "你好,世界!",
    x = 20, y = 80, w = 800, h = 500,
    font = "hzfont",
    font_size = 36,
})
4.2.1.2 label:set_text(text)

功能

设置标签文本。

参数

text

参数含义：新内容
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：无
参数示例："更新标题"
示例代码：text = "更新标题"

返回值

无

示例

-- 创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})

-- 更新内容
label:set_text("更新标题")
4.2.1.3 label:set_color(color) -- V1.0.1 更新

功能

设置标签颜色。

参数

color

参数含义：字体颜色
数据类型：number
取值范围：十六进制颜色值
是否必选：可选
注意事项：无
参数示例：0xff0000

返回值

无

示例

-- 创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})

-- 更新label颜色，V1.0.1更新 
label:set_color(0xff0000)
4.2.1.4 label:set_font_size(size) -- V1.0.1 更新

功能

设置标签大小。

参数

size

参数含义：字体大小
数据类型：number
取值范围：含12-255的正整数
是否必选：可选
注意事项：无
参数示例：16

返回值

无

示例

-- 创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})

-- 更新label显示内容大小，V1.0.1更新 
label:set_font_size(16)
4.2.1.5 label:set_symbol(symbol)

功能

将文本替换为符号字符。

参数

symbol

参数含义：符号字符
数据类型：string
是否必选：是
取值范围：airui.SYMBOL_* 常量或符号字符串
注意事项：无
示例代码：label:set_symbol(airui.SYMBOL_SETTINGS)

返回值

无

示例

-- 创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})

-- 更新内容
label:set_symbol(airui.SYMBOL_SETTINGS)
4.2.1.6 label:set_on_click(fn)

功能

设置点击回调。

参数

fn

参数含义：回调函数
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：点击标签时触发
参数示例：
        label:set_on_click(function() 
            log.info("label tapped twice") 
        end)

返回值

无

示例

-- 创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})
-- 设置点击回调函数
label:set_on_click(function() 
    log.info("label tapped twice") 
end)
4.2.1.7 label:get_text()

功能

获取当前文本。

参数

无

返回值

local text_content = label:get_text()

text_content

含义说明：当前文本内容
数据类型：string
取值范围：标签显示的文本
注意事项：如果标签显示的是符号，则返回符号字符串
返回示例："Hello, World!"

示例

-- 创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})
--获取当前文本内容
local text = label:get_text()
log.info("label", "当前文本：" .. text)
4.2.1.8 label:move(dx, dy) -- V1.1.5 新增

功能

移动标签相对当前位置偏移指定像素距离。

参数

dx

参数含义：X轴偏移量，正数向右，负数向左
数据类型：number
取值范围：整数
是否必选：是
注意事项：无
参数示例：10

dy

参数含义：Y轴偏移量，正数向下，负数向上
数据类型：number
取值范围：整数
是否必选：是
注意事项：无
参数示例：10

返回值

无

示例

local label = airui.label({
    text = "move me",
    x = 20, y = 80,
})

-- 向右移动10像素，向下移动20像素
label:move(10, 20)
4.2.1.9 label:get_pos() -- V1.2.1 新增

功能

获取标签当前的位置坐标。

参数

无

返回值

local x, y = label:get_pos()

x, y

含义说明：标签的当前坐标位置
数据类型：number, number
取值范围：x为X坐标，y为Y坐标
注意事项：返回两个值
返回示例：20, 80

示例

local label = airui.label({
    text = "get_pos me",
    x = 20, y = 80,
})

local x, y = label:get_pos()
log.info("label", "position: " .. x .. ", " .. y)
4.2.1.10 label:set_pos(x, y) -- V1.2.1 新增

功能

设置标签的绝对位置。

参数

x

参数含义：X坐标
数据类型：number
是否必选：是
取值范围：0到屏幕宽度
参数示例：100

y

参数含义：Y坐标
数据类型：number
是否必选：是
取值范围：0到屏幕高度
参数示例：200

返回值

无

示例

local label = airui.label({
    text = "set_pos me",
    x = 20, y = 80,
})

-- 设置新位置
label:set_pos(100, 200)
4.2.1.11 label:is_destroyed() -- V1.2.1 新增

功能

检查标签组件是否已被销毁。

参数

无

返回值

local destroyed = label:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80,
})

if not label:is_destroyed() then
    label:set_text("still alive")
end
4.2.1.12 label:destroy()

功能

销毁组件。

参数

无

返回值

无

示例

-- 创建文本标签
local label = airui.label({
    text = "Hello, World!",
    x = 20, y = 80, w = 500, h = 500,
})
-- 销毁标签
label:destroy()

4.2.2 图像（airui.image）

4.2.2.1 airui.image(config)

功能

显示图片，支持静态图片/符号、缩放与透明度控制。

参数

config

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

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

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

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

    参数含义：图片路径
    数据类型：string
    取值范围：有效的图片文件路径
    是否必选：是
    注意事项：目前只支持jpg和png两种图片格式
    参数示例：src = "/luadb/image.png"
    src = ,

    参数含义：图片内容适配模式 -- V1.2.1 更新
    数据类型：string
    取值范围："center"（不缩放居中显示）、"contain"（等比缩放完整显示）、"cover"（等比缩放铺满裁剪）、"stretch"（拉伸填满）
    是否必选：可选
    注意事项：默认 "center"。控制图片在控件区域内如何适配显示
    参数示例：fit = "cover"
    fit = ,

    参数含义：旋转中心
    数据类型：table
    取值范围：包含x和y键的表，值为绝对像素坐标
    是否必选：可选
    注意事项：1、仅限PNG图片有效：pivot参数只对PNG格式图片有效，JPG图片不支持
              2、配合rotation使用：pivot通常与rotation参数一起使用才有意义
              3、绝对坐标：x和y的值是绝对像素坐标，不是相对比例
              4、坐标范围：最小值为0（图片左上角），最大值为图片宽度和高度（图片右下角）
              5、缩放影响：缩放后需要按比例调整pivot值，否则旋转中心会相对于图片内容偏移
              6、推荐计算：使用公式 pivot_x = img_w * percentage_x * (zoom/256) 来计算合适的pivot值
    参数示例：pivot = {x=128, y=128} -- 对于256x256的图片，中心点坐标为(128, 128)
    pivot = ,

    参数含义：旋转角度 -- V1.1.0 更新
    数据类型：number
    取值范围：0~3600（0.1度单位，即900表示90度）
    是否必选：可选
    注意事项：默认0。仅限png图片格式有效
    参数示例：rotation = 900
    rotation = ,

    参数含义：缩放比例
    数据类型：number
    取值范围：整数，256=100%
    是否必选：可选
    注意事项：仅限png图片，jpg图片无效
    参数示例：zoom = 256
    zoom = ,

    参数含义：透明度
    数据类型：number
    取值范围：0~255
    是否必选：可选
    注意事项：仅限png图片，jpg图片无效
    参数示例：opacity = 255
    opacity = ,

    参数含义：点击回调函数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：点击图像时触发
    参数示例：on_click = function(self) log.info("airui.image", "image clicked") end
    on_click = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：parent = airui.screen
    parent = ,
}

返回值

local image_object = airui.image(config)

image_object

含义说明：图像组件对象
数据类型：userdata
取值范围：包含 set_src、set_zoom、set_opacity、set_pivot、set_rotation、set_fit、get_pos、set_pos、move、is_destroyed、destroy 等方法的图像对象
注意事项：需要添加到界面中才能显示
返回示例：image_object

示例

-- 示例1：可点击图片
local img = airui.image({
    parent = airui.screen, -- 父对象，可选，默认当前屏幕
    src = "/luadb/test.jpg",
    x = 20, y = 20, w = 256, h = 256,
    zoom = 256,    -- 缩放比例，默认 256（100%），jpg必须为默认值
    opacity = 255, -- 透明度，默认 255（不透明），范围 0-255，jpg必须为默认值
    on_click = function(self)
        log.info("airui.image", "image clicked")
    end
})

-- 示例2：PNG图片（支持透明度和缩放）
local img1 = airui.image({
    parent = airui.screen, -- 父对象，可选，默认当前屏幕
    src = "/luadb/sunset.png",
    x = 400, y = 160, w = 100, h = 100,
    zoom = 256,    -- 缩放比例，默认 256（100%）
    opacity = 100, -- 透明度，默认 255（不透明），范围 0-255
})

-- 示例3：PNG图片设置旋转中心并旋转
local img_width = 200
local img_height = 200
local img2 = airui.image({
    parent = airui.screen,
    src = "/luadb/test.png",
    x = 100, y = 100, 
    w = img_width, h = img_height,
    pivot = {x = img_width / 2, y = img_height / 2},  -- 绝对坐标：100, 100（中心点）
    rotation = 900,  -- 旋转90度
    zoom = 256,
})

-- 示例4：缩放图片时调整旋转中心
local img_width = 200
local img_height = 200
local zoom_scale = 512  -- 200%缩放

-- 计算缩放后的中心点坐标
local pivot_x = (img_width / 2) * (zoom_scale / 256)
local pivot_y = (img_height / 2) * (zoom_scale / 256)

local img3 = airui.image({
    parent = airui.screen,
    src = "/luadb/test.png",
    x = 100, y = 300, 
    w = img_width, h = img_height,
    pivot = {x = pivot_x, y = pivot_y},  -- 缩放后的中心坐标：200, 200
    rotation = 1800,  -- 旋转180度
    zoom = zoom_scale,
})

-- 示例3：创建点击后修改自身属性的图片，例如：来回切换图标
local icon_play = "/luadb/play.png"
local icon_stop = "/luadb/stop.png"

-- 状态变量：true 表示当前为“播放”图标，false 表示当前为“停止”图标
local is_play = true

-- 创建可点击的图片控件
local img = airui.image({
    parent = airui.screen,   -- 父对象，可选，默认当前屏幕
    src = icon_play,         -- 初始显示播放图标
    x = 20, y = 20, w = 64, h = 64,  -- 尺寸根据需要调整
    zoom = 256,              -- 缩放比例，256 表示 100%
    opacity = 255,           -- 不透明度
    on_click = function(self)
        if is_play then
            self:set_src(icon_stop)  -- 当前是播放，点击后切换为停止图标
            is_play = false
        else
            self:set_src(icon_play)  -- 当前是停止，点击后切换为播放图标
            is_play = true
        end
        log.info("airui.image", "icon switched")
    end
})
4.2.2.2 image:set_src(src)

功能

替换图片来源。

参数

src

参数含义：图片路径或符号名
数据类型：string
是否必选：是
取值范围：有效的图片文件路径或符号字符串
注意事项：目前只支持jpg和png两种图片格式
参数示例："/luadb/new.jpg"
示例代码：src = "/luadb/new.jpg"

返回值

无

示例

-- 显示图片
local img = airui.image({
    parent = airui.screen, -- 父对象，可选，默认当前屏幕
    src = "/luadb/test.jpg",
    x = 20, y = 20, w = 256, h = 256,
    zoom = 256,    -- 缩放比例，默认 256（100%），jpg必须为默认值
    opacity = 255, -- 透明度，默认 255（不透明），范围 0-255，jpg必须为默认值
    on_click = function(self)
        log.info("airui.image", "image clicked")
    end
})
-- 替换图片
img:set_src("/luadb/new.jpg")
4.2.2.3 image:set_zoom(zoom)

功能

设置图片显示缩放比例（256 表示 100%）。

参数

zoom

参数含义：缩放值
数据类型：number
是否必选：是
取值范围：整数，256=100%
注意事项：仅限png图片，jpg图片无效
参数示例：512
示例代码：zoom = 512

返回值

无

示例

-- 显示图片
local img = airui.image({
    parent = airui.screen, -- 父对象，可选，默认当前屏幕
    src = "/luadb/test.jpg",
    x = 20, y = 20, w = 256, h = 256,
    zoom = 256,    -- 缩放比例，默认 256（100%），jpg必须为默认值
    opacity = 255, -- 透明度，默认 255（不透明），范围 0-255，jpg必须为默认值
    on_click = function(self)
        log.info("airui.image", "image clicked")
    end
})
-- 放大到200%
img:set_zoom(512)
4.2.2.4 image:set_opacity(opacity)

功能

调整图片透明度。

参数

opacity

参数含义：透明度值
数据类型：number
是否必选：是
取值范围：0~255
注意事项：仅限png图片，jpg图片无效
参数示例：128
示例代码：opacity = 128

返回值

无

示例

-- 显示图片
local img = airui.image({
    parent = airui.screen, -- 父对象，可选，默认当前屏幕
    src = "/luadb/test.jpg",
    x = 20, y = 20, w = 256, h = 256,
    zoom = 256,    -- 缩放比例，默认 256（100%），jpg必须为默认值
    opacity = 255, -- 透明度，默认 255（不透明），范围 0-255，jpg必须为默认值
    on_click = function(self)
        log.info("airui.image", "image clicked")
    end
})
-- 设置为半透明
img:set_opacity(128)
4.2.2.5 image:get_pos()

功能

获取图片当前的位置坐标。

参数

无

返回值

local x, y = image:get_pos()

x, y

含义说明：图片的当前坐标位置
数据类型：number, number
取值范围：x为X坐标，y为Y坐标
注意事项：返回两个值
返回示例：20, 80

示例

-- 创建图片
local img = airui.image({
    src = "/luadb/test.jpg",
    x = 20, y = 80, w = 256, h = 256,
})

-- 获取当前位置
local x, y = img:get_pos()
log.info("image", "position: " .. x .. ", " .. y)
4.2.2.6 image:set_pos(x, y)

功能

设置图片的绝对位置。

参数

x

参数含义：X坐标
数据类型：number
是否必选：是
取值范围：0到屏幕宽度
参数示例：100

y

参数含义：Y坐标
数据类型：number
是否必选：是
取值范围：0到屏幕高度
参数示例：200

返回值

无

示例

-- 创建图片
local img = airui.image({
    src = "/luadb/test.jpg",
    x = 20, y = 80, w = 256, h = 256,
})

-- 设置新位置
img:set_pos(100, 200)
4.2.2.7 image:move(dx, dy) -- V1.1.5 新增

功能

相对移动图片位置。

参数

dx

参数含义：X方向偏移量
数据类型：number
是否必选：是
取值范围：任意整数
参数示例：10

dy

参数含义：Y方向偏移量
数据类型：number
是否必选：是
取值范围：任意整数
参数示例：20

返回值

无

示例

-- 创建图片
local img = airui.image({
    src = "/luadb/test.jpg",
    x = 20, y = 80, w = 256, h = 256,
})

-- 向右移动10像素，向下移动20像素
img:move(10, 20)
4.2.2.8 image:set_rotation(rotation)

功能

设置图片旋转角度。

参数

rotation

参数含义：旋转角度
数据类型：number
是否必选：是
取值范围：0~3600（0.1度单位，即900表示90度）
注意事项：仅限png图片格式有效
参数示例：900

返回值

无

示例

-- 创建图片
local img = airui.image({
    src = "/luadb/test.png",
    x = 20, y = 80, w = 256, h = 256,
})

-- 旋转90度
img:set_rotation(900)
4.2.2.9 image:set_pivot(pivot) -- V1.1.6 新增

功能

设置图片的旋转中心点。

参数

pivot

参数含义：旋转中心点坐标
数据类型：table
是否必选：是
取值范围：包含 x 和 y 键的表，值为绝对像素坐标
注意事项：仅限PNG图片有效，需配合set_rotation或rotation参数使用
参数示例：{x = 100, y = 100}

返回值

无

示例

local img = airui.image({
    src = "/luadb/test.png",
    x = 20, y = 80, w = 200, h = 200,
})

-- 设置旋转中心为图片中心
img:set_pivot({x = 100, y = 100})

-- 旋转90度
img:set_rotation(900)
4.2.2.10 image:set_fit(fit) -- V1.2.1 新增

功能

设置图片内容适配模式，控制图片在控件区域内如何适配显示。

参数

fit

参数含义：适配模式
数据类型：string
是否必选：是
取值范围："center"（不缩放居中显示）、"contain"（等比缩放完整显示）、"cover"（等比缩放铺满裁剪）、"stretch"（拉伸填满）
注意事项：默认 "center"
参数示例："cover"

返回值

无

示例

local img = airui.image({
    src = "/luadb/image.png",
    x = 20, y = 20, w = 200, h = 200,
})

-- 设置为cover模式铺满控件
img:set_fit("cover")
4.2.2.11 image:is_destroyed() -- V1.2.1 新增

功能

检查图片组件是否已被销毁。

参数

无

返回值

local destroyed = image:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local img = airui.image({
    src = "/luadb/test.png",
    x = 20, y = 20,
})

if not img:is_destroyed() then
    log.info("image", "still alive")
end
4.2.2.12 image:destroy()

功能

销毁图片组件。

参数

无

返回值

无

示例

-- 销毁图片组件
img:destroy()

4.2.3 进度条（airui.bar）

4.2.3.1 airui.bar(config)

功能

显示进度范围，可自定义颜色与圆角。

参数

config

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

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

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

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

    参数含义：最小值
    数据类型：number
    取值范围：任意整数
    是否必选：可选
    注意事项：默认0
    参数示例：0
    min = 0,

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

    参数含义：初始值
    数据类型：number
    取值范围：min到max之间
    是否必选：可选
    注意事项：默认0
    参数示例：30
    value = 30,

    参数含义：圆角半径
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：默认0
    参数示例：5
    radius = 5,

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

    参数含义：背景颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x000000
    参数示例：0x666666
    bg_color = 0x666666,

    参数含义：指示器颜色（进度条部分）
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x0000ff
    参数示例：0x00ff00
    indicator_color = 0x00ff00,

    参数含义：边框颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x000000
    参数示例：0xffffff
    border_color = 0xffffff,

    参数含义：是否显示进度文本（显示当前值/范围）-- V1.0.3更新
    数据类型：boolean
    取值范围：true（显示），false（不显示）
    是否必选：可选
    注意事项：默认 false
    参数示例：true
    show_progress_text = true，

    参数含义：进度文本的显示格式，支持 %d 占位符（当前值），若同时显示最大值可用 %d / %d -- V1.0.3更新
    数据类型：string
    取值范围：任意字符串，包含占位符
    是否必选：可选
    注意事项：默认不设置（无文本），设置后需同时启用 show_progress_text 才能生效
    参数示例："加载 %d%%"
    progress_text_format = "加载 %d%%"，

    参数含义：进度文本的字体大小 -- V1.2.1 更新
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：仅在 hzfont 字体启用时生效，默认使用全局字体大小
    参数示例：24
    progress_text_font_size = 24，

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local bar_object = airui.bar(config)

bar_object

含义说明：进度条组件对象
数据类型：userdata
取值范围：包含 set_value、get_value、set_range、set_indicator_color、set_bg_color、set_progress_text_format、set_progress_text_color、set_progress_text_font_size、is_destroyed、destroy 等方法的进度条对象
注意事项：需要添加到界面中才能显示
返回示例：bar_object

示例

-- 创建进度条
local progress = airui.bar({ 
    x = 20, y = 220, w = 280, 
    value = 30 
})
4.2.3.2 bar:set_value(value, anim)

功能

更新当前进度，支持动画。

参数

value

参数含义：目标值
数据类型：number
是否必选：是
取值范围：min到max之间
注意事项：无
参数示例：80
示例代码：value = 80

anim

参数含义：是否启用动画
数据类型：boolean
是否必选：可选
取值范围：true（启用动画）, false（不启用动画）
注意事项：默认false
参数示例：true
示例代码：anim = true

返回值

无

示例

-- 创建进度条
local progress = airui.bar({ 
    x = 20, y = 220, w = 280, 
    value = 30 
})
-- 设置值为80，启用动画
progress:set_value(80, true)
4.2.3.3 bar:get_value()

功能

读取当前进度值。

参数

无

返回值

local current_value = bar:get_value()

current_value

含义说明：当前进度值
数据类型：number
取值范围：min到max之间
注意事项：无
返回示例：50

示例

-- 创建进度条
local progress = airui.bar({ 
    x = 20, y = 220, w = 280, 
    value = 30 
})
-- 读取当前进度值
local v = progress:get_value()
log.info("progress", "当前进度：" .. v)
4.2.3.4 bar:set_range(min, max)

功能

设置进度范围。

参数

min

参数含义：最小值
数据类型：number
是否必选：是
取值范围：任意整数
注意事项：无
参数示例：0
示例代码：min = 0

max

参数含义：最大值
数据类型：number
是否必选：是
取值范围：大于最小值的整数
注意事项：无
参数示例：200
示例代码：max = 200

返回值

无

示例

-- 创建进度条
local progress = airui.bar({ 
    x = 20, y = 220, w = 280, 
    value = 30 
})
-- 设置范围为0-100
progress:set_range(0, 100)
4.2.3.5 bar:set_indicator_color(color)

功能

更换进度条指示器颜色。

参数

color

参数含义：指示器颜色
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：0xffff00
示例代码：color = 0xffff00

返回值

无

示例

-- 创建进度条
local progress = airui.bar({ 
    x = 20, y = 220, w = 280, 
    value = 30 
})
-- 设置为黄色
progress:set_indicator_color(0xffff00)
4.2.3.6 bar:set_bg_color(color)

功能

设置背景颜色。

参数

color

参数含义：背景颜色
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：0x000000
示例代码：color = 0x000000

返回值

无

示例

-- 创建进度条
local progress = airui.bar({ 
    x = 20, y = 220, w = 280, 
    value = 30 
})

-- 设置进度条背景色为黑色
progress:set_bg_color(0x000000)
4.2.3.7 bar:set_progress_text_format(format) -- V1.0.3 更新

功能 设置进度文本的显示格式。若进度条已启用文本显示（show_progress_text = true），则立即更新显示。

参数

format

参数含义：文本格式字符串
数据类型：string
是否必选：是
取值范围：任意字符串，可使用 %d 占位符表示当前数值，使用"%d / %d"占位符表示当前数值/最大值
注意事项：若格式字符串中包含多个 %d，将依次替换为当前值、最小值、最大值（暂未支持全部，具体以实际实现为准）
参数示例：format = "进度 %d%%"

返回值

无

示例

-- 创建进度条
local progress = airui.bar {
    x = 20, y = 220, w = 280, value = 30,
    show_progress_text = true }

-- 设置按xx%方式显示当前进度值
bar:set_progress_text_format("%d%%")
4.2.3.8 bar:set_progress_text_color(color) -- V1.0.3 更新

功能

设置进度文本的颜色。若进度条已启用文本显示，立即生效。

参数

color

参数含义：文本颜色（十六进制 RGB 值）
数据类型：number
是否必选：是
取值范围：0x000000 ~ 0xffffff
注意事项：无
参数示例：color = 0xffaa00

返回值

无

示例
4.2.3.9 bar:set_progress_text_font_size(size) -- V1.2.1 新增

功能

设置进度文本的字体大小。若进度条已启用文本显示，立即生效。

参数

size

参数含义：字体大小
数据类型：number
是否必选：是
取值范围：大于0的整数
注意事项：仅在 hzfont 字体启用时生效
参数示例：24

返回值

无

示例

local progress = airui.bar {
    x = 20, y = 220, w = 280, value = 30,
    show_progress_text = true,
    progress_text_font_size = 24,
}
4.2.3.10 bar:is_destroyed() -- V1.2.1 新增

功能

检查进度条组件是否已被销毁。

参数

无

返回值

local destroyed = bar:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local progress = airui.bar({
    x = 20, y = 220, w = 280,
    value = 30,
})

if not progress:is_destroyed() then
    log.info("bar", "still alive")
end
4.2.3.11 bar:destroy()

功能

销毁进度条。

参数

无

返回值

无

示例

-- 创建进度条
local progress = airui.bar({ 
    x = 20, y = 220, w = 280, 
    value = 30 
})

-- 销毁进度条
progress:destroy()

4.2.4 表格（airui.table）

4.2.4.1 airui.table(config)

功能

用于展示数据表格，支持设置各列宽及边框颜色。

参数

config

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

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

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

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

    参数含义：行数
    数据类型：number
    取值范围：大于0的整数
    是否必选：是
    注意事项：无
    参数示例：3
    rows = 3,

    参数含义：列数
    数据类型：number
    取值范围：大于0的整数
    是否必选：是
    注意事项：无
    参数示例：3
    cols = 3,

    参数含义：列宽数组或统一列宽 -- V1.1.3 更新
    数据类型：number/table
    取值范围：若为数字，则所有列宽相同；若为数组，则数组长度应与列数一致
    是否必选：可选
    注意事项：默认按总宽度平均分配
    参数示例：{80, 180, 180} 或 180
    col_width = {100, 150, 100},

    参数含义：行高数组或统一行高 -- V1.1.3 更新
    数据类型：number/table
    取值范围：若为数字，则所有行高相同；若为数组，则数组长度应与行数一致
    是否必选：可选
    注意事项：默认按总高度平均分配
    参数示例：{30, 40, 30} 或 30
    row_height = {30, 40, 30},

    参数含义：初始化数据（二维数组） -- V1.1.3 更新
    数据类型：table
    取值范围：包含所有行数据的数组，每行是一个包含所有列数据的数组
    是否必选：可选
    注意事项：行数和列数应与rows和cols一致
    参数示例：{
                {"ID", "Name", "Status"},
                {"001", "Module", "OK"},
                {"002", "Sensor", "Fail"},
             }
    data = { {"ID", "Name"}, {"1", "A"} },

    参数含义：边框颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x000000
    参数示例：0xcccccc
    border_color = 0xcccccc,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local table_object = airui.table(config)

table_object

含义说明：表格组件对象
数据类型：userdata
取值范围：包含 set_cell_text、set_col_width、set_border_color、set_row_height、insert、remove、set_cell_style、auto_jump_scroll_control、auto_marquee_scroll_control、get_cell_text、set_on_cell_click、is_destroyed、destroy 等方法的表格对象
注意事项：需要添加到界面中才能显示
返回示例：table_object

示例

-- 示例1：创建表格
local tbl = airui.table({ 
    x = 40, y = 260, 
    rows = 3, cols = 3 
})

-- 示例2：创建带初始化数据的表格
local tbl = airui.table({
    x = 0, y = 0, w = 480, h = 200,
    rows = 5,
    cols = 3,
    col_width = {80, 180, 180},
    row_height = 30,
    data = {
        {"ID", "Name", "状态"},
        {"001", "通讯模块", "待机"},
        {"002", "传感器", "故障"},
        {"003", "执行器", "正常"},
        {"004", "电源", "正常"},
    },
})
4.2.4.2 table:set_cell_text(row, col, text)

功能

设置特定单元格文本。

参数

row

参数含义：行索引
数据类型：number
是否必选：是
取值范围：0到rows-1
注意事项：0起始
参数示例：0
示例代码：row = 0

col

参数含义：列索引
数据类型：number
是否必选：是
取值范围：0到cols-1
注意事项：0起始
参数示例：0
示例代码：col = 0

text

参数含义：文本内容
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：无
参数示例："数据"
示例代码：text = "数据"

返回值

无

示例

-- 创建表格
local tbl = airui.table({ 
    x = 40, y = 260, 
    rows = 3, cols = 3 
})

-- 第0行第0列设置为"标题"
tbl:set_cell_text(0, 0, "标题")
-- 第2行第3列设置为"数据"
tbl:set_cell_text(1, 2, "数据")
4.2.4.3 table:set_col_width(col, width)

功能

调整列宽。

参数

col

参数含义：列索引
数据类型：number
是否必选：是
取值范围：0到cols-1
注意事项：0起始
参数示例：0
示例代码：col = 0

width

参数含义：宽度值
数据类型：number
是否必选：是
取值范围：大于0的整数
注意事项：无
参数示例：120
示例代码：width = 120参数含义：宽度值
数据类型：number
是否必选：是
取值范围：大于0的整数
注意事项：无
参数示例：120
示例代码：width = 120

返回值

无

示例

-- 创建表格
local tbl = airui.table({ 
    x = 40, y = 260, 
    rows = 3, cols = 3 
})

-- 设置第1列宽度为120
tbl:set_col_width(0, 120)
4.2.4.4 table:set_border_color(color)

功能

设置边框颜色。

参数

color

参数含义：边框颜色
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：0xff00ff
示例代码：color = 0xff00ff

返回值

无

示例

-- 创建表格
local tbl = airui.table({ 
    x = 40, y = 260, 
    rows = 3, cols = 3 
})

-- 设置边框为紫色
tbl:set_border_color(0xff00ff)
4.2.4.5 table:set_row_height(row, height) -- V1.1.3 更新

功能

设置特定行的高度。

参数

row

参数含义：行索引
数据类型：number
是否必选：是
取值范围：0到rows-1
注意事项：0起始
参数示例：0
示例代码：row = 0

height

参数含义：高度值
数据类型：number
是否必选：是
取值范围：大于0的整数
注意事项：无
参数示例：30
示例代码：height = 30

返回值

无

示例

-- 创建表格
local tbl = airui.table({
    x = 40, y = 260,
    rows = 3, cols = 3
})

-- 设置第0行高度为40像素
tbl:set_row_height(0, 40)
-- 设置第2行高度为50像素
tbl:set_row_height(2, 50)
4.2.4.6 table:insert(type, index, data, anim) -- V1.1.4 新增

功能

在表格中插入行或列。

参数

type

参数含义：插入类型
数据类型：string
是否必选：是
取值范围："row"（插入行）, "column"（插入列）
注意事项：无
参数示例："row"
示例代码：type = "row"

index

参数含义：插入位置索引
数据类型：number
是否必选：是
取值范围：0到rows-1 或 0到cols-1
注意事项：0起始，在该位置之前插入
参数示例：1
示例代码：index = 1

data

参数含义：插入的数据
数据类型：table
是否必选：是
取值范围：对于行插入，为包含列数据的数组；对于列插入，为包含行数据的数组
注意事项：无
参数示例：{"新数据1", "新数据2", "新数据3"}
示例代码：data = {"新数据1", "新数据2", "新数据3"}

anim

参数含义：是否使用动画
数据类型：boolean
是否必选：可选
取值范围：true（使用动画）, false（不使用动画）
注意事项：默认false
参数示例：true
示例代码：anim = true

返回值

无

示例

-- 创建表格
local tbl = airui.table({
    x = 40, y = 260,
    rows = 3, cols = 3
})

-- 在第1行位置插入新行
tbl:insert("row", 1, {"ID", "Name", "状态"}, true)

-- 在第0列位置插入新列
tbl:insert("column", 0, {"新列1", "新列2", "新列3"}, false)
4.2.4.7 table:remove(type, index, anim) -- V1.1.4 新增

功能

从表格中移除行或列。

参数

type

参数含义：移除类型
数据类型：string
是否必选：是
取值范围："row"（移除行）, "column"（移除列）
注意事项：无
参数示例："row"
示例代码：type = "row"

index

参数含义：移除位置索引
数据类型：number
是否必选：是
取值范围：0到rows-1 或 0到cols-1
注意事项：0起始
参数示例：1
示例代码：index = 1

anim

参数含义：是否使用动画
数据类型：boolean
是否必选：可选
取值范围：true（使用动画）, false（不使用动画）
注意事项：默认false
参数示例：true
示例代码：anim = true

返回值

无

示例

-- 创建表格
local tbl = airui.table({
    x = 40, y = 260,
    rows = 3, cols = 3
})

-- 移除第1行
tbl:remove("row", 1, true)

-- 移除第0列
tbl:remove("column", 0, false)
4.2.4.8 table:set_cell_style(target, index, style) -- V1.1.4 新增

功能

设置单元格或行/列的样式。

参数

target

参数含义：样式应用目标
数据类型：string
是否必选：是
取值范围："row"（设置行样式）, "column"（设置列样式）, "cell"（设置单元格样式）
注意事项：无
参数示例："row"
示例代码：target = "row"

index

参数含义：目标索引
数据类型：number
是否必选：是
取值范围：根据target而定
注意事项：0起始
参数示例：1
示例代码：index = 1

style

参数含义：样式配置
数据类型：table
是否必选：是
取值范围：包含样式属性的表
注意事项：包含背景色、文字颜色、边框等样式属性
参数示例：{cell_text_color = 0xff0000}
示例代码：style = {cell_text_color = 0xff0000}

返回值

无

示例

-- 创建表格
local tbl = airui.table({
    x = 40, y = 260,
    rows = 3, cols = 3
})

-- 设置第1行的文字颜色为红色
tbl:set_cell_style("row", 1, {
    cell_text_color = 0xff0000
})

-- 设置第0列的背景色为灰色
tbl:set_cell_style("column", 0, {
    cell_bg_color = 0xf0f0f0
})
4.2.4.9 table:auto_jump_scroll_control(config) -- V1.1.4 新增

功能

控制表格的跳转自动滚动。

参数

config

参数含义：滚动控制配置
数据类型：table
是否必选：是
取值范围：包含以下子参数：
{
    参数含义：控制动作
    数据类型：string
    取值范围："start"（开始）、"pause"（暂停）、"resume"（恢复）、"stop"（停止）
    是否必选：是
    注意事项：无
    参数示例："start"
    action = "start",

    参数含义：滚动间隔（毫秒）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：仅在action="start"时有效，默认1500
    参数示例：1500
    interval = 1500,

    参数含义：是否循环
    数据类型：boolean
    取值范围：true（循环）、false（不循环）
    是否必选：可选
    注意事项：仅在action="start"时有效，默认true
    参数示例：true
    loop = true,

    参数含义：是否使用动画
    数据类型：boolean
    取值范围：true（使用动画）、false（直接跳转）
    是否必选：可选
    注意事项：仅在action="start"时有效，默认true
    参数示例：true
    anim = true,

    参数含义：每次前进行数
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：仅在action="start"时有效，默认1
    参数示例：1
    step = 1,

    参数含义：焦点列
    数据类型：number
    取值范围：0到cols-1
    是否必选：可选
    注意事项：仅在action="start"时有效，默认0
    参数示例：0
    focus_col = 0,
}

返回值

无

示例

-- 创建表格
local tbl = airui.table({
    x = 40, y = 260,
    rows = 10, cols = 3
})

-- 开始自动跳转滚动
tbl:auto_jump_scroll_control({
    action = "start",
    interval = 1500,
    loop = true,
    anim = true,
    step = 1,
    focus_col = 0
})

-- 暂停滚动
tbl:auto_jump_scroll_control({action = "pause"})

-- 恢复滚动
tbl:auto_jump_scroll_control({action = "resume"})

-- 停止滚动
tbl:auto_jump_scroll_control({action = "stop"})
4.2.4.10 table:auto_marquee_scroll_control(config) -- V1.1.4 新增

功能

控制表格的跑马灯式自动滚动。

参数

config

参数含义：滚动控制配置
数据类型：table
是否必选：是
取值范围：包含以下子参数：
{
    参数含义：控制动作
    数据类型：string
    取值范围："start"（开始）、"pause"（暂停）、"resume"（恢复）、"stop"（停止）
    是否必选：是
    注意事项：无
    参数示例："start"
    action = "start",

    参数含义：滚动tick间隔（毫秒）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：仅在action="start"时有效，默认30，越小更新越频繁
    参数示例：100
    interval = 100,

    参数含义：是否循环
    数据类型：boolean
    取值范围：true（循环）、false（不循环）
    是否必选：可选
    注意事项：仅在action="start"时有效，默认true
    参数示例：true
    loop = true,

    参数含义：每次tick滚动像素
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：仅在action="start"时有效，默认1，越大越快
    参数示例：1
    speed = 1,
}

返回值

无

示例

-- 创建表格
local tbl = airui.table({
    x = 40, y = 260,
    rows = 10, cols = 3
})

-- 开始跑马灯滚动
tbl:auto_marquee_scroll_control({
    action = "start",
    interval = 100,
    loop = true,
    speed = 1
})

-- 暂停滚动
tbl:auto_marquee_scroll_control({action = "pause"})

-- 恢复滚动
tbl:auto_marquee_scroll_control({action = "resume"})

-- 停止滚动
tbl:auto_marquee_scroll_control({action = "stop"})
4.2.4.11 table:get_cell_text(row, col) -- V1.2.1 新增

功能

获取指定单元格的文本内容。

参数

row

参数含义：行索引
数据类型：number
是否必选：是
取值范围：0到rows-1
注意事项：0起始
参数示例：0

col

参数含义：列索引
数据类型：number
是否必选：是
取值范围：0到cols-1
注意事项：0起始
参数示例：1

返回值

local text = table:get_cell_text(row, col)

text

含义说明：单元格文本内容
数据类型：string
注意事项：若单元格为空则返回空字符串
返回示例："数据"

示例

-- 创建表格
local tbl = airui.table({
    x = 40, y = 260,
    rows = 3, cols = 3,
    data = {
        {"ID", "Name", "Status"},
        {"001", "Module", "OK"},
    },
})

-- 获取第0行第1列的文本
local name = tbl:get_cell_text(0, 1)
log.info("table", "cell text: " .. name)
4.2.4.12 table:set_on_cell_click(callback) -- V1.2.1 新增

功能

设置表格单元格点击回调函数。

参数

callback

参数含义：单元格点击回调函数
数据类型：function
是否必选：是
取值范围：function(row, col, value)
说明：
  - row: 被点击单元格的行索引（0起始）
  - col: 被点击单元格的列索引（0起始）
  - value: 被点击单元格的文本内容
参数示例：function(row, col, value)
    log.info("table", "cell clicked", row, col, value)
end

返回值

无

示例

local tbl = airui.table({
    x = 40, y = 260,
    rows = 3, cols = 3,
    data = {
        {"A1", "B1", "C1"},
        {"A2", "B2", "C2"},
    },
})

-- 设置单元格点击回调
tbl:set_on_cell_click(function(row, col, value)
    log.info("table", "clicked:", row, col, value)
end)
4.2.4.13 table:is_destroyed() -- V1.2.1 新增

功能

检查表格组件是否已被销毁。

参数

无

返回值

local destroyed = table:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local tbl = airui.table({
    x = 40, y = 260,
    rows = 3, cols = 3,
})

if not tbl:is_destroyed() then
    log.info("table", "still alive")
end
4.2.4.14 table:destroy()

功能

销毁表格组件。

参数

无

返回值

无

示例

-- 创建表格
local tbl = airui.table({ 
    x = 40, y = 260, 
    rows = 3, cols = 3 
})

-- 销毁表格
tbl:destroy()

4.2.5 动画图像（airui.animimg） -- V1.1.4 新增

4.2.5.1 airui.animimg(config)

功能

创建动画图像组件，支持多帧图片循环播放、控制播放状态。

参数

config

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

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

    参数含义：动画图像宽度
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认100
    参数示例：w = 380
    w = ,

    参数含义：动画图像高度
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认100
    参数示例：h = 380
    h = ,

    参数含义：图片帧列表
    数据类型：table
    取值范围：包含图片路径的数组
    是否必选：是
    注意事项：支持PNG和JPG格式
    参数示例：{"/luadb/frame1.png", "/luadb/frame2.png"}
    frames = {"/luadb/fly_man_01.png", "/luadb/fly_man_02.png"},

    参数含义：总动画时长（毫秒）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认1000
    参数示例：960
    duration = 960，

    参数含义：是否循环播放
    数据类型：boolean
    取值范围：true（循环），false（不循环）
    是否必选：可选
    注意事项：默认false
    参数示例：false
    loop = false,

    参数含义：是否自动播放
    数据类型：boolean
    取值范围：true（自动播放），false（手动控制）
    是否必选：可选
    注意事项：默认false
    参数示例：true
    auto_play = true,

    参数含义：是否反向播放
    数据类型：boolean
    取值范围：true（反向），false（正向）
    是否必选：可选
    注意事项：默认false
    参数示例：false
    reverse = false,

    参数含义：播放完成回调函数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：动画播放完成时触发
    参数示例：function() log.info("animimg", "complete") end
    on_complete = function() log.info("animimg", "complete") end,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local animimg_object = airui.animimg(config)

animimg_object

含义说明：动画图像组件对象
数据类型：userdata
取值范围：包含 play、pause、stop、set_src、is_destroyed、destroy 等方法的动画图像对象
注意事项：需要添加到界面中才能显示
返回示例：animimg_object

示例

-- 创建动画帧列表
local forward_frames = {
    "/luadb/fly_man_01.png",
    "/luadb/fly_man_02.png",
    "/luadb/fly_man_03.png",
    "/luadb/fly_man_04.png",
}

-- 创建动画图像，自动播放
local anim = airui.animimg({
    parent = airui.screen,
    x = 15, y = 15, w = 350, h = 350,
    frames = forward_frames,
    duration = 960,
    loop = false,
    auto_play = true,
    on_complete = function()
        log.info("animimg", "complete")
    end,
})

-- 播放动画
anim:play()

-- 暂停动画
anim:pause()

-- 停止动画
anim:stop()

-- 切换动画帧列表
local bounce_frames = {
    "/luadb/fly_man_01.png",
    "/luadb/fly_man_02.png",
    "/luadb/fly_man_01.png",
}
anim:set_src(bounce_frames)
4.2.5.2 animimg:play()

功能

开始或继续播放动画。

参数

无

返回值

无

示例

-- 创建动画图像
local anim = airui.animimg({
    x = 20, y = 140, w = 380, h = 380,
    frames = {"/luadb/frame1.png", "/luadb/frame2.png"},
    auto_play = false,
})

-- 开始播放
anim:play()
4.2.5.3 animimg:pause()

功能

暂停动画播放。

参数

无

返回值

无

示例

-- 创建动画图像
local anim = airui.animimg({
    x = 20, y = 140, w = 380, h = 380,
    frames = {"/luadb/frame1.png", "/luadb/frame2.png"},
    auto_play = true,
})

-- 暂停播放
anim:pause()
4.2.5.4 animimg:stop()

功能

停止动画并重置到第一帧。

参数

无

返回值

无

示例

-- 创建动画图像
local anim = airui.animimg({
    x = 20, y = 140, w = 380, h = 380,
    frames = {"/luadb/frame1.png", "/luadb/frame2.png"},
    auto_play = true,
})

-- 停止播放并重置
anim:stop()
4.2.5.5 animimg:set_src(frames)

功能

动态替换动画帧列表。

参数

frames

参数含义：新的图片帧列表
数据类型：table
取值范围：包含图片路径的数组
是否必选：是
注意事项：支持PNG和JPG格式
参数示例：{"/luadb/new_frame1.png", "/luadb/new_frame2.png"}
示例代码：frames = {"/luadb/frame1.png", "/luadb/frame2.png"}

返回值

无

示例

-- 创建动画图像
local anim = airui.animimg({
    x = 20, y = 140, w = 380, h = 380,
    frames = {"/luadb/frame1.png", "/luadb/frame2.png"},
})

-- 切换到新的动画帧列表
local new_frames = {
    "/luadb/fly_man_01.png",
    "/luadb/fly_man_02.png",
}
anim:set_src(new_frames)
anim:play()
4.2.5.6 animimg:destroy()

功能

销毁动画图像组件。

参数

无

返回值

无

示例

-- 创建动画图像
local anim = airui.animimg({
    x = 20, y = 140, w = 380, h = 380,
    frames = {"/luadb/frame1.png", "/luadb/frame2.png"},
})

-- 销毁组件
anim:destroy()

4.2.6 形状（airui.shape） -- V1.1.6 新增

4.2.6.1 airui.shape(config)

功能

创建形状绘制组件，通过 items 数组支持同时绘制直线、圆形、椭圆、矩形/圆角矩形等多种图元。图元坐标相对于组件左上角。

参数

config

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

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

    参数含义：形状宽度（绘制区域宽）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认100
    参数示例：w = 200
    w = ,

    参数含义：形状高度（绘制区域高）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认100
    参数示例：h = 200
    h = ,

    参数含义：图元数组
    数据类型：table
    取值范围：数组，每个元素为 table，包含以下字段：
      公共字段：
      - type (string): 图元类型，必填。可选 "line"（直线）、"circle"（圆形）、"ellipse"（椭圆）、"rect"（矩形/圆角矩形）
      - color (number): 描边颜色 0xRRGGBB，默认 0xffffff
      - width (number): 描边宽度，默认 1
      - opacity (number): 描边透明度 0-255，默认 255
      - fill (boolean): 是否填充，默认 false
      - fill_color (number): 填充颜色 0xRRGGBB，默认同 color
      - fill_opacity (number): 填充透明度 0-255
      line 专用：
      - x1, y1 (number): 起点坐标，默认 0
      - x2, y2 (number): 终点坐标，默认 0
      - dash_width (number): 虚线实线段长度，默认 0
      - dash_gap (number): 虚线间隔长度，默认 0
      - round_start (boolean): 起点圆头，默认 false
      - round_end (boolean): 终点圆头，默认 false
      circle 专用：
      - cx, cy (number): 圆心坐标，默认 0
      - r (number): 半径，默认 0
      ellipse 专用：
      - cx, cy (number): 中心坐标，默认 0
      - rx, ry (number): X/Y 半径，默认 0
      - segments (number): 折线分段数，可选，不填时自动计算
      rect 专用：
      - x, y (number): 左上角坐标，默认 0
      - w, h (number): 宽高，默认 0
      - radius (number): 圆角半径，默认 0
    是否必选：可选
    注意事项：图元坐标相对于 shape 组件左上角。一个 shape 可包含多个不同类型的图元。
    参数示例：见下方示例
    items = {
        {type = "line", x1 = 10, y1 = 10, x2 = 100, y2 = 10, color = 0xff0000, width = 2},
    },

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：parent = airui.screen
    parent = ,
}

返回值

local shape_object = airui.shape(config)

shape_object

含义说明：形状组件对象
数据类型：userdata
取值范围：包含 set_items、add_item、clear、get_count、get_pos、set_pos、move、is_destroyed、destroy 等方法的形状对象
注意事项：需要添加到界面中才能显示
返回示例：shape_object

示例

-- 示例1：直线（含虚线、圆头）
airui.shape({
    x = 20, y = 50, w = 720, h = 420,
    items = {
        {type = "line", x1 = 40, y1 = 60, x2 = 680, y2 = 60,
         color = 0xff3b30, width = 2},
        {type = "line", x1 = 40, y1 = 120, x2 = 680, y2 = 120,
         color = 0x22c55e, width = 6,
         round_start = true, round_end = true},
        {type = "line", x1 = 40, y1 = 200, x2 = 680, y2 = 200,
         color = 0x38bdf8, width = 2,
         dash_width = 8, dash_gap = 6},
    },
})

-- 示例2：圆形（描边/填充）
airui.shape({
    x = 20, y = 50, w = 720, h = 420,
    items = {
        {type = "circle", cx = 120, cy = 200, r = 60,
         color = 0xff3b30, width = 2},
        {type = "circle", cx = 320, cy = 200, r = 60,
         color = 0x22c55e, width = 2,
         fill = true, fill_color = 0x14532d, fill_opacity = 200},
    },
})

-- 示例3：椭圆（指定分段数）
airui.shape({
    x = 20, y = 50, w = 720, h = 420,
    items = {
        {type = "ellipse", cx = 180, cy = 200, rx = 120, ry = 60,
         color = 0xff3b30, width = 2},
        {type = "ellipse", cx = 520, cy = 200, rx = 120, ry = 60,
         color = 0x22c55e, width = 2,
         fill = true, fill_color = 0x14532d, fill_opacity = 200,
         segments = 64},
    },
})

-- 示例4：矩形/圆角矩形
airui.shape({
    x = 20, y = 50, w = 720, h = 420,
    items = {
        {type = "rect", x = 40, y = 40, w = 180, h = 120,
         color = 0xff3b30, width = 2},
        {type = "rect", x = 260, y = 40, w = 180, h = 120, radius = 20,
         color = 0x22c55e, width = 2,
         fill = true, fill_color = 0x14532d, fill_opacity = 200},
        {type = "rect", x = 480, y = 40, w = 200, h = 120, radius = 60,
         color = 0x38bdf8, width = 4,
         fill = true, fill_color = 0x38bdf8, fill_opacity = 60},
    },
})

-- 示例5：多种图元混合
local shape = airui.shape({
    x = 30, y = 80, w = 360, h = 220,
    items = {
        {type = "rect", x = 0, y = 0, w = 360, h = 220, radius = 12,
         color = 0xe2e8f0, width = 2,
         fill = true, fill_color = 0x0f172a, fill_opacity = 255},
        {type = "circle", cx = 90, cy = 110, r = 50,
         color = 0x22c55e, width = 2,
         fill = true, fill_color = 0x14532d, fill_opacity = 200},
        {type = "ellipse", cx = 250, cy = 110, rx = 80, ry = 40,
         color = 0xfbbf24, width = 2},
    },
})
4.2.6.2 shape:set_items(items)

功能

整体替换所有图元。

参数

items

参数含义：图元数组
数据类型：table
取值范围：格式同构造函数中的 items 参数
是否必选：是
注意事项：会清空旧图元并整体替换为新图元
参数示例：见示例

返回值

无

示例

shape:set_items({
    {type = "rect", x = 0, y = 0, w = 360, h = 220, radius = 12,
     color = 0xe2e8f0, width = 2,
     fill = true, fill_color = 0x0f172a, fill_opacity = 255},
    {type = "circle", cx = 90, cy = 110, r = 50,
     color = 0x22c55e, width = 2,
     fill = true, fill_color = 0x14532d, fill_opacity = 200},
})
4.2.6.3 shape:add_item(item)

功能

添加一个新图元。

参数

item

参数含义：单个图元配置
数据类型：table
取值范围：格式同 items 数组中的单个元素，公共字段和各 type 专用字段同上
是否必选：是
注意事项：新图元追加到已有图元末尾
参数示例：{type = "circle", cx = 50, cy = 50, r = 20, color = 0xff0000, fill = true}

返回值

无

示例

shape:add_item({
    type = "circle",
    cx = 50,
    cy = 50,
    r = 20,
    color = 0xff0000,
    width = 2,
    fill = true,
    fill_color = 0x00ff00,
    fill_opacity = 200,
})
4.2.6.4 shape:clear()

功能

清空所有图元。

参数

无

返回值

无

示例

shape:clear()
4.2.6.5 shape:get_count()

功能

获取当前图元数量。

参数

无

返回值

count

含义说明：图元数量
数据类型：number
取值范围：大于等于 0 的整数
注意事项：无
返回示例：3

示例

local count = shape:get_count()
log.info("shape", "item count", count)
4.2.6.6 shape:get_pos()

功能

获取 shape 当前位置。

参数

无

返回值

x

含义说明：当前 X 坐标
数据类型：number
注意事项：无
返回示例：30

y

含义说明：当前 Y 坐标
数据类型：number
注意事项：无
返回示例：80

示例

local x, y = shape:get_pos()
log.info("shape", "pos", x, y)
4.2.6.7 shape:set_pos(x, y)

功能

设置 shape 位置。

参数

x

参数含义：X 坐标
数据类型：number
是否必选：是
注意事项：无
参数示例：40

y

参数含义：Y 坐标
数据类型：number
是否必选：是
注意事项：无
参数示例：80

返回值

无

示例

shape:set_pos(40, 80)
4.2.6.8 shape:move(dx, dy)

功能

相对当前位置移动。

参数

dx

参数含义：X 方向偏移量
数据类型：number
是否必选：是
注意事项：正数右移，负数左移
参数示例：10

dy

参数含义：Y 方向偏移量
数据类型：number
是否必选：是
注意事项：正数下移，负数上移
参数示例：-5

返回值

无

示例

shape:move(10, 5)
4.2.6.9 shape:destroy()

功能

销毁形状组件，释放资源。

参数

无

返回值

无

示例

local shape = airui.shape({
    x = 20, y = 50, w = 720, h = 420,
    items = {
        {type = "rect", x = 40, y = 40, w = 180, h = 120,
         color = 0xff3b30, width = 2},
    },
})

-- 销毁形状
shape:destroy()
4.2.6.10 shape:is_destroyed()

功能

检查组件是否已被销毁。

参数

无

返回值

status

含义说明：是否已销毁
数据类型：boolean
取值范围：true（已销毁），false（未销毁）
注意事项：销毁后调用其他方法可能报错
返回示例：false

示例

local destroyed = shape:is_destroyed()
log.info("shape", "is_destroyed", destroyed)

4.2.7 开关（airui.switch）

4.2.7.1 airui.switch(config)

功能

提供 boolean 状态切换弹性控件，可绑定风格与 change 回调。

参数

config

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

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

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

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

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

    参数含义：预设样式
    数据类型：table
    取值范围：样式配置表
    是否必选：可选
    注意事项：无
    参数示例：{}
    style = {},

    参数含义：状态变化回调函数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：开关状态变化时触发
    参数示例：function(self) log.info("当期开关状态", self:get_state()) end
    on_change = function(self) log.info("当期开关状态", self:get_state()) end,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local switch_object = airui.switch(config)

switch_object

含义说明：开关组件对象
数据类型：userdata
取值范围：包含 set_state、get_state、set_on_change、is_destroyed、destroy 等方法的开关对象
注意事项：需要添加到界面中才能显示
返回示例：switch_object

示例

-- 创建开关
local sw = airui.switch({ 
    x = 20, y = 360, 
    checked = true 
})

-- 创建一个点击自动打印当前状态的开关
local sw = airui.switch({
    x = 20,
    y = 360,
    checked = true,
    on_change = function(self)
        log.info("当期开关状态", self:get_state())
    end,
})
4.2.7.2 switch:set_state(state)

功能

设置开关状态。

参数

state

参数含义：开关状态
数据类型：boolean
是否必选：是
取值范围：true（开启）, false（关闭）
注意事项：无
参数示例：false
示例代码：state = false

返回值

无

示例

-- 创建开关
local sw = airui.switch({ 
    x = 20, y = 360, 
    checked = true 
})

-- 设置开关状态为关闭
sw:set_state(false)
4.2.7.3 switch:get_state()

功能

获取当前开关状态。

参数

无

返回值

local current_state = switch:get_state()

current_state

含义说明：当前开关状态
数据类型：boolean
取值范围：true（开启）, false（关闭）
注意事项：无
返回示例：true

示例

-- 创建开关
local sw = airui.switch({ 
    x = 20, y = 360, 
    checked = true 
})

-- 设置开关状态为关闭
sw:set_state(false)

-- 获取当前开关状态
local checked = sw:get_state()
log.info("switch", "当前状态：" .. tostring(checked))local checked = sw:get_state()
log.info("switch", "当前状态：" .. tostring(checked))
4.2.7.4 switch:set_on_change(callback)

功能

设置开关状态变化回调。

参数

callback

参数含义：回调函数
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：函数参数为开关状态
参数示例：function(self) log.info("当期开关状态", self:get_state()) end
示例代码：callback = function(self) log.info("当期开关状态", self:get_state()) end

返回值

无

示例

-- 创建开关
local sw = airui.switch({ 
    x = 20, y = 360, 
    checked = true 
})

-- 设置开关状态变化回调
sw:set_on_change(function(self)
    log.info("当期开关状态", self:get_state())
end)
4.2.7.5 switch:destroy()

功能

销毁开关。

参数

无

返回值

无

示例

-- 创建开关
local sw = airui.switch({ 
    x = 20, y = 360, 
    checked = true 
})

-- 销毁开关
sw:destroy()

4.2.8 按钮（airui.button）

4.2.8.1 airui.button(config)

功能

创建可点击的文本按钮，支持 on_click 回调及 toggle 逻辑。

参数

config

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

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

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

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

    参数含义：按钮显示文字
    数据类型：string
    取值范围：任意字符串
    是否必选：可选
    注意事项：默认空字符串
    参数示例：text = "点我"
    text = ,

    参数含义：字体句柄或名称 -- V1.1.3 更新
    数据类型：string
    取值范围："hzfont"
    是否必选：可选
    注意事项：若未指定，则使用全局默认字体,若airui.font_load(config)中参数global = false时需要进行指定
    参数示例：font = "hzfont"
    font = ,

    参数含义：字体大小 -- V1.1.3 更新
    数据类型：number
    取值范围：含12-255的正整数
    是否必选：可选
    注意事项：默认 16
    参数示例：font_size = 24
    font_size = ,

    参数含义：自定义样式表 -- V1.1.0 更新
    数据类型：table
    是否必选：可选
    取值范围：包含以下子参数：
    {

        参数含义：默认态背景颜色（按钮未被按下、未聚焦时的背景色）
        数据类型：number
        取值范围：十六进制 RGB 颜色值，如 0x1A73E8
        是否必选：可选
        注意事项：未设置时保留原有背景颜色
        参数示例：0x1A73E8
        bg_color = ,

        参数含义：默认态背景透明度
        数据类型：number
        取值范围：0~255，0为完全透明，255为不透明
        是否必选：可选
        注意事项：未设置时保留原有背景透明度
        参数示例：255
        bg_opa = ,

        参数含义：默认态边框颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有边框颜色
        参数示例：0x0B57D0
        border_color = ,

        参数含义：默认态边框宽度
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有边框宽度
        参数示例：2
        border_width = ,

        参数含义：默认态圆角半径
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有圆角半径
        参数示例：14
        radius = ,

        参数含义：默认态内边距，影响文字与按钮边缘的距离
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有内边距
        参数示例：8
        pad = ,

        参数含义：默认态文字颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有文字颜色
        参数示例：0xFFFFFF
        text_color = ,

        参数含义：按下态背景颜色（按钮被触摸或鼠标按下时的背景色）
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有按下态背景颜色
        参数示例：0x0B57D0
        pressed_bg_color = ,

        参数含义：按下态背景透明度
        数据类型：number
        取值范围：0~255，0为完全透明，255为不透明
        是否必选：可选
        注意事项：未设置时保留原有按下态背景透明度
        参数示例：255
        pressed_bg_opa = ,

        参数含义：按下态文字颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有按下态文字颜色
        参数示例：0xFFFFFF
        pressed_text_color = ,

        参数含义：焦点态描边颜色（通过键盘/编码器导航聚焦时的描边颜色）
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有焦点描边颜色
        参数示例：0xFFB300
        focus_outline_color = ,

        参数含义：焦点态描边宽度
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有焦点描边宽度
        参数示例：3
        focus_outline_width = ,

    }
    注意事项：未设置的样式属性将使用默认值
    参数示例：style = { bg_color = 0x1A73E8, radius = 14 }
    style = ,

    @note 在 V1.1.2 及以后，`stype` 改名为 `style`，`set_stype` 改名为 `set_style`。`stype`/`set_stype` 已在 V1.2.0 版本移除，使用会报错，请使用 `style`/`set_style`。

    参数含义：按钮点击回调函数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：点击按钮时触发
    参数示例：on_click = function() log.info("btn", "tap") end
    on_click = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：parent = airui.screen
    parent = ,
}

返回值

local button_object = airui.button(config)

button_object

含义说明：按钮组件对象
数据类型：userdata
取值范围：包含 set_text、set_on_click、set_style、get_text、set_disabled、move、get_pos、set_pos、is_destroyed、destroy 等方法的按钮对象
注意事项：需要添加到界面中才能显示
返回示例：btn_object

示例

-- 示例1：创建一个基础按钮
local btn = airui.button({ 
    text = "点我", 
    x = 20, 
    y = 80, 
    on_click = function() 
        log.info("btn", "tap") 
    end 
})

-- 示例2：创建一个支持切换显示内容的按钮，V1.0.3更新
local is_play = false
local btn = airui.button({
    text = "播放",
    x = 20,
    y = 80,
    on_click = function(self)
        if is_play then
            -- 当前是“停止”，点击后切换为“播放”
            self:set_text("播放") 
            is_play = false
        else
            -- 当前是“播放”，点击后切换为“停止”
            self:set_text("停止") 
            is_play = true
        end
    end
})

-- 示例3：使用自定义字体和大小的按钮
local btn = airui.button({
    text = "大按钮",
    font = "hzfont",
    font_size = 24,
    x = 20,
    y = 80,
    -- 这里可设置更多按钮样式，如颜色、边框、阴影、按下变化等
    style = {
        pad = 0
    },
    on_click = function()
        log.info("btn", "clicked")
    end
})
4.2.8.2 button:set_text(text)

功能

更改按钮显示文字。

参数

text

参数含义：新文本
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：无
参数示例："确认"
示例代码：text = "确认"

返回值

无

示例

local btn = airui.button({ 
    x = 20, 
    y = 80, 
    text = "点我", 
    on_click = function() 
        log.info("btn", "tap") 
    end 
})

btn:set_text("确认")
4.2.8.3 button:set_on_click(fn)

功能

更新按钮点击回调。

参数

fn

参数含义：回调函数
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：点击按钮时触发
参数示例：function() log.info("btn","clicked") end
示例代码：fn = function() log.info("btn","clicked") end

返回值

无

示例

btn:set_on_click(function() 
    log.info("btn","clicked") 
end)
4.2.8.4 button:set_style(style) -- V1.1.2 更新

功能

动态设置按钮的自定义样式（原 set_stype，已改名）。

参数

style

参数含义：自定义样式表 -- V1.1.0 更新
数据类型：table
是否必选：可选
取值范围：包含以下子参数：
    {

        参数含义：默认态背景颜色（按钮未被按下、未聚焦时的背景色）
        数据类型：number
        取值范围：十六进制 RGB 颜色值，如 0x1A73E8
        是否必选：可选
        注意事项：未设置时保留原有背景颜色
        参数示例：0x1A73E8
        bg_color = ,

        参数含义：默认态背景透明度
        数据类型：number
        取值范围：0~255，0为完全透明，255为不透明
        是否必选：可选
        注意事项：未设置时保留原有背景透明度
        参数示例：255
        bg_opa = ,

        参数含义：默认态边框颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有边框颜色
        参数示例：0x0B57D0
        border_color = ,

        参数含义：默认态边框宽度
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有边框宽度
        参数示例：2
        border_width = ,

        参数含义：默认态圆角半径
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有圆角半径
        参数示例：14
        radius = ,

        参数含义：默认态内边距，影响文字与按钮边缘的距离
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有内边距
        参数示例：8
        pad = ,

        参数含义：默认态文字颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有文字颜色
        参数示例：0xFFFFFF
        text_color = ,

        参数含义：按下态背景颜色（按钮被触摸或鼠标按下时的背景色）
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有按下态背景颜色
        参数示例：0x0B57D0
        pressed_bg_color = ,

        参数含义：按下态背景透明度
        数据类型：number
        取值范围：0~255，0为完全透明，255为不透明
        是否必选：可选
        注意事项：未设置时保留原有按下态背景透明度
        参数示例：255
        pressed_bg_opa = ,

        参数含义：按下态文字颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有按下态文字颜色
        参数示例：0xFFFFFF
        pressed_text_color = ,

        参数含义：焦点态描边颜色（通过键盘/编码器导航聚焦时的描边颜色）
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        注意事项：未设置时保留原有焦点描边颜色
        参数示例：0xFFB300
        focus_outline_color = ,

        参数含义：焦点态描边宽度
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        注意事项：未设置时保留原有焦点描边宽度
        参数示例：3
        focus_outline_width = ,

    }
注意事项：未设置的样式属性将使用默认值
参数示例：stype = { bg_color = 0x1A73E8, radius = 14 }
stype = ,

返回值

无

示例

btn:set_stype({
    bg_color = 0x188038,
    border_color = 0x188038,
    pressed_bg_color = 0x137333,
})
4.2.8.5 button:get_text() -- V1.1.6 新增

功能

获取按钮当前显示的文本。

参数

无

返回值

local text = button:get_text()

text

含义说明：按钮当前显示的文本内容
数据类型：string
注意事项：如果按钮未设置文本，返回空字符串
返回示例："click me"

示例

local btn = airui.button({
    x = 20, y = 80,
    text = "click me",
})

local text = btn:get_text()
log.info("button", "text: " .. text)
4.2.8.6 button:set_disabled(disabled) -- V1.1.6 新增

功能

设置按钮的禁用状态。禁用后按钮不可点击，视觉上呈现灰色。

参数

disabled

参数含义：是否禁用按钮
数据类型：boolean
是否必选：是
取值范围：true（禁用），false（启用）
注意事项：禁用后按钮无法响应点击事件
参数示例：true
示例代码：disabled = true

返回值

无

示例

local btn = airui.button({
    x = 20, y = 80,
    text = "click me",
})

-- 禁用按钮
btn:set_disabled(true)

-- 稍后启用按钮
sys.timerStart(function()
    btn:set_disabled(false)
end, 3000)
4.2.8.7 button:move(dx, dy) -- V1.1.5 新增

功能

移动按钮相对当前位置偏移指定像素距离。

参数

dx

参数含义：X轴偏移量，正数向右，负数向左
数据类型：number
取值范围：整数
是否必选：是
注意事项：无
参数示例：10

dy

参数含义：Y轴偏移量，正数向下，负数向上
数据类型：number
取值范围：整数
是否必选：是
注意事项：无
参数示例：10

返回值

无

示例

local btn = airui.button({
    x = 20, y = 80,
    text = "click me",
})

-- 向右移动10像素，向下移动20像素
btn:move(10, 20)
4.2.8.8 button:get_pos() -- V1.2.1 新增

功能

获取按钮当前的位置坐标。

参数

无

返回值

local x, y = button:get_pos()

x, y

含义说明：按钮的当前坐标位置
数据类型：number, number
取值范围：x为X坐标，y为Y坐标
注意事项：返回两个值
返回示例：20, 80

示例

local btn = airui.button({
    x = 20, y = 80,
    text = "click me",
})

local x, y = btn:get_pos()
log.info("button", "position: " .. x .. ", " .. y)
4.2.8.9 button:set_pos(x, y) -- V1.2.1 新增

功能

设置按钮的绝对位置。

参数

x

参数含义：X坐标
数据类型：number
是否必选：是
取值范围：0到屏幕宽度
参数示例：100

y

参数含义：Y坐标
数据类型：number
是否必选：是
取值范围：0到屏幕高度
参数示例：200

返回值

无

示例

local btn = airui.button({
    x = 20, y = 80,
    text = "click me",
})

-- 设置新位置
btn:set_pos(100, 200)
4.2.8.10 button:is_destroyed() -- V1.2.1 新增

功能

检查按钮组件是否已被销毁。

参数

无

返回值

local destroyed = button:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local btn = airui.button({
    x = 20, y = 80,
    text = "click me",
})

if not btn:is_destroyed() then
    log.info("button", "still alive")
end
4.2.8.11 button:destroy()

功能

销毁按钮及其资源。

参数

无

返回值

无

示例

local btn = airui.button({ 
    x = 20, 
    y = 80, 
    text = "点我", 
    on_click = function() 
        log.info("btn", "tap") 
    end 
})

btn:destroy()

4.2.9 下拉框（airui.dropdown）

4.2.9.1 airui.dropdown(config)

功能

实现可滚动选择列表，支持 change 回调。

参数

config

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

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

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

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

    参数含义：选项数组
    数据类型：table
    取值范围：字符串数组
    是否必选：是
    注意事项：无
    参数示例：{"A","B"}
    options = {"A","B"},

    参数含义：默认选中项索引
    数据类型：number
    取值范围：0到选项数量-1
    是否必选：可选
    注意事项：默认0
    参数示例：0
    default_index = 0,

    参数含义：状态变化回调函数  -- V1.1.3 更新value参数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：选中项变化时触发
    参数示例：function(self,idx, value) log.info("当前选项", idx, "选项对应内", value) end
    on_change = function(self,idx, value) log.info("当前选项", idx, "选项对应内", value) end,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local dropdown_object = airui.dropdown(config)

dropdown_object

含义说明：下拉框组件对象
数据类型：userdata
取值范围：包含 set_selected、get_selected、get_value、set_on_change、set_options、is_destroyed、destroy 等方法的下拉框对象
注意事项：需要添加到界面中才能显示
返回示例：dropdown_object

示例

-- 创建下拉框
local dd = airui.dropdown({ 
    options = {"A","B"}, 
    default_index = 0, 
    on_change = function(self,idx,value) 
        log.info("当前选项", idx, "选项对应内", value)
    end 
})
4.2.9.2 dropdown:set_selected(index)

功能

设置当前选中项。

参数

index

参数含义：目标索引
数据类型：number
是否必选：是
取值范围：0到选项数量-1
注意事项：0起始
参数示例：1
示例代码：index = 1

返回值

无

示例

-- 创建下拉框
local dd = airui.dropdown({ 
    options = {"A","B"}, 
    default_index = 0, 
    on_change = function(self,idx) 
        log.info("pick", "选择了：" .. idx) 
    end 
})

-- 选择第2个选项
dd:set_selected(1)
4.2.9.3 dropdown:get_selected()

功能

获取当前选中项。

参数

无

返回值

local selected_index = dropdown:get_selected()

selected_index

含义说明：当前选中项索引
数据类型：number
取值范围：0到选项数量-1
注意事项：0起始
返回示例：1

示例

-- 创建下拉框
local dd = airui.dropdown({ 
    options = {"A","B"}, 
    default_index = 0, 
    on_change = function(self,idx) 
        log.info("pick", "选择了：" .. idx) 
    end 
})

-- 获取当前选中项
local idx = dd:get_selected()
log.info("dropdown", "当前选中：" .. idx)
4.2.9.4 dropdown:get_value()

功能

获取当前选中项的文本内容。

参数

无

返回值

local selected_value = dropdown:get_value()

selected_value

含义说明：当前选中项的文本
数据类型：string
注意事项：若未选中任何项则返回空字符串
返回示例："选项A"

示例

local dd = airui.dropdown({ options = {"A","B"}, default_index = 0 })
local val = dd:get_value()
log.info("dropdown", "当前选中文本：" .. val)
4.2.9.5 dropdown:set_on_change(callback)

功能

设置选中变动回调。

参数

callback

参数含义：回调函数
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：函数参数为选中项索引
参数示例：function(idx) log.info("dropdown", idx) end
示例代码：callback = function(idx) log.info("dropdown", idx) end

返回值

无

示例

-- 创建下拉框
local dd = airui.dropdown({ 
    options = {"A","B"}, 
    default_index = 0, 
    on_change = function(self,idx) 
        log.info("pick", "选择了：" .. idx) 
    end 
})

-- 设置选中变动回调
dd:set_on_change(function(idx) 
    log.info("dropdown", "选择了第" .. idx .. "项") 
end)
4.2.9.6 dropdown:set_options(config) -- V1.2.1 新增

功能

重新设置下拉框的选项内容和默认选中项。

参数

config

参数含义：选项配置表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
{
    参数含义：选项字符串数组
    数据类型：table
    是否必选：是
    注意事项：无
    参数示例：{"选项A", "选项B", "选项C"}
    options = {"选项A", "选项B", "选项C"},

    参数含义：默认选中项索引
    数据类型：number
    取值范围：0到选项数量-1
    是否必选：可选
    注意事项：默认0
    参数示例：1
    default_index = 1,
}

返回值

无

示例

local dd = airui.dropdown({
    options = {"A", "B"},
    default_index = 0,
})

-- 重新设置选项
dd:set_options({
    options = {"选项X", "选项Y", "选项Z"},
    default_index = 1,
})
4.2.9.7 dropdown:is_destroyed() -- V1.2.1 新增

功能

检查下拉框组件是否已被销毁。

参数

无

返回值

local destroyed = dropdown:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local dd = airui.dropdown({
    options = {"A", "B"},
})

if not dd:is_destroyed() then
    log.info("dropdown", "still alive")
end
4.2.9.8 dropdown:destroy()

功能

销毁下拉框组件。

参数

无

返回值

无

示例

-- 创建下拉框
local dd = airui.dropdown({ 
    options = {"A","B"}, 
    default_index = 0, 
    on_change = function(self,idx) 
        log.info("pick", "选择了：" .. idx) 
    end 
})

-- 销毁下拉框
dd:destroy()

4.2.10 消息框（airui.msgbox）

4.2.10.1 airui.msgbox(config)

功能

创建可定时关闭的模态消息框，可动态 show/hide。

参数

config

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

    参数含义：消息框左上角Y坐标 -- V1.2.1 更新
    数据类型：number
    取值范围：0到屏幕高度
    是否必选：可选
    注意事项：默认自动居中
    参数示例：20
    y = 20,

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

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

    参数含义：是否自动居中 -- V1.2.1 更新
    数据类型：boolean
    取值范围：true（自动居中）、false（使用指定坐标）
    是否必选：可选
    注意事项：默认 true。若设为 false 且未设置 x/y，则默认左上角 (0,0)
    参数示例：false
    auto_center = false,

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

    参数含义：消息框正文
    数据类型：string
    取值范围：任意字符串
    是否必选：可选
    注意事项：默认空字符串
    参数示例："完成"
    text = "完成",

    参数含义：按钮列表
    数据类型：table
    取值范围：字符串数组
    是否必选：可选
    注意事项：默认{"OK"}
    参数示例：{"确定","取消"}
    buttons = {"确定","取消"},

    参数含义：自动关闭时长
    数据类型：number
    取值范围：大于等于0的整数（毫秒）
    是否必选：可选
    注意事项：0表示不自动关闭
    参数示例：3000
    timeout = 3000,

    参数含义：按钮回调函数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：点击按钮时触发，参数为按钮标签
    参数示例：function(label) log.info("msgbox", label) end
    on_action = function(label) log.info("msgbox", label) end,

    参数含义：样式配置表 -- V1.2.1 更新
    数据类型：table
    取值范围：包含以下子参数：
    {
        参数含义：背景色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        参数示例：0xffffff
        bg_color = ,

        参数含义：背景透明度
        数据类型：number
        取值范围：0~255
        是否必选：可选
        参数示例：255
        bg_opa = ,

        参数含义：边框颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        参数示例：0xcccccc
        border_color = ,

        参数含义：边框宽度
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        参数示例：1
        border_width = ,

        参数含义：圆角半径
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        参数示例：10
        radius = ,

        参数含义：文本字号 -- V1.2.1 更新
        数据类型：number
        取值范围：大于0的整数
        是否必选：可选
        注意事项：仅在 hzfont 启用时生效
        参数示例：18
        text_font_size = 18,
    }
    参数示例：style = { bg_color = 0xffffff, text_font_size = 18 }
    style = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local msgbox_object = airui.msgbox(config)

msgbox_object

含义说明：消息框组件对象
数据类型：userdata
取值范围：包含 show、hide、set_style、set_on_action、is_destroyed、destroy 等方法的消息框对象
注意事项：创建后需要调用show()方法显示
返回示例：msgbox_object

示例

-- 创建消息框
local box = airui.msgbox({
    title = "通知",
    text = "2026年你会发财！",
    buttons = { "确定" },
    on_action = function(self, label)
        if label == "确定" then
            self:hide()
        end
    end
})
4.2.10.2 msgbox:show()

功能

显示消息框。

参数

无

返回值

无

示例

-- 创建消息框
local box = airui.msgbox({ 
    text = "操作完成", 
    buttons = {"OK"} 
})

-- 显示消息框
box:show()
4.2.10.3 msgbox:hide()

功能

隐藏消息框。

参数

无

返回值

无

示例

-- 创建消息框
local box = airui.msgbox({ 
    text = "操作完成", 
    buttons = {"OK"} 
})

-- 隐藏消息框
box:hide()
4.2.10.4 msgbox:set_on_action(callback)

功能

设置按钮回调。

参数

callback

参数含义：回调函数
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：函数参数为按钮标签
参数示例：function(label) log.info("msgbox", label) end
示例代码：callback = function(label) log.info("msgbox", label) end

返回值

无

示例

-- 创建消息框
local box = airui.msgbox({ 
    text = "操作完成", 
    buttons = {"OK"} 
})

-- 设置按钮回调
box:set_on_action(function(label) 
    log.info("msgbox", "点击了按钮：" .. label) 
end)
4.2.10.5 msgbox:is_destroyed() -- V1.2.1 新增

功能

检查消息框组件是否已被销毁。

参数

无

返回值

local destroyed = msgbox:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local box = airui.msgbox({
    text = "Hello",
    buttons = {"OK"},
})

if not box:is_destroyed() then
    log.info("msgbox", "still alive")
end
4.2.10.6 msgbox:destroy()

功能

释放消息框资源。

参数

无

返回值

无

示例

-- 创建消息框
local box = airui.msgbox({ 
    text = "操作完成", 
    buttons = {"OK"} 
})

-- 释放消息框资源
box:destroy()

4.2.11 键盘（airui.keyboard）

4.2.11.1 airui.keyboard(config)

功能

虚拟键盘，支持多模式与自动隐藏、绑定目标 textarea。

参数

config

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

    参数含义：键盘左下角Y坐标
    数据类型：number
    取值范围：负屏幕高度到0，0为键盘左下角靠近屏幕底部，-10为键盘左下角距离屏幕距离为10
    是否必选：可选
    注意事项：默认贴屏幕底部
    参数示例：屏幕高度-键盘高度
    y = 0,

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

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

    参数含义：键盘模式
    数据类型：string
    取值范围：
            - "text" - 文本模式
            - "upper" - 大写字母模式
            - "lower" - 小写字母模式
            - "numeric" - 数字模式
            - "pinyin_26" - 拼音26键模式
            - "pinyin_9" - 拼音9宫格模式
            - "pinyin_9_number" - 拼音9宫格数字模式
    是否必选：可选
    注意事项：默认"text"
    参数示例："pinyin_26"
    mode = "pinyin_26",

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

    参数含义：是否失焦自动隐藏
    数据类型：boolean
    取值范围：true（自动隐藏）, false（不自动隐藏）
    是否必选：可选
    注意事项：默认 true
    参数示例：true
    auto_hide = true,

    参数含义：关联的textarea，推荐使用输入框关联键盘方式
    数据类型：userdata
    取值范围：有效的文本输入框对象
    是否必选：可选
    注意事项：创建时可指定，也可后续通过set_target设置
    参数示例：ta_object
    target = ta_object,

    参数含义：是否启用输入预览 -- V1.1.0 更新
    数据类型：boolean
    取值范围：true（显示预览）, false（不显示预览）
    是否必选：可选
    注意事项：默认 false。启用后，在键盘上方会显示当前输入内容的预览区域
    参数示例：true
    preview = true,

    参数含义：预览区域高度 -- V1.1.0 更新
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认 40，仅当 preview = true 时生效
    参数示例：40
    preview_height = 40,

    参数含义：背景颜色 -- V1.0.1更新
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：不设置则透明
    参数示例：0x666666
    bg_color = 0x666666,

    参数含义：键盘提交回调函数 -- V1.1.0 更新
    数据类型：function
    是否必选：可选
    注意事项：当键盘执行提交操作（右下角确认键）时触发，回调函数参数为无（或者可带参数，但示例中是无参）。可以通过 keyboard:get_target() 获取当前绑定的输入框。
    参数示例：function() log.info("keyboard", "commit") end
    on_commit = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,

}

返回值

local keyboard_object = airui.keyboard(config)

keyboard_object

含义说明：键盘组件对象
数据类型：userdata
取值范围：包含 set_target、show、hide、set_on_commit、is_destroyed、destroy 等方法的键盘对象
注意事项：需要添加到界面中才能显示
返回示例：keyboard_object

示例

-- 创建键盘
local kb= airui.keyboard({
    x = 0,
    y = -20,  -- 底部留20像素边距
    w = 800,
    h = 250,
    mode = "text",
    auto_hide = true,
})
4.2.11.2 keyboard:set_target(textarea)

功能

指定关联的 textarea。

参数

textarea

参数含义：文本输入框对象
数据类型：userdata
是否必选：是
取值范围：有效的文本输入框对象
注意事项：无
参数示例：ta_object
示例代码：textarea = ta_object

返回值

无

示例

-- 创建键盘
local kb= airui.keyboard({
    x = 0,
    y = -20,  -- 底部留20像素边距
    w = 800,
    h = 250,
    mode = "text",
    auto_hide = true,
})

-- 创建输入框并关联键盘
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
    keyboard = kb
})
4.2.11.3 keyboard:show()

功能

显示键盘。

参数

无

返回值

无

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 显示键盘
kb:show()
4.2.11.4 keyboard:hide()

功能

隐藏键盘。

参数

无

返回值

无

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 隐藏键盘
kb:hide()
4.2.11.5 keyboard:set_on_commit(fn)

功能

设置键盘提交回调。

参数

fn

参数含义：回调函数
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：提交时触发
参数示例：function(txt) log.info("commit", txt) end
示例代码：fn = function(txt) log.info("commit", txt) end

返回值

无

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 设置键盘提交回调
kb:set_on_commit(function(txt) 
    log.info("keyboard", "提交内容：" .. txt) 
end)
4.2.11.6 keyboard:set_layout(name)

功能

更换键盘布局。

参数

name

参数含义：布局名称
数据类型：string
是否必选：是
取值范围：
- `"text"` - 文本布局
- `"upper"` - 大写字母布局
- `"lower"` - 小写字母布局
- `"numeric"` - 数字布局
- `"pinyin_26"` - 拼音26键布局
- `"pinyin_9"` - 拼音9宫格布局
- `"pinyin_9_number"` - 拼音9宫格数字布局
注意事项：无
参数示例："pinyin_26"
示例代码：name = "pinyin_26"

返回值

无

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 切换到大写字母布局
kb:set_layout("upper")

-- 切换到拼音26键布局
kb:set_layout("pinyin_26")
4.2.11.7 keyboard:set_bg_color(color) -- V1.0.1 更新

功能

设置背景颜色

参数

color

参数含义：背景颜色
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：_0xff0000_
示例代码：color = _0xff0000_

返回值

无

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 切换到大写字母布局
kb:_set_bg_color_(_0xff0000_)
4.2.11.8 keyboard:get_target()

功能

返回当前绑定的 textarea，推荐使用输入框关联键盘的方式。

参数

无

返回值

local target_object = keyboard:get_target()

target_object

含义说明：当前绑定的文本输入框对象
数据类型：userdata
取值范围：有效的文本输入框对象或nil
注意事项：如果未绑定返回nil
返回示例：ta_object

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 将输入框关联键盘
ta:attach_keyboard(kb) 

-- 返回当前绑定的 textarea，推荐使用输入框关联键盘的方式
local target = kb:get_target()
if target then
    log.info("keyboard", "已绑定到输入框")
end
4.2.11.9 keyboard:destroy()

功能

销毁键盘组件。

参数

无

返回值

无

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 销毁键盘
kb:destroy()

4.2.12 文本输入（airui.textarea）

4.2.12.1 airui.textarea(config)

功能

创建文本输入框，输入框支持占位、自动绑定键盘和监听文本变化。

参数

config

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

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

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

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

    参数含义：最大字符数
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认256
    参数示例：100
    max_len = 100,

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

    参数含义：占位提示
    数据类型：string
    取值范围：任意字符串
    是否必选：可选
    注意事项：默认空字符串
    参数示例："请输入"
    placeholder = "请输入",

    参数含义：键盘配置
    数据类型：table
    取值范围：键盘配置表
    是否必选：可选
    注意事项：可选，内嵌 keyboard 配置
    参数示例：{ x = 0, y = -20, w = 800, h = 250, mode = "text", auto_hide = true }
    keyboard = { x = 0, y = -20, w = 800, h = 250, mode = "text", auto_hide = true },

    参数含义：文本变化回调函数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：文本内容变化时触发
    参数示例：function(txt) log.info("text", txt) end
    on_text_change = function(txt) log.info("text", txt) end,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local textarea_object = airui.textarea(config)

textarea_object

含义说明：文本输入框组件对象
数据类型：userdata
取值范围：包含 set_text、get_text、set_cursor、attach_keyboard、is_destroyed、destroy 等方法的对象
注意事项：需要添加到界面中才能显示
返回示例：textarea_object

示例

-- 创建键盘
local kb= airui.keyboard({
    x = 0,
    y = -20,  -- 底部留20像素边距
    w = 800,
    h = 250,
    mode = "text",
    auto_hide = true,
})

-- 创建输入框并关联键盘
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
    keyboard = kb
})
4.2.12.2 textarea:set_text(text)

功能

设置输入框文本内容。

参数

text

参数含义：目标文本
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：受max_len限制
参数示例："abc"
示例代码：text = "abc"

返回值

无

示例

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 设置输入框文本内容
ta:set_text("默认文本")
4.2.12.3 textarea:get_text()

功能

获取输入框当前内容。

参数

无

返回值

local text_content = textarea:get_text()

text_content

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 获取输入框当前内容
local txt = ta:get_text()
log.info("textarea", "当前内容：" .. txt)
4.2.12.4 textarea:set_cursor(pos)

功能

调整光标位置。

参数

pos

参数含义：光标位置
数据类型：number
是否必选：是
取值范围：0到文本长度
注意事项：0起始
参数示例：2
示例代码：pos = 2

返回值

无

示例

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 将光标移动到第3个字符后
ta:set_cursor(2)
4.2.12.5 textarea:set_on_text_change(fn)

功能

设置输入框内容变化回调。

参数

fn

参数含义：回调函数
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：函数参数为文本内容
参数示例：function(txt) log.info("text", txt) end
示例代码：fn = function(txt) log.info("text", txt) end

返回值

无

示例

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 设置输入框内容变化回调
ta:set_on_text_change(function(txt) 
    log.info("textarea", "内容变化：" .. txt) 
end)
4.2.12.6 textarea:attach_keyboard(keyboard)

功能

将输入框关联键盘。

参数

keyboard

参数含义：键盘对象
数据类型：userdata
是否必选：是
取值范围：有效的键盘对象
注意事项：键盘必须通过airui.keyboard创建
参数示例：kb_object
示例代码：keyboard = kb_object

返回值

无

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 将输入框关联键盘
ta:attach_keyboard(kb)
4.2.12.7 textarea:get_keyboard()

功能

获取输入框绑定键盘。

参数

无

返回值

local keyboard_object = textarea:get_keyboard()

keyboard_object

含义说明：绑定的键盘对象
数据类型：userdata
取值范围：有效的键盘对象或nil
注意事项：如果未绑定键盘返回nil
返回示例：kb_object

示例

-- 创建键盘
local kb = airui.keyboard({ mode = "text" })

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 将输入框关联键盘
ta:attach_keyboard(kb) 

local kb = ta:get_keyboard()
if kb then
    log.info("textarea", "已绑定键盘")
end
4.2.12.8 textarea:destroy()

功能

销毁输入框。

参数

无

返回值

无

示例

-- 创建输入框
local ta = airui.textarea({ 
    x = 20, y = 420, 
    placeholder = "请输入" 
})

-- 销毁输入框
ta:destroy()

4.2.13 容器（airui.container）

4.2.13.1 airui.container(config)

功能

用于多页面制作，支持颜色、显示控制与 open。

参数

config

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

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

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

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

    参数含义：背景色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x000000
    参数示例：0xff0000
    color = 0xff0000,

    参数含义：设置容器背景色透明度  -- V 1.0.3更新
    数据类型：number
    取值范围：0~255，_0为完全透明，255为完全不透明_
    是否必选：可选
    注意事项：默认值为255不透明
    参数示例：255
    color_opacity = 255

    参数含义：圆角半径
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：默认为 0  
    参数示例：10
    radius = 10,

    参数含义：点击回调函数 -- V1.1.0 更新
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：点击容器区域时触发，容器内子组件不设置on_click参数才能更准确触发
    参数示例：on_click = function(self) log.info("container_click", "click") end
    on_click = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local container_object = airui.container(config)

container_object

含义说明：容器组件对象
数据类型：userdata
取值范围：包含 set_color、set_hidden、hide、open、move、get_pos、set_pos、is_destroyed、destroy 等方法的容器对象
注意事项：需要添加到界面中才能显示
返回示例：container_object

示例

-- 创建容器
local box = airui.container({ 
    x = 10, y = 10, w = 300, h = 200, 
    color = 0xff0000, 
    on_click = function(self)
        log.info("container_click", "click")
    end,
})
4.2.13.2 container:set_color(color)

功能

设置容器背景色。

参数

color

参数含义：背景颜色
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：0x00ff00
示例代码：color = 0x00ff00

返回值

无

示例

-- 创建容器
local box = airui.container({ 
    x = 10, y = 10, w = 300, h = 200, 
    color = 0xff0000 
})
-- 设置为绿色
box:set_color(0x00ff00)
4.2.13.3 container:set_hidden(hidden)

功能

控制可见性，可以设置为可见或者不可见，与 hide/open 形成互补。

参数

hidden

参数含义：隐藏状态
数据类型：boolean
是否必选：是
取值范围：true（隐藏）, false（显示）
注意事项：无
参数示例：true
示例代码：hidden = true

返回值

无

示例

-- 创建容器
local box = airui.container({ 
    x = 10, y = 10, w = 300, h = 200, 
    color = 0xff0000 
})

-- 控制可见性为隐藏
box:set_hidden(true)
4.2.13.4 container:hide()

功能

隐藏容器。

参数

无

返回值

无

示例

-- 创建容器
local box = airui.container({ 
    x = 10, y = 10, w = 300, h = 200, 
    color = 0xff0000 
})

-- 隐藏容器
box:hide()
4.2.13.5 container:open()

功能

显示容器（若之前隐藏）。

参数

无

返回值

无

示例

-- 创建容器
local box = airui.container({ 
    x = 10, y = 10, w = 300, h = 200, 
    color = 0xff0000 
})

-- 先隐藏容器
box:hide()

-- 显示容器
box:open()
4.2.13.6 container:move(dx, dy) -- V1.1.5 新增

功能

移动容器相对当前位置偏移指定像素距离。

参数

dx

参数含义：X轴偏移量，正数向右，负数向左
数据类型：number
取值范围：整数
是否必选：是
注意事项：无
参数示例：10

dy

参数含义：Y轴偏移量，正数向下，负数向上
数据类型：number
取值范围：整数
是否必选：是
注意事项：无
参数示例：10

返回值

无

示例

local box = airui.container({
    x = 20, y = 80, w = 200, h = 100,
})

-- 向右移动10像素，向下移动20像素
box:move(10, 20)
4.2.13.7 container:get_pos() -- V1.2.1 新增

功能

获取容器当前的位置坐标。

参数

无

返回值

local x, y = container:get_pos()

x, y

含义说明：容器的当前坐标位置
数据类型：number, number
取值范围：x为X坐标，y为Y坐标
注意事项：返回两个值
返回示例：10, 10

示例

local box = airui.container({
    x = 10, y = 10, w = 300, h = 200,
})

local x, y = box:get_pos()
log.info("container", "position: " .. x .. ", " .. y)
4.2.13.8 container:set_pos(x, y) -- V1.2.1 新增

功能

设置容器的绝对位置。

参数

x

参数含义：X坐标
数据类型：number
是否必选：是
取值范围：0到屏幕宽度
参数示例：100

y

参数含义：Y坐标
数据类型：number
是否必选：是
取值范围：0到屏幕高度
参数示例：200

返回值

无

示例

local box = airui.container({
    x = 10, y = 10, w = 300, h = 200,
})

-- 设置新位置
box:set_pos(100, 200)
4.2.13.9 container:is_destroyed() -- V1.2.1 新增

功能

检查容器组件是否已被销毁。

参数

无

返回值

local destroyed = container:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local box = airui.container({
    x = 10, y = 10, w = 300, h = 200,
})

if not box:is_destroyed() then
    log.info("container", "still alive")
end
4.2.13.10 container:destroy()

功能

销毁容器及子组件。

参数

无

返回值

无

示例

-- 创建容器并添加子组件
local box = airui.container({ 
    x = 10, y = 10, w = 300, h = 200, 
    color = 0xff0000 
})

local btn = airui.button({
    parent = box,
    text = "按钮",
    x = 50, y = 50
})


-- 使用后销毁容器及其子组件
box:destroy()

4.2.14 选项卡（airui.tabview）

4.2.14.1 airui.tabview(config)

功能

创建多标签页选项卡，支持点击标签和滑动页面切换。

参数

config

参数含义：选项卡配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：

{
    参数含义：选项卡左上角X坐标
    数据类型：number
    取值范围：0到屏幕宽度
    是否必选：可选
    注意事项：默认0
    参数示例：10
    x = 10,

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

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

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

    参数含义：标签栏位置 -- 目前设置此参数无效，默认标签栏在顶部
    数据类型：number
    取值范围：airui方向常量
    是否必选：可选
    注意事项：默认 airui.DIR_TOP
    参数示例：airui.DIR_TOP
    tabbar_pos = airui.DIR_TOP,

    参数含义：默认激活页索引
    数据类型：number
    取值范围：0到标签数量-1
    是否必选：可选
    注意事项：默认0
    参数示例：0
    active = 0,

    参数含义：切页切换方式
    数据类型：string
    取值范围：
    - `"jump"` - 跳转切换，立即切换到目标页面，不带动画滑动
    - `"swipe"` - 滑动切换，带动画平滑滑动
    是否必选：可选
    注意事项：默认 `jump`
    参数示例："jump"
    switch_mode = "jump",

    参数含义：标签名数组
    数据类型：table
    取值范围：字符串数组
    是否必选：是
    注意事项：无
    参数示例：{"A","B"}
    tabs = {"A","B"},

    参数含义：页面样式配置表
    数据类型：table
    是否必选：可选
    注意事项：用于设置页面区域的样式，包含以下子参数
            {
                参数含义：标签栏高度
                数据类型：number
                取值范围：大于0的整数，单位像素
                是否必选：可选
                注意事项：不设置则使用默认高度
                参数示例：40
                tabbar_size = 40,

                参数含义：内边距配置表
                数据类型：table
                是否必选：可选
                注意事项：包含以下子参数：
                {
                    参数含义：内边距应用方式
                    数据类型：number
                    取值范围：airui.TABVIEW_PAD_ALL（所有边）、
                             airui.TABVIEW_PAD_HOR（左右）、
                             airui.TABVIEW_PAD_VER（上下）、
                             airui.TABVIEW_PAD_TOP（上边）、
                             airui.TABVIEW_PAD_BOTTOM（下边）、
                             airui.TABVIEW_PAD_LEFT（左边）、
                             airui.TABVIEW_PAD_RIGHT（右边）
                    是否必选：是（当 pad 存在时）
                    注意事项：无
                    参数示例：airui.TABVIEW_PAD_ALL
                    method = ,

                    参数含义：内边距数值
                    数据类型：number
                    取值范围：大于等于0的整数
                    是否必选：是（当 pad 存在时）
                    注意事项：单位像素
                    参数示例：0
                    value = ,
                }
                参数示例：{ method = airui.TABVIEW_PAD_ALL, value = 0 }
                pad = ,

                参数含义：页面区域背景透明度
                数据类型：number
                取值范围：0~255，0为完全透明，255为不透明
                是否必选：可选
                注意事项：无
                参数示例：0
                bg_opa = ,
            }
    参数示例：{ tabbar_size = 40, pad = { method = airui.TABVIEW_PAD_ALL, value = 0 }, bg_opa = 0 }
    page_style = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local tabview_object = airui.tabview(config)

tabview_object

含义说明：选项卡组件对象
数据类型：userdata
取值范围：包含 set_active、get_content、set_on_change、is_destroyed、destroy 等方法的选项卡对象
注意事项：需要添加到界面中才能显示
返回示例：tabview_object

示例

-- 创建选项卡
local tv = airui.tabview({ 
    tabs = {"A","B"} 
})
4.2.14.2 tabview:set_active(index)

功能

切换当前页。

参数

index

参数含义：目标页索引
数据类型：number
是否必选：是
取值范围：0到标签数量-1
注意事项：0起始
参数示例：0
示例代码：index = 0

返回值

无

示例

-- 创建选项卡
local tv = airui.tabview({ 
    tabs = {"A","B"} 
})
-- 切换到第1个标签页
tv:set_active(0)
4.2.14.3 tabview:get_content(index)

功能

获取指定页对象。

参数

index

参数含义：页索引
数据类型：number
是否必选：是
取值范围：0到标签数量-1
注意事项：0起始
参数示例：0
示例代码：index = 0

返回值

local page_object = tabview:get_content(index)

page_object

含义说明：页面对象
数据类型：userdata
取值范围：有效的容器对象或nil
注意事项：如果索引无效返回nil
返回示例：page_object

示例

-- 创建选项卡
local tv = airui.tabview({ 
    tabs = {"A","B"} 
})

-- 获取第1个标签页的内容
local page = tv:get_content(0)  
if page then
    -- 在页面中添加组件
    local btn = airui.button({
        parent = page,
        text = "页面按钮"
    })
end
4.2.14.4 tabview:set_on_change(callback)

功能

监听页变化。

参数

callback

参数含义：回调函数  V1.1.3 版本后实现index参数的获取
数据类型：function
是否必选：是
取值范围：有效的Lua函数
注意事项：函数参数为(tabview, index)
参数示例：function(self, index)  log.info("tab", "page changed to", index) end
示例代码：callback = function(self, index) log.info("tab", "page changed to", index) end

返回值

无

示例

-- 创建选项卡
local tv = airui.tabview({ 
    tabs = {"A","B"} 
})

-- 监听选项卡页变化
tv:set_on_change(function(self, index)
    log.info("tab", "page changed to", index)
end)
4.2.14.5 tabview:get_tab_count() -- V1.1.4 新增

功能

获取当前标签页数量。

参数

无

返回值

local count = tabview:get_tab_count()

count

含义说明：标签页数量
数据类型：number
取值范围：大于等于1的整数
注意事项：无
返回示例：3

示例

-- 创建选项卡
local tv = airui.tabview({
    tabs = {"A","B","C"}
})

-- 获取标签页数量
local count = tv:get_tab_count()
log.info("tabview", "tab count: " .. count)  -- 输出: tab count: 3
4.2.14.6 tabview:add_tab(title) -- V1.1.4 新增

功能

添加新的标签页。

参数

title

参数含义：标签页标题
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：无
参数示例："新页面"
示例代码：title = "新页面"

返回值

local page = tabview:add_tab(title)

page

含义说明：新标签页的容器对象
数据类型：userdata
取值范围：有效的容器对象
注意事项：可以在该容器中添加子组件
返回示例：page_object

示例

-- 创建选项卡
local tv = airui.tabview({
    tabs = {"A","B"}
})

-- 添加新标签页
local new_page = tv:add_tab("新页面")
if new_page then
    -- 在新页面中添加组件
    local label = airui.label({
        parent = new_page,
        text = "这是新添加的页面",
        x = 20, y = 20, w = 200, h = 30
    })
end
4.2.14.7 tabview:remove_tab(index) -- V1.1.4 新增

功能

移除指定索引的标签页。

参数

index

参数含义：标签页索引
数据类型：number
是否必选：是
取值范围：0到tab_count-1
注意事项：0起始
参数示例：1
示例代码：index = 1

返回值

无

示例

-- 创建选项卡
local tv = airui.tabview({
    tabs = {"A","B","C"}
})

-- 移除第1个标签页（B）
tv:remove_tab(1)
4.2.14.8 tabview:destroy()

功能

销毁组件。

参数

无

返回值

无

示例

-- 创建选项卡
local tv = airui.tabview({ 
    tabs = {"A","B"} 
})

-- 销毁选项卡
tv:destroy()

4.2.15 窗口（airui.win）

4.2.15.1 airui.win(config)

功能

创建带标题的浮动窗口，可注册关闭回调。

参数

config

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

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

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

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

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

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

    参数含义：是否自动居中
    数据类型：boolean
    取值范围：true（自动居中）, false（使用指定坐标）
    是否必选：可选
    注意事项：默认 true
    参数示例：false
    auto_center = false,

    参数含义：窗口完整样式配置表
    数据类型：table
    取值范围：包含以下子参数：
    {
        参数含义：窗口默认背景颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        参数示例：0xF7F1E8
        bg_color = ,

        参数含义：窗口默认背景透明度
        数据类型：number
        取值范围：0~255，0 为完全透明，255 为完全不透明
        是否必选：可选
        参数示例：255
        bg_opa = ,

        参数含义：窗口边框颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        参数示例：0x6E4C2B
        border_color = ,

        参数含义：窗口边框宽度
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        参数示例：3
        border_width = ,

        参数含义：窗口边框圆角半径
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        参数示例：18
        radius = ,

        参数含义：窗口整体内边距，影响内容与窗口边缘的距离
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        参数示例：10
        pad = ,

        参数含义：标题栏背景颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        参数示例：0xD8B98A
        header_bg_color = ,

        参数含义：标题栏背景透明度
        数据类型：number
        取值范围：0~255，0 为完全透明，255 为完全不透明
        是否必选：可选
        参数示例：255
        header_bg_opa = ,

        参数含义：标题栏内边距
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        参数示例：8
        header_pad = ,

        参数含义：标题栏高度
        数据类型：number
        取值范围：大于0的整数，单位像素
        是否必选：可选
        参数示例：54
        header_height = ,

        参数含义：标题文字对齐方式 -- V1.1.3 更新
        数据类型：number
        取值范围：airui.TEXT_ALIGN_LEFT / CENTER / RIGHT
        是否必选：可选
        注意事项：默认左对齐
        参数示例：airui.TEXT_ALIGN_CENTER
        title_align = ,

        参数含义：内容区域背景颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        参数示例：0xFFF9F0
        content_bg_color = ,

        参数含义：内容区域背景透明度
        数据类型：number
        取值范围：0~255，0 为完全透明，255 为完全不透明
        是否必选：可选
        参数示例：255
        content_bg_opa = ,

        参数含义：内容区域内边距
        数据类型：number
        取值范围：大于等于0的整数，单位像素
        是否必选：可选
        参数示例：14
        content_pad = ,

        参数含义：标题文字颜色
        数据类型：number
        取值范围：十六进制 RGB 颜色值
        是否必选：可选
        参数示例：0x3B2412
        title_text_color = ,

        参数含义：关闭按钮背景颜色
        数据：number
        取值：十六进制 RGB 颜色值
        是否必选：可选
        示例：0x8F4A32
        close_btn_bg_color = ,

        参数含义：关闭按钮背景透明度
        数据：number
        取值：0~255，0 为完全透明，255 为完全不透明
        是否必选：可选
        示例：255
        close_btn_bg_opa = ,

        参数含义：关闭按钮文字颜色
        数据：number
        取值：十六进制 RGB 颜色值
        是否必选：可选
        示例：0xFFF7ED
        close_btn_text_color = ,

        参数含义：关闭按钮圆角半径
        数据：number
        取值：大于等于0的整数，单位像素
        是否必选：可选
        示例：12
        close_btn_radius = ,
    }
    参数示例：
    style = {
        bg_color = 0xF7F1E8,
        bg_opa = 255,
        border_color = 0x6E4C2B,
        border_width = 3,
        radius = 18,
        pad = 10,
        header_bg_color = 0xD8B98A,
        header_bg_opa = 255,
        header_pad = 8,
        header_height = 54,
        content_bg_color = 0xFFF9F0,
        content_bg_opa = 255,
        content_pad = 14,
        title_text_color = 0x3B2412,
        close_btn_bg_color = 0x8F4A32,
        close_btn_bg_opa = 255,
        close_btn_text_color = 0xFFF7ED,
        close_btn_radius = 12,
    }
    style = ,

    参数含义：关闭回调函数
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：关闭窗口时触发
    参数示例：function(self) log.info("airui.win", "win:on_close called") end
    on_close = function(self) log.info("airui.win", "win:on_close called") end,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local win_object = airui.win(config)

win_object

含义说明：窗口组件对象
数据类型：userdata
取值范围：包含 set_title、get_title、add_content、close、is_destroyed、destroy 等方法的窗口对象
注意事项：需要添加到界面中才能显示
返回示例：win_object

示例

-- 创建带标题居中的窗口
local win = airui.win({
    parent = airui.screen,
    title = "居中标题",
    x = 70, y = 50, w = 660, h = 460,
    close_btn = true,
    -- style参数中包含win组件窗口颜色，透明度等更多样式设置
    style = {
        title_text_color = 0x3B2412,
        title_align = airui.TEXT_ALIGN_CENTER,
    },
    on_close = function()
        log.info("airui.win", "closed")
    end
})
4.2.15.2 win:set_title(title)

功能

更新窗口标题。

参数

title

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

返回值

无

示例

-- 创建窗口组件
local win = airui.win({
    parent = airui.screen,
    title = "Settings",    -- 标题文本，可选
    x = 40, y = 40, w = 600, h = 400,  -- x, y, w, h
    close_btn = false,     -- 是否显示关闭按钮，默认 false
    auto_center = false,   -- 是否自动居中，默认 true
    on_close = function(self)  -- 关闭回调，目前on_close无效，V1.0.4更新此参数
        log.info("airui.win", "win:on_close called")
    end
})

-- 更新窗口标题
win:set_title("新标题")
4.2.15.3 win:get_title() -- V1.2.1 新增

功能

获取窗口当前标题文本。

参数

无

返回值

local title = win:get_title()

title

含义说明：窗口标题文本内容
数据类型：string
注意事项：如果窗口未设置标题，返回空字符串
返回示例："Settings"

示例

local win = airui.win({
    title = "Settings",
    x = 40, y = 40, w = 600, h = 400,
})

local title = win:get_title()
log.info("win", "title: " .. title)
4.2.15.4 win:add_content(child)

功能

将子组件添加到窗口内容区域。

参数

child

参数含义：子组件对象
数据类型：userdata
是否必选：是
取值范围：有效的组件对象
注意事项：组件必须通过airui.button、airui.label等构造函数创建
参数示例：button_object
示例代码：child = btn_object

返回值

无

示例

-- 创建窗口组件
local win = airui.win({
    parent = airui.screen,
    title = "Settings",    -- 标题文本，可选
    x = 40, y = 40, w = 600, h = 400,  -- x, y, w, h
    close_btn = false,     -- 是否显示关闭按钮，默认 false
    auto_center = false,   -- 是否自动居中，默认 true
    on_close = function(self)  -- 关闭回调，目前on_close无效，V1.0.4更新此参数
        log.info("airui.win", "win:on_close called")
    end
})

-- 创建按钮
local btn = airui.button({
    text = "窗口内按钮"
})

-- 将按钮添加到窗口
win:add_content(btn)
4.2.15.5 win:close()

功能

关闭窗口，触发 on_close 回调。

参数

无

返回值

无

示例

-- 创建窗口组件
local win = airui.win({
    parent = airui.screen,
    title = "Settings",    -- 标题文本，可选
    x = 40, y = 40, w = 600, h = 400,  -- x, y, w, h
    close_btn = false,     -- 是否显示关闭按钮，默认 false
    auto_center = false,   -- 是否自动居中，默认 true
    on_close = function(self)  -- 关闭回调，目前on_close无效，V1.0.4更新此参数
        log.info("airui.win", "win:on_close called")
    end
})

-- 关闭窗口
win:close()
4.2.15.6 win:is_destroyed() -- V1.2.1 新增

功能

检查窗口组件是否已被销毁。

参数

无

返回值

local destroyed = win:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local win = airui.win({
    title = "Settings",
})

if not win:is_destroyed() then
    log.info("win", "still alive")
end
4.2.15.7 win:destroy()

功能

销毁窗口。

参数

无

返回值

无

示例

-- 创建窗口组件
local win = airui.win({
    parent = airui.screen,
    title = "Settings",
    x = 40, y = 40, w = 600, h = 400,
    close_btn = false,
    auto_center = false,
    on_close = function(self)
        log.info("airui.win", "win:on_close called")
    end
})

-- 销毁窗口
win:destroy()

4.2.16 图表（airui.chart） -- V1.1.0 新增

4.2.16.1 airui.chart(config)

功能

创建数据曲线图组件，支持折线图、柱状图、堆叠柱状图，支持多系列、坐标轴自定义、动态数据推流。

参数

config

参数含义：曲线图配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：

{
    参数含义：图表左上角X坐标
    数据类型：number
    取值范围：0到屏幕宽度
    是否必选：可选
    注意事项：默认0
    参数示例：50
    x = 50,

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

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

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

    参数含义：图表类型
    数据类型：string
    取值范围："line"（折线图）、"bar"（柱状图）、"stacked"（堆叠柱状图）
    是否必选：可选
    注意事项：默认 "line"
    参数示例："bar"
    type = "bar",

    参数含义：Y轴最小值
    数据类型：number
    取值范围：任意整数
    是否必选：可选
    注意事项：默认0
    参数示例：0
    y_min = 0,

    参数含义：Y轴最大值
    数据类型：number
    取值范围：大于y_min的整数
    是否必选：可选
    注意事项：默认100
    参数示例：100
    y_max = 100,

    参数含义：数据点总数（每个系列的点数）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认120
    参数示例：120
    point_count = 120,

    参数含义：更新模式
    数据类型：string
    取值范围："shift"（滚动更新，新数据替换最早数据）、"circular"（环形更新，覆盖最旧数据）
    是否必选：可选
    注意事项：默认"shift"
    参数示例："shift"
    update_mode = "shift",

    参数含义：默认系列的颜色（第一个系列）
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x00b4ff
    参数示例：0x00b4ff
    line_color = 0x00b4ff,

    参数含义：曲线线宽（折线图有效）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认2
    参数示例：2
    line_width = 2,

    参数含义：数据点半径（折线图有效）
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：默认0（不显示点）
    参数示例：2
    point_radius = 2,

    参数含义：水平网格线数量（除轴线外）
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：默认6
    参数示例：6
    hdiv = 6,

    参数含义：垂直网格线数量（除轴线外）
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：默认6
    参数示例：6
    vdiv = 6,

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

    参数含义：X轴配置
    数据类型：table
    是否必选：可选
    注意事项：包含以下子参数：
        enable：是否显示轴线，默认 true
        min：最小值，默认 0
        max：最大值，默认 point_count
        ticks：刻度数量，默认 6
        unit：单位标签，默认 ""
    参数示例：{ enable = true, min = 1, max = 12, ticks = 7, unit = "s" }
    x_axis = { enable = true, min = 1, max = 12, ticks = 7, unit = "s" },

    参数含义：Y轴配置
    数据类型：table
    是否必选：可选
    注意事项：包含以下子参数：
        enable：是否显示轴线，默认 true
        min：最小值，默认 y_min
        max：最大值，默认 y_max
        ticks：刻度数量，默认 6
        unit：单位标签，默认 ""
    参数示例：{ enable = true, min = 0, max = 220, ticks = 6, unit = "k" }
    y_axis = { enable = true, min = 0, max = 220, ticks = 6, unit = "k" },

    参数含义：柱状图组间距（同一组内不同系列柱体之间的距离）
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：仅 type="bar" 或 "stacked" 时有效，默认 10
    参数示例：10
    bar_group_gap = 10,

    参数含义：柱状图系列间距（同一组内不同系列柱体之间的距离，堆叠图忽略）
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：仅 type="bar" 时有效，默认 5
    参数示例：5
    bar_series_gap = 5,

    参数含义：柱状图圆角半径
    数据类型：number
    取值范围：大于等于0的整数
    是否必选：可选
    注意事项：仅 type="bar" 或 "stacked" 时有效，默认 4
    参数示例：4
    bar_radius = 4,

    参数含义：点击曲线上点时触发的回调（折线图有效）
    数据类型：function
    是否必选：可选
    注意事项：回调参数为 self，可通过 self:get_pressed_point() 获取被点击的点索引
    参数示例：on_point = function(self) 
                log.info("chart", "pressed index", self:get_pressed_point())
             end
    on_point = function(self) 
        log.info("chart", "pressed index", self:get_pressed_point())
    end,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local chart_object = airui.chart(config)

chart_object

含义说明：曲线图组件对象
数据类型：userdata
取值范围：包含 set_type、add_series、remove_series、set_x_axis、set_y_axis、add_data、clear_data、set_bar_gap、set_bar_radius、is_destroyed、destroy 等方法的曲线图对象
注意事项：需要添加到界面中才能显示
返回示例：chart_object

示例

-- 创建多系列折线图
local chart = airui.chart({
    x = 50, y = 90, w = 700, h = 380,
    y_min = 0, y_max = 100,
    point_count = 120,
    update_mode = "shift",
    line_color = 0x00b4ff,
    line_width = 2,
    hdiv = 6,
    vdiv = 6,
    legend = true,
    x_axis = { enable = true, min = 0, max = 100, ticks = 6, unit = "s" },
    y_axis = { enable = true, min = 0, max = 100, ticks = 6, unit = "%" }
})

-- 添加额外系列
local sid2 = chart:add_series({color = 0xff6b35, name = "avg"})
local sid3 = chart:add_series({color = 0x22c55e, name = "diff"})
chart:set_series_name(1, "raw")

-- 设置初始值，目前只能设置整数，小数会不显示
chart:set_values(1, {50, 52, 54, 56, 58, 60})
chart:set_values(sid2, {50, 51, 52, 53, 54, 55})
chart:set_values(sid3, {0, 1, 2, 3, 4, 5})
4.2.16.2 chart:add_series(config)

功能

向图表添加一个新的数据系列。

参数

config

参数含义：系列配置表
数据类型：table
是否必选：是
取值范围：包含以下子参数：

{
    参数含义：系列颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：是
    注意事项：无
    参数示例：0xff0000
    color = ,

    参数含义：系列名称（用于图例）
    数据类型：string
    取值范围：任意字符串
    是否必选：可选
    注意事项：无
    参数示例："新系列"
    name = ,
}

返回值

local series_id = chart:add_series(config)

series_id

含义说明：新系列的标识符
数据类型：number
注意事项：set_values、push、set_line_color 等方法需要传入此ID
返回示例：2

示例

local sid = chart:add_series({color = 0xff0000, name = "新系列"})
4.2.16.3 chart:remove_series(series_id)

功能

移除指定的数据系列。

参数

series_id

参数含义：系列标识符
数据类型：number
是否必选：是
取值范围：由 add_series 返回的有效ID
注意事项：无
参数示例：2

返回值

无

示例

chart:remove_series(sid)
4.2.16.4 chart:set_series_name(series_id, name)

功能

设置系列的显示名称（用于图例）。

参数

series_id

参数含义：系列标识符
数据类型：number
是否必选：是
取值范围：由 add_series 返回的有效ID
注意事项：无
参数示例：1

name

参数含义：系列名称
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：无
参数示例："raw"

返回值

无

示例

chart:set_series_name(1, "实际值")
4.2.16.5 chart:set_values(series_id, values)

功能

一次设置指定系列的多个数据点（通常用于初始化或批量更新）。

参数

series_id

参数含义：系列标识符
数据类型：number
是否必选：是
取值范围：有效的系列ID
注意事项：无
参数示例：1

values

参数含义：数值数组
数据类型：table
是否必选：是
取值范围：整数组成的数组，长度应小于等于 point_count
注意事项：超出部分会被截断，不足部分补0
参数示例：{10, 20, 30}

返回值

无

示例

chart:set_values(1, {50, 52, 54, 56, 58, 60})
4.2.16.6 chart:push(series_id, value)

功能

向指定系列追加一个新数据点，根据当前 update_mode 自动滚动或环形覆盖。

参数

series_id

参数含义：系列标识符
数据类型：number
是否必选：是
取值范围：有效的系列ID
注意事项：无
参数示例：1

value

参数含义：新数据点的数值
数据类型：number
是否必选：是
取值范围：任意整数，但建议在 y_min 到 y_max 之间，否则可能超出显示范围
注意事项：无
参数示例：65

返回值

无

示例

chart:push(1, 65.5)
4.2.16.7 chart:set_update_mode(mode)

功能

切换图表的更新模式（影响所有系列）。

参数

mode

参数含义：更新模式
数据类型：string
是否必选：是
取值范围："shift" 或 "circular"
注意事项：无
参数示例："circular"

返回值

无

示例

chart:set_update_mode("circular")
4.2.16.8 chart:clear(value)

功能

清除所有系列的所有数据点，并设置所有点为指定值（通常用于复位）。

参数

value

参数含义：用于填充所有数据点的数值
数据类型：number
是否必选：是
取值范围：任意数值
注意事项：无
参数示例：50

返回值

无

示例

chart:clear(50)
4.2.16.9 chart:set_line_color(series_id, color)

功能

设置指定系列的线条/柱体颜色。

参数

series_id

参数含义：系列标识符
数据类型：number
是否必选：是
取值范围：有效的系列ID
注意事项：无
参数示例：1

color

参数含义：颜色值
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：0xff0000

返回值

无

示例

chart:set_line_color(1, 0xff0000)
4.2.16.10 chart:set_x_axis(config)

功能

设置 X 轴参数。

参数

config

参数含义：X轴配置表
数据类型：table
是否必选：是
取值范围：包含以下子参数（均为可选）：

{
    参数含义：是否显示轴线
    数据类型：boolean
    取值范围：true（显示）、false（不显示）
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：true
    enable = ,

    参数含义：最小值
    数据类型：number
    取值范围：任意整数
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：0
    min = ,

    参数含义：最大值
    数据类型：number
    取值范围：大于最小值的整数
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：24
    max = ,

    参数含义：刻度数量
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：7
    ticks = ,

    参数含义：单位标签
    数据类型：string
    取值范围：任意字符串
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例："s"
    unit = ,
}

返回值

无

示例

chart:set_x_axis({enable = true, min = 0, max = 24, ticks = 7, unit = "s"})
4.2.16.11 chart:set_y_axis(config)

功能

设置 Y 轴参数。

参数

config

参数含义：Y轴配置表
数据类型：table
是否必选：是
取值范围：包含以下子参数（均为可选）：

{
    参数含义：是否显示轴线
    数据类型：boolean
    取值范围：true（显示）、false（不显示）
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：true
    enable = ,

    参数含义：最小值
    数据类型：number
    取值范围：任意整数
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：-20
    min = ,

    参数含义：最大值
    数据类型：number
    取值范围：大于最小值的整数
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：120
    max = ,

    参数含义：刻度数量
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例：8
    ticks = ,

    参数含义：单位标签
    数据类型：string
    取值范围：任意字符串
    是否必选：可选
    注意事项：未设置则保持原值
    参数示例："%"
    unit = ,
}

返回值

无

示例

chart:set_y_axis({enable = true, min = -20, max = 120, ticks = 8, unit = "%"})
4.2.16.12 chart:set_bar_gap(group_gap, series_gap)

功能

设置柱状图的组间距和系列间距（仅 bar 类型有效）。

参数

group_gap

参数含义：组间距
数据类型：number
是否必选：是
取值范围：大于等于0的整数
注意事项：无
参数示例：10

series_gap

参数含义：系列间距（堆叠图忽略）
数据类型：number
是否必选：是
取值范围：大于等于0的整数
注意事项：无
参数示例：5

返回值

无

示例

chart:set_bar_gap(10, 5)
4.2.16.13 chart:set_bar_radius(radius)

功能

设置柱状图的圆角半径。

参数

radius

参数含义：圆角半径
数据类型：number
是否必选：是
取值范围：大于等于0的整数
注意事项：无
参数示例：4

返回值

无

示例

chart:set_bar_radius(4)
4.2.16.14 chart:get_pressed_point()

功能

获取当前触摸按下的点索引（通常在 on_point 回调中使用，仅折线图有效）。

参数

无

返回值

local index = chart:get_pressed_point()

index

含义说明：被按下点的索引
数据类型：number
取值范围：0 到 point_count-1，若没有按下则返回 -1
注意事项：仅在触摸事件中有效
返回示例：5

示例

-- 在 on_point 回调中获取被点击的点索引
local idx = chart:get_pressed_point()
log.info("chart", "pressed index", idx)
4.2.16.15 chart:destroy()

功能

销毁曲线图组件。

参数

无

返回值

无

示例

chart:destroy()

4.2.17 二维码（airui.qrcode）-- V1.1.0 新增

4.2.17.1 airui.qrcode(config)

功能

创建二维码组件，用于显示二维码。

参数

config

参数含义：二维码配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：

{
    参数含义：二维码左上角X坐标
    数据类型：number
    取值范围：0到屏幕宽度
    是否必选：可选
    注意事项：默认0
    参数示例：40
    x = 40,

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

    参数含义：二维码尺寸（宽度和高度，正方形）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认200
    参数示例：220
    size = 220,

    参数含义：二维码数据内容
    数据类型：string
    取值范围：任意字符串
    是否必选：是
    注意事项：无
    参数示例："https://docs.openluat.com/"
    data = "https://docs.openluat.com/",

    参数含义：深色模块颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认 0x000000
    参数示例：0x000000
    dark_color = 0x000000,

    参数含义：浅色模块颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认 0xFFFFFF
    参数示例：0xFFFFFF
    light_color = 0xFFFFFF,

    参数含义：是否添加静默区（四周留白）
    数据类型：boolean
    取值范围：true（添加）、false（不添加）
    是否必选：可选
    注意事项：默认 true
    参数示例：true
    quiet_zone = true,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local qrcode_object = airui.qrcode(config)

qrcode_object

含义说明：二维码组件对象
数据类型：userdata
取值范围：包含 set_data、set_size、set_colors、is_destroyed、destroy 等方法的二维码对象
注意事项：需要添加到界面中才能显示
返回示例：qrcode_object

示例

-- 创建二维码
local qrcode = airui.qrcode({
    x = 40,
    y = 40,
    size = 220,
    data = "https://docs.openluat.com/",
    dark_color = 0x000000,
    light_color = 0xFFFFFF,
    quiet_zone = true
})

if not qrcode then
    log.error("airui", "create qrcode failed")
    return
end
4.2.17.2 qrcode:set_data(data)

功能

更新二维码数据内容。

参数

data

参数含义：新的数据内容
数据类型：string
是否必选：是
取值范围：任意字符串
注意事项：无
参数示例："WIFI:T:WPA;S:LuatOS_AP;P:12345678;;"

返回值

local ok = qrcode:set_data(data)

ok

含义说明：操作结果
数据类型：boolean
取值范围：true（成功）、false（失败）
注意事项：若数据过长可能失败
返回示例：true

示例

local ok = qrcode:set_data("WIFI:T:WPA;S:LuatOS_AP;P:12345678;;")
log.info("qrcode", "set_data result", ok)
4.2.17.3 qrcode:set_size(size)

功能

设置二维码尺寸。

参数

size

参数含义：新尺寸（宽度和高度）
数据类型：number
是否必选：是
取值范围：大于0的整数
注意事项：无
参数示例：180

返回值

无

示例

qrcode:set_size(180)
4.2.17.4 qrcode:set_colors(dark, light)

功能

设置二维码颜色。

参数

dark

参数含义：深色模块颜色
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：0x0B3D91

light

参数含义：浅色模块颜色
数据类型：number
是否必选：是
取值范围：十六进制颜色值
注意事项：无
参数示例：0xF4F8FF

返回值

无

示例

qrcode:set_colors(0x0B3D91, 0xF4F8FF)
4.2.17.5 qrcode:destroy()

功能

销毁二维码组件。

参数

无

返回值

无

示例

qrcode:destroy()

4.2.18 加载指示器（airui.spinner） -- V1.1.5 新增

4.2.18.1 airui.spinner(config)

功能

创建加载指示器组件，用于显示正在加载或处理中的状态。

参数

config

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

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

    参数含义：加载指示器宽度
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认100
    参数示例：w = 40
    w = ,

    参数含义：加载指示器高度
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认100
    参数示例：h = 40
    h = ,

    参数含义：旋转一周所需时长（毫秒）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认1000
    参数示例：duration = 1000
    duration = ,

    参数含义：弧形角度（弧度覆盖范围）
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认200
    参数示例：arc_angle = 200
    arc_angle = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：parent = airui.screen
    parent = ,
}

style 子参数说明

参数含义：加载指示器样式配置
数据类型：table
是否必选：可选
取值范围：包含以下子参数：
{
    参数含义：旋转弧线颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x00b4ff
    参数示例：color = 0x00b4ff
    color = ,

    参数含义：轨道颜色（背景弧线颜色）
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：默认0x202835
    参数示例：track_color = 0x202835
    track_color = ,

    参数含义：线条宽度
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：默认4
    参数示例：line_width = 6
    line_width = ,

    参数含义：透明度
    数据类型：number
    取值范围：0-255，0为完全透明，255为完全不透明
    是否必选：可选
    注意事项：默认255
    参数示例：opa = 255
    opa = ,
}

返回值

local spinner_object = airui.spinner(config)

spinner_object

含义说明：加载指示器组件对象
数据类型：userdata
取值范围：包含 set_style、set_anim_params、is_destroyed、destroy 等方法的加载指示器对象
注意事项：需要添加到界面中才能显示
返回示例：spinner_object

示例

-- 创建加载指示器
local spinner = airui.spinner({
    x = 330, y = 120, w = 40, h = 40,
    duration = 1000,
    arc_angle = 200,
    style = {
        color = 0x00b4ff,
        track_color = 0x202835,
        line_width = 4,
        opa = 255,
    }
})
4.2.18.2 spinner:set_style(style) -- V1.1.5 新增

功能

设置加载指示器的样式。

参数

style

参数含义：加载指示器样式配置表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
{
    参数含义：旋转弧线颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：无
    参数示例：color = 0xff7a00
    color = ,

    参数含义：轨道颜色
    数据类型：number
    取值范围：十六进制颜色值
    是否必选：可选
    注意事项：无
    参数示例：track_color = 0x33261a
    track_color = ,

    参数含义：线条宽度
    数据类型：number
    取值范围：大于0的整数
    是否必选：可选
    注意事项：无
    参数示例：line_width = 6
    line_width = ,

    参数含义：透明度
    数据类型：number
    取值范围：0-255
    是否必选：可选
    注意事项：无
    参数示例：opa = 220
    opa = ,
}

返回值

无

示例

local spinner = airui.spinner({
    x = 330, y = 120, w = 40, h = 40,
})

spinner:set_style({
    color = 0xff7a00,
    track_color = 0x33261a,
    line_width = 6,
})
4.2.18.3 spinner:set_anim_params(duration, arc_angle) -- V1.1.5 新增

功能

设置加载指示器的动画参数。

参数

duration

参数含义：旋转一周所需时长
数据类型：number
取值范围：大于0的整数，单位毫秒
是否必选：是
注意事项：值越小旋转越快
参数示例：700

arc_angle

参数含义：弧形角度
数据类型：number
取值范围：大于0的整数
是否必选：是
注意事项：值越大弧线越长
参数示例：260

返回值

无

示例

local spinner = airui.spinner({
    x = 330, y = 120, w = 40, h = 40,
})

-- 设置更快的旋转速度和更长的弧线
spinner:set_anim_params(700, 260)
4.2.18.4 spinner:destroy()

功能

销毁加载指示器组件。

参数

无

返回值

无

示例

local spinner = airui.spinner({
    x = 330, y = 120, w = 40, h = 40,
})

-- 销毁加载指示器
spinner:destroy()

4.2.19 视频（airui.video） -- V1.1.5 新增

4.2.19.1 airui.video(config)

功能

创建视频播放组件，支持 MJPG 和 MP4 格式视频解码播放（MP4 目前无音频）。

参数

config

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

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

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

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

    参数含义：视频源文件路径
    数据类型：string
    取值范围：有效的视频文件路径
    是否必选：是
    注意事项：支持 MJPG 和 MP4 格式
    参数示例：src = "/luadb/fly_man.mjpg"
    src = ,

    参数含义：格式 -- V1.2.1 更新支持 mp4
    数据类型：string
    取值范围："auto"、"mjpg"、"avi_mjpg"、"mp4"
    是否必选：可选
    注意事项：默认"auto"。mp4 格式目前无音频
    参数示例：format = "mp4"
    format = ,

    参数含义：解码后端
    数据类型：string
    取值范围："auto"
    是否必选：可选
    注意事项：默认"auto"
    参数示例：backend = "auto"
    backend = ,

    参数含义：解码模式
    数据类型：string
    取值范围："hw"（硬件解码）
    是否必选：可选
    注意事项：默认"hw"
    参数示例：decode_mode = "hw"
    decode_mode = ,

    参数含义：播放帧间隔
    数据类型：number
    取值范围：大于0的整数，单位毫秒
    是否必选：可选
    注意事项：默认33（约30fps）
    参数示例：interval = 33
    interval = ,

    参数含义：是否循环播放
    数据类型：boolean
    取值范围：true（循环）、false（不循环）
    是否必选：可选
    注意事项：默认false
    参数示例：loop = false
    loop = ,

    参数含义：是否自动播放
    数据类型：boolean
    取值范围：true（自动播放）、false（手动播放）
    是否必选：可选
    注意事项：默认true
    参数示例：auto_play = true
    auto_play = ,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：parent = airui.screen
    parent = ,
}

返回值

local video_object = airui.video(config)

video_object

含义说明：视频组件对象
数据类型：userdata
取值范围：包含 play、pause、stop、is_destroyed、destroy 等方法的视频对象
注意事项：需要添加到界面中才能显示
返回示例：video_object

示例

local video = airui.video({
    x = 40, y = 40, w = 180, h = 180,
    src = "/luadb/fly_man.mjpg",
    format = "auto",
    backend = "auto",
    decode_mode = "hw",
    interval = 33,
    loop = true,
    auto_play = true,
})
4.2.19.2 video:play()

功能

播放视频。

参数

无

返回值

无

示例

local video = airui.video({
    x = 40, y = 40, w = 180, h = 180,
    src = "/luadb/fly_man.mjpg",
    auto_play = false,
})

-- 开始播放
video:play()
4.2.19.3 video:pause()

功能

暂停视频播放。

参数

无

返回值

无

示例

local video = airui.video({
    x = 40, y = 40, w = 180, h = 180,
    src = "/luadb/fly_man.mjpg",
})

-- 暂停播放
video:pause()
4.2.19.4 video:stop()

功能

停止视频播放并重置到第一帧。

参数

无

返回值

无

示例

local video = airui.video({
    x = 40, y = 40, w = 180, h = 180,
    src = "/luadb/fly_man.mjpg",
})

-- 停止播放
video:stop()
4.2.19.5 video:is_destroyed() -- V1.2.1 新增

功能

检查视频组件是否已被销毁。

参数

无

返回值

local destroyed = video:is_destroyed()

destroyed

含义说明：组件是否已被销毁
数据类型：boolean
取值范围：true（已销毁）, false（未销毁）
注意事项：无
返回示例：false

示例

local video = airui.video({
    x = 40, y = 40, w = 180, h = 180,
    src = "/luadb/fly_man.mjpg",
})

if not video:is_destroyed() then
    log.info("video", "still alive")
end
4.2.19.6 video:destroy()

功能

销毁视频组件。

参数

无

返回值

无

示例

local video = airui.video({
    x = 40, y = 40, w = 180, h = 180,
    src = "/luadb/fly_man.mjpg",
})

-- 销毁视频组件
video:destroy()

4.3 AirUI PC 端 专用接口和组件

4.3.1 系统键盘支持接口

3.3.1.1 airui.keyboard_enable_system(enabled)

功能

在 PC 模拟器上打开键盘输入法，支持实体键盘输入，而不是虚拟键盘输入。

参数

enabled

参数含义：是否启用系统键盘
数据类型：boolean
是否必选：是
取值范围：true（启用）, false（禁用）
注意事项：仅在PC模拟器上有效
参数示例：true
示例代码：enabled = true

返回值

local enable_result = airui.keyboard_enable_system(enabled)

enable_result

含义说明：启用操作结果
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：成功返回 true
返回示例：true

示例

-- 在PC模拟器上启用系统键盘输入
airui.keyboard_enable_system(true)

4.3.2 Lottie 动画组件

4.3.2.1 airui.lottie(config)

功能

配置 Lottie 动画，支持文件/内联数据、循环与速率配置。当前仅 pc 模拟器支持，真机后续计划支持。

参数

config

参数含义：Lottie动画配置参数表
数据类型：table
是否必选：是
取值范围：包含以下子参数：
{
    参数含义：动画源文件路径
    数据类型：string
    取值范围：有效的Lottie JSON文件路径
    是否必选：可选（与data二选一）
    注意事项：无
    参数示例："/luadb/anim.json"
    src = "/luadb/anim.json",

    参数含义：动画JSON数据
    数据类型：string
    取值范围：有效的Lottie JSON字符串
    是否必选：可选（与src二选一）
    注意事项：无
    参数示例："{\"v\":\"5.5.7\",\"fr\":60,\"ip\":0,\"op\":180,\"w\":500,\"h\":500,\"nm\":\"Comp 1\",\"layers\":[]}"
    data = "{\"v\":\"5.5.7\",\"fr\":60,\"ip\":0,\"op\":180,\"w\":500,\"h\":500,\"nm\":\"Comp 1\",\"layers\":[]}",

    参数含义：是否循环播放
    数据类型：boolean
    取值范围：true（循环）, false（不循环）
    是否必选：可选
    注意事项：默认false
    参数示例：true
    loop = true,

    参数含义：是否自动播放
    数据类型：boolean
    取值范围：true（自动播放）, false（手动播放）
    是否必选：可选
    注意事项：默认false
    参数示例：true
    auto_play = true,

    参数含义：播放速率
    数据类型：number
    取值范围：大于0的数
    是否必选：可选
    注意事项：默认1.0
    参数示例：1.5
    speed = 1.5,

    参数含义：准备完成回调
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：动画加载完成时触发
    参数示例：function() log.info("lottie", "ready") end
    on_ready = function() log.info("lottie", "ready") end,

    参数含义：播放完成回调
    数据类型：function
    取值范围：有效的Lua函数
    是否必选：可选
    注意事项：动画播放完成时触发（非循环模式下）
    参数示例：function() log.info("lottie", "complete") end
    on_complete = function() log.info("lottie", "complete") end,

    参数含义：父对象
    数据类型：userdata
    取值范围：有效的容器组件
    是否必选：可选
    注意事项：默认当前屏幕
    参数示例：airui.screen
    parent = airui.screen,
}

返回值

local lottie_object = airui.lottie(config)

lottie_object

含义说明：Lottie动画组件对象
数据类型：userdata
取值范围：包含 play、pause、stop、set_src、is_destroyed、destroy 等方法的动画对象
注意事项：需要添加到界面中才能显示
返回示例：lottie_object

示例

-- 配置Lottie 动画
local anim = airui.lottie({ 
    src = "/luadb/anim.json" 
})

-- 开始播放动画
anim:play()
4.3.2.2 Lottie:play()

功能

开始播放动画。

参数

无

返回值

无

示例

-- 开始播放动画
anim:play()
4.3.2.3 Lottie:pause()

功能

暂停播放。

参数

无

返回值

无

示例

-- 暂停播放
anim:pause()
4.3.2.4 Lottie:stop()

功能

停止并重置动画。

参数

无

返回值

无

示例

-- 停止并重置动画
anim:stop()
4.3.2.5 Lottie:set_src(source)

功能

更新动画源。

参数

source

参数含义：动画源
数据类型：string 或 table
是否必选：是
取值范围：字符串路径或 {path=..., data=...} 表
注意事项：无
参数示例："/luadb/anim2.json"
示例代码：source = "/luadb/anim2.json"

返回值

无

示例

-- 通过文件路径设置动画源
anim:set_src("/luadb/anim2.json")

-- 通过数据设置动画源
anim:set_src({data = '{"v":"5.5.7","fr":60,"ip":0,"op":180,"w":500,"h":500,"nm":"Comp 1","layers":[]}'})
4.3.2.6 Lottie:set_speed(speed)

功能

设置播放速率。

参数

speed

参数含义：播放速率
数据类型：number
是否必选：是
取值范围：大于 0 的数
注意事项：1.0为正常速度
参数示例：1.5
示例代码：speed = 1.5

返回值

无

示例

-- 设置为1.5倍速
anim:set_speed(1.5)
4.3.2.7 Lottie:set_loop(loop)

功能

控制是否循环播放。

参数

loop

参数含义：循环标志
数据类型：boolean
是否必选：是
取值范围：true（循环）, false（不循环）
注意事项：无
参数示例：true
示例代码：loop = true

返回值

无

示例

-- 设置为循环播放
anim:set_loop(true)
4.3.2.8 Lottie:set_progress(progress)

功能

设置动画进度。

参数

progress

参数含义：动画进度
数据类型：number
是否必选：是
取值范围：0~1 浮点数
注意事项：0表示开始，1表示结束
参数示例：0.5
示例代码：progress = 0.5

返回值

无

示例

-- 跳转到动画中间位置
anim:set_progress(0.5)
4.3.2.9 Lottie:destroy()

功能

销毁动画资源。

参数

无

返回值

无

示例

-- 销毁动画资源
anim:destroy()

五、仅内置点阵字体固件加载固定内容的 ttf 字体文件说明

5.1、使用情况说明

  1. Air780EHM/Air8000 等型号 14 号/114 固件内置了.ttf 字体文件，占用了约 1.7MB 的存储空间，导致固件内无法包含摄像头、语音等核心库功能，所以新增了 15/115 号固件和 16/116 号 2 个固件版本去除了固件内置了.ttf 字体文件增加更多功能，具体支持功能差异可以查看选型手册：https://docs.openluat.com/common/product/
  2. 新增固件内置了 16 号中文点阵字体，不需要初始化 hzfont 也能显示中英文和符号，字体大小固定 16 号。

  3. 如果使用了没有内置.ttf 字体文件的固件，并且还需要在显示固定内容位置显示更大的字号，那么可以通过以下步骤进行操作

  4. 将需要显示的内容通过 luatos-font-tools 生成只包含这些内容的.ttf 字体文件

  5. 通过 airui.font_load(config)选择所指定的.ttf 字体文件，全局参数使用 global = false
  6. label 中 font = "hzfont"，此时 label 中设置字体大小参数 font_size 可以生效，支持设置 16-255 号字体大小。

5.2、制作仅包含特定内容的 ttf 字体步骤

5.2.1 进入 luatos-font-tools 代码仓库

https://gitee.com/openLuat/luatos-font-tools

5.2.2 以 luatos-font-tools 文件在 D 盘根目录为例，演示完整操作步骤

步骤 1：打开命令提示符
  • 按键盘 Win + R
  • 输入 cmd 回车
步骤 2：进入 D 盘并克隆仓库，执行完不要关闭 CMD 窗口
cd /d D:\

git clone https://gitee.com/openLuat/luatos-font-tools.git

执行后会在 D 盘创建 D:\luatos-font-tools 文件夹

（也可以直接将代码压缩包下载至本地）

步骤 3：在 CMD 窗口继续输入命令进入项目目录
cd luatos-font-tools
步骤 4：在 CMD 窗口继续输入命令安装工具
python -m pip install .

等待安装完成，显示 "Successfully installed"

步骤 5：编辑字符文件

在 D 盘 D:\luatos-font-tools 文件夹下打开 examples\sample_chars.txt 的记事本中输入需要保留的字符，例如：

你好LuatOS测试123456

按 Ctrl + S 保存，关闭记事本

步骤 6：执行字体裁剪
python -m luatos_font_tools -i examples\MiSans-Demibold.ttf -o examples\MiSans_mini.ttf --text-file examples\sample_chars.txt --verbose
步骤 7：查看结果
dir examples\MiSans-Demibold*.ttf

会显示两个文件：

  • MiSans-Demibold.ttf（原始，约 8MB）
  • MiSans``_mini.ttf（裁剪后，约 8KB）
完整命令序列（复制粘贴执行）：
cd /d D:\
git clone https://gitee.com/openLuat/luatos-font-tools.git
cd luatos-font-tools
python -m pip install .
# [在记事本输入字符并保存]
python -m luatos_font_tools -i examples\MiSans-Demibold.ttf -o examples\MiSans_mini.ttf --text-file examples\sample_chars.txt --verbose
dir examples\MiSans-Demibold*.ttf

5.3、label 组件使用含特定内容的 ttf 字体文件进行显示步骤

5.3.1 将字体文件放入脚本分区烧录至设备（二选一）

操作如下：

-- 初始化AirUI
local width, height = lcd.getSize()
airui.init(width, height)

-- 加载hzfont字库，从而支持中文显示
airui.font_load({
    type = "hzfont",                 -- 字体类型，可选 "hzfont" 或 "bin"
    path = "/luadb/MiSans_mini.ttf", -- 字体路径，对于 "hzfont"，传 nil 则使用内置字库
    size = 16,                       -- 默认显示字体大小，14号
    cache_size = 256,                -- 缓存字数大小，默认 256
    antialias = 1,                   -- 抗锯齿等级1-3，默认自动抗锯齿
    load_to_psram= true,             -- 是否将ttf文件加载至内存中，字体少可以加载
    global = false                   -- 字体不进行全局加载，仅在指定font = "hzfont"的label组件中加载
})

-- 创建标签并使用内置字体
airui.label({
    text = "中文显示测试",
    x = 10,
    y = 50,
    w = 100,
    h = 200,
})

-- 创建标签并使用加载的字体
airui.label({
    text = "你好LuatOS123",
    x = 10,
    y = 100,
    w = 300,
    h = 200,
    font_size = 36,
    font = "hzfont",
})

5.3.2 将字体文件放入文件系统烧录至设备（二选一）

操作如下：

-- 初始化AirUI
local width, height = lcd.getSize()
airui.init(width, height)

-- 加载hzfont字库，从而支持中文显示
airui.font_load({
    type = "hzfont",                 -- 字体类型，可选 "hzfont" 或 "bin"
    path = "/MiSans_mini.ttf",       -- 字体路径，对于 "hzfont"，传 nil 则使用固件内置ttf字体文件
    size = 16,                       -- 默认显示字体大小，14号
    cache_size = 256,                -- 缓存字数大小，默认 256
    antialias = 1,                   -- 抗锯齿等级1-3，默认自动抗锯齿
    load_to_psram= true,             -- 是否将ttf文件加载至内存中，字体少可以加载
    global = false                   -- 字体不进行全局加载，仅在指定font = "hzfont"的label组件中加载
})

-- 创建标签并使用内置字体
airui.label({
    text = "中文显示测试",
    x = 10,
    y = 50,
    w = 100,
    h = 200,
})

-- 创建标签并使用加载的字体
airui.label({
    text = "你好LuatOS123",
    x = 10,
    y = 100,
    w = 300,
    h = 200,
    font_size = 36,
    font = "hzfont",
})

六、未内置 ttf 字体文件和点阵字体的固件加载完整 ttf 文件操作说明

6.1 使用情况说明

  1. Air8101 支持 hzfont 的固件中未内置.ttf 文件，可以选择从 SD 卡或者模组文件系统中加载。如果选择从模组文件系统中加载，那么在烧录固件时需要手动将.ttf 文件字体文件一并烧录到模组的文件系统中，且初始化 hzfont 时选择所烧录的字体文件。
  2. 字体文件大小不能超过固件所支持的文件系统空间。
  3. 字体所在文件夹不能是包含中文路径名

6.2 烧录步骤如下：

  • 将.ttf 文件准备好，或者下载 MiSans_gb2312.ttf，单独放入一个空文件夹中
  • 烧录固件时选择对应的文件夹，然后选择下载底层和脚本

6.3 使用说明

-- Air8101使用104号固件将字体文件烧录到文件系统，从文件系统中加载hzfont字库，从而支持12-255号中文显示
airui.font_load({
    type = "hzfont",             -- 字体类型，可选 "hzfont" 或 "bin"
    path = "/MiSans_gb2312.ttf", -- 字体路径，对于 "hzfont"，传 nil 则使用固件内置ttf字体文件
    size = 20,                   -- 默认显示字体大小，14号
    cache_size = 1048,           -- 缓存字数大小，默认 256
    antialias = 1,               -- 抗锯齿等级1-3，默认自动抗锯齿
-- load_to_psram= true,          -- 是否将ttf文件加载至内存中
    global = true                -- 字体不进行全局加载，仅在指定font = "hzfont"的label组件中加载
})

-- 创建标签并使用加载的字体
airui.label({ x=60, y=10, w=680, h=30, text="串口", font_size=24, color=0xffffff })

七、AirUI 更新说明

AirUI V 1.2.1

  1. 更新时间：2026-05-11
  2. 更新内容：
    • add: airui，添加 is_destroyed 方法以检查组件是否被销毁
    • fix: airui，修复 tp 订阅的位置在旋转后不对的问题
    • add: airui，进度条支持设置 text 字体大小
    • add: airui，增加图片内容适配模式设置功能，支持 center、contain、cover 和 stretch 选项
    • fix: airui，修复 airui_switch_set_state 无论状态是否变化创建的时候底层都会发送 LV_EVENT_VALUE_CHANGED 的问题
    • add: airui，下拉框添加 set_options 方法以设置下拉框内容选项
    • fix: airui，重构键盘底层，修复死机问题
    • add: airui，增加对于 msgbox 组件自定义参数的支持如 xywh
    • update: airui，减小输入候选框大小为屏幕的 8%
    • fix: airui，修复键盘隐藏后光标跳转异常的问题
    • add: airui，添加 mp4 播放器支持，目前没有音频
    • update: airui，优化 video 组件为双缓冲减少 copy 复制时间
    • add: airui，支持订阅 pc 键盘按键值
    • fix: airui，修复共享键盘 data->target 变成悬空指针，第二次打开弹窗时在解绑旧 target 回调处踩到已释放对象问题
    • fix: airui，修复键盘中文选字框失效问题；修复部分键盘销毁逻辑
    • add: airui，支持获取 win 窗口标题和 table 单元的 text 信息
    • add: airui，支持 table 单元格点击回调设置
    • fix: airui，修复键盘候选字面板有时消失的问题

AirUI V 1.2.0

  1. 更新时间：2026-04-20
  2. 更新内容：
    • remove: airui，移除三个 airui 废弃接口兼容性，改为提醒 + 报错

AirUI V 1.1.6

  1. 更新时间：2026-04-17
  2. 更新内容：
  3. add: airui，优化PC模拟器界面超出屏幕时自动缩放到90%屏幕处；支持拖拽自动缩放画面
  4. fix: airui，组件采用共享缓存解决销毁组件被访问的问题和定位
  5. fix: airui，修复键盘预览框在键盘被销毁时没有一起被销毁
  6. fix: airui，修复键盘 auto_hide 失效的问题
  7. fix: airui，通过 seq 方案部分修复 UI 刷新消息丢失的问题
  8. add: airui，button 增加 get_text 和 set_disabled 子方法
  9. remove: airui，彻底移除 xml 的支持
  10. add: airui，增加刷新消息重试超时时间以支持画面刷新重试
  11. update: airui，仅在调试模式下记录未处理消息的重试信息
  12. add: airui，增加获取当前状态的接口 status
  13. add: airui，增加设置图片旋转中心点的子方法
  14. update: airui，所有组件的 xywh 位置自动向下取整
  15. add: airui，增加 shape 组件，当前支持直线、圆形、椭圆、矩形/圆角矩形

AirUI V 1.1.5

  1. 更新时间：2026-04-07
  2. 更新内容：
  3. fix: airui，修复hw循环解码时，硬解码器中间没有释放的问题
  4. add: airui，增加spinner组件
  5. update: airui，PC模拟器画面启动和旋转后自动居中
  6. update: airui，调整hzfont的默认缓存数量为1024
  7. add: airui，容器组件增加移动的接口
  8. add: airui，给button、image、label增加移动的子方法
  9. fix: airui，修复键盘预览框光标无法被选择的问题
  10. add: airui，增加video组件，当前只支持mjpg解码
  11. update: airui，关闭真机端airui日志系统，减少固件大小
  12. fix: airui，修复先使用lcd后初始化airui时PC模拟器旋转不对的问题
  13. fix: airui，修复airui长时间计算时会导致真机没有时间喂狗死机的问题
  14. add: airui，SDL模拟器增加反向预览补偿，避免模拟器调试旋转时横屏预览不方便

AirUI V 1.1.4

  1. 更新时间：2026-03-30
  2. 更新内容：
  3. update: airui，优化JPG图片加载速度
  4. update: airui，优化内存管理
  5. add: airui，table支持插入行或者列；支持跳转或者跑马灯两种自动滚动方式
  6. add: airui，增加table组件支持样式设置；增加或者移除一行或者一列
  7. add: airui，增加button、dropdown、keyboard、table、tabview、win组件中字号任意大小的设置能力
  8. add: airui，添加animimg组件
  9. add: airui，TabView组件支持获取标签页数量、添加新标签页和移除指定标签页的功能
  10. fix: airui，修复spi屏幕上出现颜色反转问题
  11. add: airui，table支持边框宽度、单元格文本对齐和垂直对齐属性设置
  12. update: airui，支持显示和触摸旋转功能
  13. update: airui，调高分配缓存为1/2屏幕，能有效提高旋转屏幕刷新效率

AirUI V 1.1.3

  1. 更新时间：2026-03-20
  2. 更新内容：
  3. update: airui，支持图片缓存，默认最大 1MB 缓存大小
  4. add: airui，支持 JPG 硬件解码（部分平台）
  5. update: airui，JPG 图片现在支持旋转、透明和缩放操作（需硬件支持）
  6. update: airui，下拉框组件增加 get_value() 方法，用于获取当前选中项的文本
  7. update: airui，添加 libjpeg-turbo 支持用于 PC 模拟器的 JPEG 解码
  8. update: airui，图表组件（chart）在没有数据时默认显示为空
  9. update: airui.wakeup 增加 auto_refresh 参数，可控制唤醒后是否自动刷新屏幕
  10. update: airui，键盘组件的选字候选框高度从 5% 提高到 10%
  11. update: airui.sleep 增加 power_down_lcd 参数，可控制休眠时是否关闭 LCD 电源
  12. fix: airui，修复 tabview 回调函数中 index 参数始终为 nil 的问题
  13. fix: airui，修复二维码组件设置颜色和大小失效的问题
  14. add: airui.win，支持标题对齐方式配置，通过 style.title_align 设置
  15. update: airui，更新 hzfont 设置字体大小的底层设计，同时为 button 组件增加 font 和 font_size 支持
  16. update: airui，缓冲区大小调整为 2 × (四分之一屏幕)，减少内存占用
  17. update: airui，xml默认关闭，可节省约 100KB Flash 空间
  18. add: airui.table，增加行高、初始内容设置功能，支持统一或逐行设置，同时支持统一或逐列设置列宽
  19. fix: airui，修复 textarea 组件处理文本慢的问题

AirUI V 1.1.2

  1. 更新时间：2026-03-17
  2. 更新内容：
  3. add: airui 增加检测渐进式 jpg 图片时打印 Warning 提醒，提示用户转为 baseline 格式
  4. add: airui 添加全屏刷新、休眠和唤醒功能
    • airui.sleep() - airui 界面休眠
    • airui.wakeup() - airui 设备唤醒
    • airui.full_refresh() - airui 整页刷新
  5. fix: airui 修复 pc 模拟器上运行 airui 时和 lcd 一起使用会出现两个窗口的问题
  6. add: airui.tabview 组件增加切屏方式配置和标签栏尺寸设置功能，支持两种切换方式 jump 跳转 / swipe 滑动
  7. add: airui.keyboard 增加拼音输入法模式参数设置支持，包括 pinyin_26、pinyin_9 和 pinyin_9_number
  8. update: airui.keyboard 键盘候选区一直打开，避免误触；预览区改为 textarea，支持光标重新移动到预览区
  9. update: airui.textarea 减小组件上下内边距为 4，避免滚动条临界高度异常
  10. add: airui 增加默认点阵字符范围，包含更多标点和符号（比如 ℃ 这种特殊字符）
  11. update: airui.image 添加对 JPG 图片旋转设置的拦截，目前只有 PNG 图片支持旋转
  12. update: airui.button 按钮样式设置接口从 stype 修改为 style，更好的表达样式表的意思，后续 1.2.0 不再兼容 set_stype
  13. add: airui.win 添加窗口样式设置功能，支持多种 style 样式属性的配置，包括背景色、边框、内边距等
  14. add: airui 添加触摸事件订阅和取消功能，支持 down、hold、up 三种 tp 事件订阅
    • airui.touch_subscribe(function(state, x, y, track_id, timestamp) ... end)
    • 提供三个触摸事件常量：airui.TP_DOWN、airui.TP_HOLD、airui.TP_UP

AirUI V 1.1.1

  1. 更新时间：2026-03-06
  2. 更新内容：
  3. fix: airui 修复 tp 在 airui 中旋转异常
  4. add: container 容器组件增加点击回调 on_click 参数
  5. fix: airui 优化触摸 tp 数据处理
  6. add: chart 图表组件支持多曲线、坐标完整设置，同时移除了部分不必要的子方法接口；增加柱状图/堆叠柱状图支持
  7. add: label 标签组件增加对齐功能，支持左、中、右对齐，新增三个对齐常量 TEXT_ALIGN_LEFT/CENTER/RIGHT
  8. add: chart 图表组件增加柱状图/堆叠柱状图，提供 add_series/remove_series/set_bar_gap/set_bar_radius/set_x_axis/set_y_axis 等接口
  9. fix: tp 修复 ft3x68 型号 tp 适配 airui 异常的问题
  10. add: 新增 qrcode 二维码组件，支持动态修改内容、尺寸和颜色
  11. add: keyboard 键盘组件增加输入预览功能，新增 preview/preview_height 参数
  12. update: keyboard 修改键盘组件背景从默认透明改为有颜色；将预览框间距改为 0
  13. add: font_load 增加 hzfont 和默认字体同时使用的支持，新增 global 参数
  14. add: button 按钮组件增加自定义样式功能，新增完整样式参数配置支持
  15. add: image 图像组件增加旋转功能，新增 rotation 参数
  16. fix: keyboard 修复键盘输入大写字符计算导致越界死机问题
  17. fix: airui，修复 label 组件在 hzfont 为全局时字体设置失效和 hzfont.debug 异常
  18. update: hzfont 光栅化部分从全局扫描算法改为扫描线算法，优化渲染性能
    • 原算法：1级抗锯齿耗时 4ms/字（36号字体），2级抗锯齿 16ms，4级抗锯齿 64ms
    • 新算法：1级抗锯齿耗时 2ms/字，2级抗锯齿 5ms，3级抗锯齿 8ms，且 1 级抗锯齿效果等价原 2 级抗锯齿
  19. fix: airui 修复图表 x 坐标异常，以及坐标单位遮挡的问题

AirUI V 1.1.0

  1. 更新时间：2026-02-28
  2. 更新内容：
  3. 新增 airui.device_bind_keypad(config) 组件，通过将 GPIO 绑定上、下、确认、返回操作，实现通过 GPIO 代替触摸控制 button 组件操作
  4. 新增 airui.debug(true/false) 接口，用于调试 airui
  5. 新增 chart 组件，实现曲线图展示功能
  6. 修复 win 组件 on_close 无效，点击关闭按钮不能关闭问题
  7. 优化中文拼音输入法逻辑
  8. 优化 AirUI 内存控制
  9. 调整底层自动刷新周期至 33ms，也就是每秒 30 帧
  10. 修复加载 hzfont 字体时画面卡顿问题，同时添加 hzfont 调试统计功能接口 hzfont.debug()，支持字符串渲染耗时统计并输出日志

AirUI V 1.0.3

  1. 更新时间：2026-02-14
  2. 更新内容：
  3. 除 win 组件外，其他交互类组件新增支持在点击和回调函数中使用 self:子方法 的方式
  4. airui.textarea(config) 支持多个输入框绑定同一个键盘样式
  5. airui.bar(config) 接口中新增 show_progress_text 参数，支持设置是否显示进度条进度值
  6. airui.bar(config) 接口中新增 progress_text_format 参数，支持设置进度条进度显示值样式
  7. 新增 bar:set_progress_text_format(format) 子方法，支持设置进度文本的显示格式
  8. 新增 bar:set_progress_text_color(color) 子方法，支持设置进度文本的颜色
  9. airui.container(config) 接口中新增 color_opacity 参数，支持设置容器透明度
  10. 新增 airui.version() 接口，支持获取当前固件内 AirUI 版本号
  11. 优化其他组件加入 win 组件时，不再需要使用 win:add_content 将组件添加进去，只需将子组件的父级设置为 win 组件即可，保留 win:add_content 方法
  12. 调整 pinyin 表顺序，修复部分拼音无法正确找到候选字的问题
  13. 修复切换按键中 set_state 子方法调用后死机问题
  14. 修复 label 设置大小后会影响其它组件字体大小的问题
  15. 更新 airui 刷新方式为定时刷新
  16. 新增键盘模式设置时添加日志打印记录以便于观察是否设置正确

AirUI V 1.0.1

  1. 更新时间：2026-02-03
  2. 更新内容：
  3. airui.indev_bind_touch(tp_cfg) 改为 airui.device_bind_touch(tp_cfg)
  4. airui.font_load(config) 接口中新增 load_to_psram 参数，是否将 .ttf 字体文件加载至 PSRAM 中
  5. airui.label(config) 接口中新增 font_size 和 color 参数，支持设置 label 大小和颜色
  6. 新增 label:set_font_size(size) 子方法，支持设置 label 字体大小
  7. 新增 label:set_color(color) 子方法，支持设置 label 字体颜色
  8. airui.keyboard(config) 接口中新增 bg_color 参数，支持设置键盘备选区域背景色
  9. 新增 keyboard:set_bg_color(color) 子方法
  10. 更新常量：去除常量中的 AIRUI_ 部分
  11. 优化拼音表排序，常规字放前面，多音字放后面
  12. img 图片组件拦截 jpg 图片设置透明度和大小缩放
  13. 优化内存分配逻辑，提高资源利用率

AirUI V 1.0.0

  1. 更新时间：2026-01-28
  2. 更新内容：
  3. 首次推出 AirUI
  4. 支持 label、image、button、switch、bar、dropdown、textarea、keyboard、table、container、tabview、win 等核心组件，支持 hzfont、xml 导入、AirUI PC 端