洛汐文档库

外观

LVGL 控件与属性

约 541 字大约 2 分钟

2026-07-15

创建语法

两种写法等价：

local image1 = lvgl.Image(parent, { src = "asset/a.bin" })
local image2 = parent:Image { src = "asset/b.bin" }

所有控件继承 Object，可在构造时传属性，也可稍后批量设置：

obj:set { x = 10, y = 20, hidden = false }

Object 属性

分类属性
几何x、y、w、h、align、min_width、max_width、min_height、max_height
背景bg_color、bg_opa、bg_img_src、bg_img_opa、bg_img_recolor、bg_img_recolor_opa、bg_img_tiled
边框border_width、border_color、border_opa、border_side、border_post
外轮廓outline_width、outline_color、outline_opa、outline_pad
阴影shadow_width、shadow_color、shadow_opa、shadow_ofs_x、shadow_ofs_y、shadow_spread
内边距pad_all、pad_top、pad_bottom、pad_left、pad_right、pad_row、pad_column、pad_gap
变换transform_zoom、transform_angle、transform_pivot_x、transform_pivot_y、translate_x、translate_y
文本text_color、text_opa、text_font、text_letter_space、text_line_space、text_decor、text_align
其他radius、opa、clip_corner、blend_mode、scrollbar_mode、scroll_snap_x、scroll_snap_y

Object 方法

分类方法
生命周期delete、clean、get_parent、set_parent、get_child、get_child_cnt、get_screen
样式set_style、add_style、remove_style、remove_style_all
几何align_to、center、invalidate、get_coords、get_pos
状态get_state、add_flag、clear_flag、add_state、clear_state、is_visible
滚动scroll_to、scroll_by、scroll_by_bounded、scroll_by_raw、scroll_to_view、scroll_to_view_recursive、is_scrolling、readjust_scroll
布局set_flex_flow、set_flex_align、set_flex_grow、mark_layout_as_dirty、is_layout_positioned
事件onevent、onPressed、onClicked、indev_search
动画anim / Anim、remove_all_anim

标准控件

控件主要属性专用方法
Imagesrc、zoom、angle、pivot、offset_x、offset_yset_src、set_offset、set_pivot、get_img_size
Labeltext、long_mode、文本样式set_text_static、get_text、get_long_mode、ins_text、cut_text
Ledbrightnesson、off、toggle、get_brightness
List列表样式add_text、add_btn、get_btn_text
Textareatext、placeholder、password_mode、password_bullet、accepted_chars、max_length、one_lineget_text、remove_prop
Dropdownoptions、selectedget_options、get_selected、get_selected_str、get_options_cnt、is_open、add_option、clear_option
Calendar日期属性get_today、get_showed、get_pressed、get_btnm
Checkboxtext、checked stateObject 状态方法
Keyboardmode、textarea通过属性绑定 Textarea
Rolleroptions、selected、visible_cnt通用 set 与选择读取

扩展控件

AnalogTime

local clock = root:AnalogTime {
  hands = { second = image("second.bin") },
  period = 33,
  w = 466, h = 466,
  align = lvgl.ALIGN.CENTER,
}

clock:set { pivot = { second = { 16, 232 } } }
clock:set { fake_time = { second = 30 } }
clock:pause()
clock:resume()

属性：hands.hour/minute/second、pivot、period、fake_time。

Pointer

local pointer = root:Pointer {
  range = {
    valueStart = 0, valueRange = 100,
    angleStart = -120, angleRange = 240,
  },
  value = 75,
}

CurvedLabel

属性：text、radius、angle_start、angle_range、font、text_color。

ImageLabel

属性包括 src、text、font、suffix、spacing 与文本样式。

ImageBar

范围属性包括 center_x、center_y、linecap、bar_width、value 和进度映射参数。

ImageLineBar

范围属性包括 start_x、start_y、end_x、end_y、value 和图片源。

Thumbnail

用于缩略图预览，支持 src 以及 Object 通用属性和事件。

事件示例

button:onClicked(function(obj, code)
  print("clicked", obj, code)
end)

button:onevent(lvgl.EVENT.PRESSED, function(obj, code)
  print("pressed", code)
end)

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
✅✅

获取源代码