外观
LVGL 辅助模块
约 838 字大约 3 分钟
2026-07-15
除控件外，Lua 绑定还提供 Timer、Group、输入设备、文件系统、颜色和字体等模块。
Timer
local timer = lvgl.Timer {
period = 1000,
repeat_count = -1,
cb = function(timer)
print("tick")
end,
}
timer:pause()
timer:resume()
timer:set { period = 500 }
timer:ready()
timer:delete()| 成员 | 说明 |
|---|---|
period | 触发周期，毫秒 |
repeat_count | 剩余次数；-1 表示无限 |
cb | 定时回调 |
pause / resume | 暂停和恢复 |
set | 更新 period、paused、repeat_count 或 cb |
ready | 令定时器尽快执行一次 |
delete | 删除定时器 |
Group
local group = lvgl.Group.create()
group:add_obj(object)
group:focus_obj(object)
group:set_editing(true)
group:set_wrap(true)模块函数：get_default、create。
对象方法：delete、set_default、add_obj、remove_obj、remove_objs、focus_obj、focus_next、focus_prev、focus_freeze、send_data、set_focus_cb、set_edge_cb、get_focus_cb、get_edge_cb、set_editing、set_wrap、get_wrap、get_obj_count、get_focused。
输入设备
模块函数：
lvgl.indev.get_act()
lvgl.indev.get_next([indev])
lvgl.indev.get_obj_act()输入设备对象提供：
| 方法 | 说明 |
|---|---|
get_type | 输入设备类型 |
reset | 重置输入状态 |
reset_long_press | 清除长按状态 |
set_cursor | 设置指针光标对象 |
set_group | 绑定 Group |
get_point | 当前触点坐标 |
get_gesture_dir | 当前手势方向 |
get_key | 当前按键值 |
get_scroll_dir | 滚动方向 |
get_scroll_obj | 当前滚动对象 |
get_vect | 输入移动向量 |
wait_release | 等待松开 |
on_event | 注册输入设备事件 |
返回坐标或向量时，宿主可能返回 table 或多个数值。调用方可先打印返回值形态，再做兼容封装。
屏幕与显示
| 函数 | 说明 |
|---|---|
lvgl.disp.get_default() | 默认显示设备 |
lvgl.disp.get_next([display]) | 遍历显示设备 |
lvgl.disp.get_scr_act(display) | 当前活动 screen |
lvgl.disp.get_scr_prev(display) | 上一个 screen |
lvgl.disp.load_scr(screen [, options]) | 切换 screen |
显示设备对象提供 get_res、set_rotation、get_layer_top、get_layer_sys、get_next、set_bg_opa、set_bg_color、set_bg_image 和 get_chroma_key_color。
切屏参数：
lvgl.disp.load_scr(screen, {
anim = "over_left",
time = 500,
delay = 0,
auto_del = 1,
})HOR_RES、VER_RES 在部分脚本中是函数，在部分模拟环境中是数值。可统一读取：
local function constValue(value)
return type(value) == "function" and value() or value
end
local width = constValue(lvgl.HOR_RES)
local height = constValue(lvgl.VER_RES)颜色
颜色属性通常接受十六进制整数：
label:set {
text_color = 0xffffff,
bg_color = 0x000000,
}透明度使用 lvgl.OPA 常量或数值。常见常量包括 TRANSP、COVER 以及分级透明度值。
字体
字体构造：
lvgl.Font(name [, size [, weight]]) -> light userdata已验证的名称包括 montserrat；常见尺寸为 14、16、18、24、32，weight 可用 normal。字体可作为 text_font 属性传入：
label:set { text_font = font }系统字体对象和资源字体的加载方式取决于表盘包。不要把宿主字体指针保存到页面销毁之后。
文件与目录 userdata
目录接口：
local dir = lvgl.fs.open_dir(path)
local name = dir:read()
dir:close()文件接口：
local file = lvgl.fs.open_file(path, mode)
local data = file:read(size)
file:seek(offset, whence)
file:write(data)
file:close()mode 支持 "r" 和 "w"。文件的 read 支持整数长度与 "*a"，不支持 "*l"、"*n"；seek 的 whence 为 "set"、"cur" 或 "end"。
文件与目录对象实现 __gc、__close、__tostring、__index。仍应显式 close()，因为表盘 Lua state 可能长期不触发垃圾回收。
常量组
常用分组包括：
lvgl.ALIGN：对象对齐；lvgl.FLAG：对象标志；lvgl.STATE：对象状态；lvgl.PART：控件部件；lvgl.EVENT：事件码；lvgl.FLEX_FLOW、lvgl.FLEX_ALIGN：Flex 布局；lvgl.LABEL_LONG：长文本模式；lvgl.OPA：透明度；lvgl.DIR：方向；lvgl.ANIM：动画开关或类型。
特殊值包括 ANIM_REPEAT_INFINITE、ANIM_PLAYTIME_INFINITE、SIZE_CONTENT、RADIUS_CIRCLE、COORD_MAX、COORD_MIN、IMG_ZOOM_NONE、BTNMATRIX_BTN_NONE、CHART_POINT_NONE、DROPDOWN_POS_LAST、LABEL_POS_LAST、TEXTAREA_CURSOR_LAST、LAYOUT_FLEX、LAYOUT_GRID。
机型可用性
| 模块 | Xiaomi Smart Band 10 Pro | Xiaomi Watch S4 41mm |
|---|---|---|
| Timer | ✅ | ✅ |
| Group 与输入设备 | ✅ | ✅ |
| 显示辅助函数 | ✅ | ✅ |
| 文件与目录 userdata | ✅ | ✅ |