深入理解 LuatOS核心库API——AirUI 基础知识
airui 基础引擎作为框架的运行中枢，负责指令解析、虚拟DOM管理与事件循环调度，是实现流畅用户交互体验的核心支撑。其采用异步更新策略与细粒度依赖追踪技术，显著提升了渲染效率与资源利用率。本文将从源码层面切入，系统讲解基础引擎的关键实现路径与设计思想。
一、概述
AirUI 是基于 LVGL 9.4 版本进行图形层封装的 LuatOS 核心库，把常用组件、事件管理、输入和基础视觉主题封装为更易上手的 Lua 接口，便于在支持 LuatOS 的设备和 PC 上统一开发。
主要特性
组件丰富：内置丰富标签类型、图片显示、按钮、开关、进度条、下拉框、输入框、键盘、表格、容器、选项卡、窗口等核心组件;
更低成本：可选 hzfont 矢量字体支持 12-255 号字体，节省字库成本;
开发高效：用更少代码快速搭建可量产的触控界面，参考示例代码能快速掌握原理;
验证便捷：提供 LuatOS windows桌面系统 快速验证效果，无需烧录就能看到代码运行效果;
支持 LuatOS windows桌面系统 (SDL2) 和真机两种模式：
当前LuatOS windows桌面系统支持Lottie动画和键盘输入；
PC端仅支持window 10/11系统；
真机支持Air8101和Air8000系列、Air780EHM/EGH/EHV等；
支持使用设计器设计页面和 XML 导入，能够快速搭建页面原型与交互逻辑。
当前 AirUI 设计器开发中，目前可以使用 LVGL 9.4 官方设计器进行页面设计
注意事项
AirUI 使用的是 lcd 核心库初始化显示设备
二、核心示例
2.1 核心代码
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
返回 Luatloos 工具首页，点击--项目管理测试
创建一个项目并命名
选择固件刚才下载的固件--点击打开，路径在 Luatools 目录下 resource\LuatOS_Air780EHM\LuatOS-SoC_VXXXX_Air780EHM
将下载的 demo 图片资源和.lua 文件拖入到项目管理内的脚本和资源列表区域--勾选添加默认 lib--点击LuatOS 桌面系统运行--出来的界面就是 demo 在实际设备上运行界面的仿真，可以用鼠标进行交互
如需切换 demo 内的演示内容，可打开下载脚本文件中的 mian.lua 文件，将需要演示 demo 的 require 前面的注释符"--"去掉，将不需要演示 demo 的 require 前面加上注释符“--”。修改后保存代码文件，再点击LuatOS 桌面系统运行，就会出现所 require 的 demo 对应的界面仿真。
比如：需要演示下拉框组件，将 main.lua 文件中的-- require("airui_dropdown") 改为 require("airui_dropdown") ，并把其他加载的组件改为注释状态。
2.3 组件效果及其 demo
2.3.1 label（标签）
2.3.1.1 演示效果
2.3.1.2 演示代码
2.3.1.3 加载方式
2.3.2 button（按钮）
2.3.2.1 演示效果
2.3.2.2 演示代码
2.3.2.3 加载方式
2.3.3 image（图片）
2.3.3.1 演示效果
2.3.3.2 演示代码
2.3.3.3 加载方式
2.3.4 container（容器）
2.3.4.1 演示效果
2.3.4.2 演示代码
2.3.4.3 加载方式
2.3.5 bar（进度条）动态方式
2.3.5.1 演示效果
2.3.5.2 演示代码
2.3.5.3 加载方式
2.3.6 dropdown（下拉框）
2.3.6.1 演示效果
2.3.6.2 演示代码
2.3.6.3 加载方式
2.3.7 switch（开关按钮）
2.3.7.1 演示效果
2.3.7.2 演示代码
2.3.7.3 加载方式
2.3.8 msgbox（消息窗）
2.3.8.1 演示效果
2.3.8.2 演示代码
2.3.8.3 加载方式
2.3.9 textarea（输入框）+ keyboard（键盘）
2.3.9.1 演示效果
2.3.9.2 演示代码
2.3.9.3 加载方式
2.3.10 tabview（选项卡）
2.3.10.1 演示效果
2.3.10.2 演示代码
2.3.10.3 加载方式
2.3.11 table（表格）
2.3.11.1 演示效果
2.3.11.2 演示代码
2.3.11.3 加载方式
2.3.12 win（窗口容器）
2.3.12.1 演示效果
2.3.12.2 演示代码
2.3.12.3 加载方式
2.3.13 全部控件
2.3.13.1 演示效果
2.3.13.2 演示代码
2.3.13.3 加载方式
2.3.14 页面切换
2.3.14.1 演示效果
2.3.14.2 演示代码
2.3.14.3 加载方式
2.3.15 hzfont 矢量字体
2.3.15.1 演示效果
2.3.15.2 演示代码
2.3.15.3 加载方式
三、常量详解
扩展库常量，顾名思义是由扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中直接调用；
AirUI 库定义了以下常量：
3.1 颜色格式常量
3.1.1 airui.COLOR_FORMAT_RGB565
3.1.2 airui.COLOR_FORMAT_ARGB8888
3.2 文本对齐常量
3.2.1 airui.TEXT_ALIGN_LEFT
3.2.2 airui.TEXT_ALIGN_CENTER
3.2.3 airui.TEXT_ALIGN_RIGHT
3.3 事件码常量
3.3.1 airui.EVENT_CLICKED
3.3.2 airui.EVENT_PRESSED
3.3.3 airui.EVENT_RELEASED
3.3.4 airui.EVENT_VALUE_CHANGED
3.4 图标符号常量
3.4.1 airui.SYMBOL_SETTINGS
3.4.2 airui.SYMBOL_HOME
3.4.3 airui.SYMBOL_PLAY
3.4.4 airui.SYMBOL_PAUSE
3.4.5 其他图标符号常量类似，包括：
3.5 tabview 内边距常量
3.5.1 airui.TABVIEW_PAD_ALL
3.5.2 airui.TABVIEW_PAD_HOR
3.5.3 airui.TABVIEW_PAD_VER
3.5.4 airui.TABVIEW_PAD_TOP
3.5.5 airui.TABVIEW_PAD_BOTTOM
3.5.6 airui.TABVIEW_PAD_LEFT
3.5.7 airui.TABVIEW_PAD_RIGHT
四、函数详解
4.1 核心接口
4.1.1 airui.init(width, height, color_format)
功能
初始化 LVGL 渲染上下文，包括屏幕分辨率、颜色格式、上下文创建与绑定，使后续组件创建可用。
参数
width
height
color_format
返回值
local init_result = airui.init(width, height, color_format)
init_result
示例
4.1.2 airui.deinit()
功能
释放画布与上下文资源，清理注册表中的 airui_ctx，通常在退出或重新初始化前调用。
参数
无
返回值
无
示例
4.1.3 airui.refresh()
功能
驱动 LVGL 定时器，需在主循环中周期调用以完成绘制和事件分发。
参数
无
返回值
无
示例
4.1.4 airui.device_bind_touch(tp_cfg)
功能
将触摸初始化后的事件和数据与 AirUI 绑定
参数
tp_cfg
返回值
local bind_result = airui.device_bind_touch(tp_cfg)
bind_result
示例
4.1.5 airui.font_load(config)
功能
加载文本渲染所需字体，目前用于支持内置矢量字库（hzfont），此接口返回字体指针将绑定到所有 lvgl 字符中，缺失字符则将使用 lvgl 默认 14 号字体，如果 lvgl 默认字符也没有，则会出现字符空缺。
参数
config
返回值
local font_object = airui.font_load(config)
font_object
示例
4.2 组件接口
4.2.1.1 airui.label(config)
功能
用于静态文本和内置图标显示，可设置点击回调，支持 set_text/set_symbol。
参数
config
返回值
local label_object = airui.label(config)
label_object
示例
4.2.1.2 label:set_text(text)
功能
设置标签文本。
参数
text
返回值
无
示例
4.2.1.3 label:set_color(color)
功能
设置标签颜色。
参数
color
返回值
无
示例
4.2.1.4 label:set_font_size(size)
功能
设置标签大小。
参数
size
返回值
无
示例
4.2.1.5 label:set_symbol(symbol)
功能
将文本替换为符号字符。
参数
symbol
返回值
无
示例
4.2.1.6 label:set_on_click(fn)
功能
设置点击回调。
参数
fn
返回值
无
示例
4.2.1.7 label:get_text()
功能
获取当前文本。
参数
无
返回值
local text_content = label:get_text()
text_content
示例
4.2.1.8 label:destroy()
功能
销毁组件。
参数
无
返回值
无
示例
4.2.2 按钮（airui.button）
4.2.2.1 airui.button(config)
功能
创建可点击的文本按钮，支持 on_click 回调及 toggle 逻辑。
参数
config
返回值
local button_object = airui.button(config)
button_object
示例
4.2.2.2 button:set_text(text)
功能
更改按钮显示文字。
参数
text
返回值
无
示例
4.2.2.3 button:set_on_click(fn)
功能
更新按钮点击回调。
参数
fn
返回值
无
示例
4.2.2.4 button:destroy()
功能
销毁按钮及其资源。
参数
无
返回值
无
示例
4.2.3 图像（airui.image）
4.4.1 airui.image(config)
功能
显示图片，支持静态图片/符号、缩放与透明度控制。
参数
config
返回值
local image_object = airui.image(config)
image_object
示例
4.4.1.1 image:set_src(src)
功能
替换图片来源。
参数
src
返回值
无
示例
4.4.1.2 image:set_zoom(zoom)
功能
设置图片显示缩放比例（256 表示 100%）。
参数
zoom
返回值
无
示例
4.4.1.3 image:set_opacity(opacity)
功能
调整图片透明度。
参数
opacity
返回值
无
示例
4.4.1.4 image:destroy()
功能
销毁图片组件。
参数
无
返回值
无
示例
4.2.4 容器（airui.container）
4.2.4.1 airui.container(config)
功能
用于多页面制作，支持颜色、显示控制与 open。
参数
config
返回值
local container_object = airui.container(config)
container_object
示例
4.2.4.2 container:set_color(color)
功能
设置容器背景色。
参数
color
返回值
无
示例
4.2.4.3 container:set_hidden(hidden)
功能
控制可见性，可以设置为可见或者不可见，与 hide/open 形成互补。
参数
hidden
返回值
无
示例
4.2.4.4 container:hide()
功能
隐藏容器。
参数
无
返回值
无
示例
4.2.4.5 container:open()
功能
显示容器（若之前隐藏）。
参数
无
返回值
无
示例
4.2.4.6 container:destroy()
功能
销毁容器及子组件。
参数
无
返回值
无
示例
4.2.5 进度条（airui.bar）
4.2.5.1 airui.bar(config)
功能
显示进度范围，可自定义颜色与圆角。
参数
config
返回值
local bar_object = airui.bar(config)
bar_object
示例
4.2.5.2 bar:set_value(value, anim)
功能
更新当前进度，支持动画。
参数
value
anim
返回值
无
示例
4.2.5.3 bar:get_value()
功能
读取当前进度值。
参数
无
返回值
local current_value = bar:get_value()
current_value
示例
4.2.5.4 bar:set_range(min, max)
功能
设置进度范围。
参数
min
max
返回值
无
示例
4.2.5.5 bar:set_indicator_color(color)
功能
更换进度条指示器颜色。
参数
color
返回值
无
示例
4.2.5.6 bar:set_bg_color(color)
功能
设置背景颜色。
参数
color
返回值
无
示例
4.2.5.7 bar:destroy()
功能
销毁进度条。
参数
无
返回值
无
示例
4.2.6 表格（airui.table）
4.2.6.1 airui.table(config)
功能
用于展示数据表格，支持设置各列宽及边框颜色。
参数
config
返回值
local table_object = airui.table(config)
table_object
示例
4.2.6.2 table:set_cell_text(row, col, text)
功能
设置特定单元格文本。
参数
row
image.png
col
text
返回值
无
示例
4.2.6.3 table:set_col_width(col, width)
功能
调整列宽。
参数
col
width
返回值
无
示例
4.2.6.4 table:set_border_color(color)
功能
设置边框颜色。
参数
color
image.png
返回值
无
示例
4.2.6.5 table:destroy()
功能
销毁表格组件。
参数
无
返回值
无
示例
4.2.7 选项卡（airui.tabview）
4.2.7.1 airui.tabview(config)
功能
创建多标签页选项卡，支持点击标签和滑动页面切换。
参数
config
返回值
local tabview_object = airui.tabview(config)
tabview_object
示例
4.2.7.2tabview:set_active(index)
功能
切换当前页。
参数
index
返回值
无
示例
4.2.7.3 tabview:get_content(index)
功能
获取指定页对象。
参数
index
返回值
local page_object = tabview:get_content(index)
page_object
示例
4.2.7.4 tabview:set_on_change(callback)
功能
监听页变化。
参数
callback
返回值
无
示例
4.2.7.5 tabview:destroy()
功能
销毁组件。
参数
无
返回值
无
示例
4.2.8 窗口（airui.win）
4.2.8.1 airui.win(config)
功能
创建带标题的浮动窗口，可注册关闭回调。
参数
config
返回值
local win_object = airui.win(config)
win_object
示例
4.2.8.2 win:set_title(title)
功能
更新窗口标题。
参数
title
返回值
无
示例
4.2.8.3 win:add_content(child)
功能
将子组件添加到窗口内容区域。
参数
child
返回值
无
示例
4.2.8.4 win:close()
功能
关闭窗口，触发 on_close 回调。
参数
无
返回值
无
示例
4.2.8.5 win:destroy()
功能
销毁窗口。
参数
无
返回值
无
示例
4.2.9 下拉框（airui.dropdown）
4.2.9.1 airui.dropdown(config)
功能
实现可滚动选择列表，支持 change 回调。
参数
config
返回值
local dropdown_object = airui.dropdown(config)
dropdown_object
示例
4.2.9.2 dropdown:set_selected(index)
功能
设置当前选中项。
参数
index
返回值
无
示例
4.2.9.3 dropdown:get_selected()
功能
获取当前选中项。
参数
无
返回值
local selected_index = dropdown:get_selected()
selected_index
示例
4.2.9.4 dropdown:set_on_change(callback)
功能
设置选中变动回调。
参数
callback
返回值
无
示例
4.2.9.5 dropdown:destroy()
功能
销毁下拉框组件。
参数
无
返回值
无
示例
4.2.10 开关（airui.switch）
4.2.10.1 airui.switch(config)
功能
提供 boolean 状态切换弹性控件，可绑定风格与 change 回调。
参数
config
返回值
local switch_object = airui.switch(config)
switch_object
示例
4.2.10.2 switch:set_state(state)
功能
设置开关状态。
参数
state
返回值
无
示例
4.2.10.3 switch:get_state()
功能
获取当前开关状态。
参数
无
返回值
local current_state = switch:get_state()
current_state
示例
4.2.10.4 switch:set_on_change(callback)
功能
设置开关状态变化回调。
参数
callback
返回值
无
示例
4.2.10.5 switch:destroy()
功能
销毁开关。
参数
无
返回值
无
示例
4.2.11 消息框（airui.msgbox）
4.2.11.1 airui.msgbox(config)
功能
创建可定时关闭的模态消息框，可动态 show/hide。
参数
config
返回值
local msgbox_object = airui.msgbox(config)
msgbox_object
示例
4.2.11.2 msgbox:show()
功能
显示消息框。
参数
无
返回值
无
示例
4.2.11.3 msgbox:hide()
功能
隐藏消息框。
参数
无
返回值
无
示例
4.2.11.4 msgbox:set_on_action(callback)
功能
设置按钮回调。
参数
callback
返回值
无
示例
4.2.11.5 msgbox:destroy()
功能
释放消息框资源。
参数
无
返回值
无
示例
4.2.12 文本输入（airui.textarea）
4.2.12.1 airui.textarea(config)
功能
创建文本输入框，输入框支持占位、自动绑定键盘和监听文本变化。
参数
config
返回值
local textarea_object = airui.textarea(config)
textarea_object
示例
4.2.12.2 textarea:set_text(text)
功能
设置输入框文本内容。
参数
text
返回值
无
示例
4.2.12.3 textarea:get_text()
功能
获取输入框当前内容。
参数
无
返回值
local text_content = textarea:get_text()
text_content
4.2.12.4 textarea:set_cursor(pos)
功能
调整光标位置。
参数
pos
返回值
无
示例
4.2.12.5 textarea:set_on_text_change(fn)
功能
设置输入框内容变化回调。
参数
fn
返回值
无
示例
4.2.12.6 textarea:attach_keyboard(keyboard)
功能
将输入框关联键盘。
参数
keyboard
返回值
无
示例
4.2.12.7 textarea:get_keyboard()
功能
获取输入框绑定键盘。
参数
无
返回值
local keyboard_object = textarea:get_keyboard()
keyboard_object
示例
4.2.12.8 textarea:destroy()
功能
销毁输入框。
参数
无
返回值
无
示例
4.2.13 键盘（airui.keyboard）
4.2.13.1 airui.keyboard(config)
功能
虚拟键盘，支持多模式与自动隐藏、绑定目标 textarea。
参数
config
返回值
local keyboard_object = airui.keyboard(config)
keyboard_object
示例
4.2.13.2 keyboard:set_target(textarea)
功能
指定关联的 textarea。
参数
textarea
返回值
无
示例
4.2.13.3 keyboard:show()
功能
显示键盘。
参数
无
返回值
无
示例
4.2.13.4 keyboard:hide()
功能
隐藏键盘。
参数
无
返回值
无
示例
4.2.13.5 keyboard:set_on_commit(fn)
功能
设置键盘提交回调。
参数
fn
返回值
无
示例
4.2.13.6 keyboard:set_layout(name)
功能
更换键盘布局。
参数
name
返回值
无
示例
4.2.13.7 keyboard:set_bg_color(color)
功能
设置背景颜色。
参数
color
返回值
无
示例
4.2.13.8 keyboard:get_target()
功能
返回当前绑定的 textarea。
参数
无
返回值
local target_object = keyboard:get_target()
target_object
示例
4.2.13.9 keyboard:destroy()
功能
销毁键盘组件。
参数
无
返回值
无
示例
4.3 LuatOS windows桌面系统专用接口和组件
4.3.1 系统键盘支持接口
3.3.1.1 airui.keyboard_enable_system(enabled)
功能
在 LuatOS windows桌面系统 上打开键盘输入法，支持实体键盘输入，而不是虚拟键盘输入。
参数
enabled
返回值
local enable_result = airui.keyboard_enable_system(enabled)
enable_result
示例
4.3.2 Lottie 动画组件
4.3.2.1 airui.lottie(config)
功能
配置 Lottie 动画，支持文件/内联数据、循环与速率配置。当前仅LuatOS windows桌面系统运支持，真机后续计划支持。
参数
config
返回值
local lottie_object = airui.lottie(config)
lottie_object
示例
4.3.2.2 Lottie:play()
功能
开始播放动画。
参数
无
返回值
无
示例
4.3.2.3 Lottie:pause()
功能
暂停播放。
参数
无
返回值
无
示例
4.3.2.4 Lottie:stop()
功能
停止并重置动画。
参数
无
返回值
无
示例
4.3.2.5 Lottie:set_src(source)
功能
更新动画源。
参数
source
返回值
无
示例
4.3.2.6 Lottie:set_speed(speed)
功能
设置播放速率。
参数
speed
返回值
无
示例
4.3.2.7 Lottie:set_loop(loop)
功能
控制是否循环播放。
参数
loop
返回值
无
示例
4.3.2.8 Lottie:set_progress(progress)
功能
设置动画进度。
参数
progress
返回值
无
示例
4.3.2.9 Lottie:destroy()
功能
销毁动画资源。
参数
无
返回值
无
示例
4.4 XML 组件介绍
4.4.1 XML 系列接口
功能
AirUI 提供 XML 层的封装，支持从文件或字符串注册 XML 资源、绑定事件、创建屏幕、注册图片/字体，并可将键盘/textarea 关联到 XML 组件。
4.4.1.2 xml_init()
功能
初始化 LVGL XML 子系统，保证后续接口可用。
参数
无
返回值
无（函数内部总是成功）
示例
4.4.1.3 xml_deinit()
功能
释放 XML 子系统占用的资源，并清理运行时状态。
参数
无
返回值
无
示例
4.4.1.4 xml_register_from_file(path)
功能
通过文件路径加载并注册 XML 内容，支持后续通过名字实例化。
参数
path
返回值
local register_result = xml_register_from_file(path)
register_result
示例
4.4.1.5 xml_register_from_data(name, data)
功能
直接从内存字符串注册 XML 内容，适合内嵌或压缩资源。
参数
name
data
返回值
local register_result = xml_register_from_data(name, data)
register_result
示例
4.4.1.6 xml_register_image(name, src)
功能
提前注册 XML 中使用的图片资源，使
能成功解析。
参数
name
src
返回值
local register_result = xml_register_image(name, src)
register_result
示例
4.4.1.7 xml_register_font(name, font)
功能
将字体指针绑定到 XML 名称，便于解析 。
参数
name
font
返回值
local register_result = xml_register_font(name, font)
register_result
示例
4.4.1.8 xml_create_screen(name)
功能
根据注册时的名称创建 XML 描述的屏幕并返回容器对象，供 Lua 代码进一步操作。
参数
name
返回值
local screen_object = xml_create_screen(name)
screen_object
示例
4.4.1.9 xml_bind_event(name, event_code, cb)
功能
为 XML 定义的控件绑定 LVGL 事件，并将事件回调转发到 Lua（回调通过 registry 机制保存）。
参数
name
event_code
cb
返回值
local bind_result = xml_bind_event(name, event_code, cb)
bind_result
示例
4.4.1.10 xml_keyboard_bind(kb_name, textarea_name)
功能
将 XML 中的键盘与输入框关联，自动在 focus/defocus 时切换目标 textarea。
参数
kb_name
textarea_name
返回值
local bind_result = xml_keyboard_bind(kb_name, textarea_name)
bind_result
示例
4.4.2 完整 XML 示例
五、AirUI 更新说明
AirUI V 1.0.1 目前 AirUI PC 端已适配，嵌入式端还需配套固件
更新时间：2026-02-03
更新接口：
airui.indev_bind_touch(tp_cfg) 改为 airui.device_bind_touch(tp_cfg)
airui.font_load(config)接口中新增 load_to_psram 参数
airui.label(config)接口中新增 size 和 color 参数
新增 label:set_font_size(size)子方法
新增 label:set_color(color)子方法
airui.keyboard(config)接口中新增 bg_color 参数
新增 keyboard:set_bg_color(color)子方法
更新常量：去除常量中的 AIRUI_ 部分
其他更新：
优化拼音表排序，常规字放前面，多音字放后面
img 图片组件拦截 jpg 图片设置透明度和大小缩放
优化内存分配逻辑，提高资源利用率
AirUI V 1.0.0
更新时间：2026-01-28
更新内容：
首次推出 AirUI
支持 label、image、button、switch、bar、dropdown、textarea、keyboard、table、container、tabview、win 等核心组件，支持 hzfont、xml 导入、AirUI PC 端。
今天的内容就分享到这里了~
浙公网安备 33010602011771号