LVGL-常用组件

2026-03-20

Edit this page

LVGL库提供了一系列组件，用于构建用户界面的基本元素。这些组件包括但不限于按钮、标签、文本框、列表、滑块、图表等。每个组件都具有独特的功能和样式，开发者可以通过设置属性和样式来定制它们的外观和行为，以满足特定应用场景的需求。

以下介绍LVGL常用组件，使用以下组件可以实现绝大部分界面需求。若需了解所有的组件及其API说明，可以访问LVGL官网查看。

LVGL基础对象

概述-LVGL

基础对象实现了屏幕上组件的基本属性，例如：

坐标
父对象
基于父对象的后代
包含样式
诸如可点击(Clickable)、可滚动(Scrollable) 等属性。

基础对象是 LVGL 中所有组件的基类，其他组件对象均继承自基础对象。

基础对象可以直接用作一个简单的组件：它就是一个矩形。在没有指定父类对象的时候，一个基础对象就独自构成一个LVGL界面。在指定父类对象的时候，它是一个容器。

坐标(Coordinates)

大小(Size)

您可以使用set_width(new_width)和set_height(new_height)设置或修改单个轴上的对象大小，或者可以使用set_size(new_width, new_height)同时修改两个轴。

位置(Position)

您可以使用set_x(new_x)和set_y(new_y)设置相对于父级的位置，或者使用set_pos(new_x, new_y)来同时设置两个轴的位置。

对齐(Alignment)

可以使用设置align(对齐)设置一个控件相对于父容器的对齐方式，Quecpython接口有下面两个:

obj.align(lvgl.ALIGN.type,x,y)
obj.set_align(lvgl.ALIGN.type)

如果设置居中,有快捷接口obj.center()

LVGL支持的对齐方式见下图：

例如，以下代码会将对象从其父对象的中心移动 10(x)，20(y) 像素：

import lvgl as lv

obj = lv.obj(lv.scr_act())

obj.set_align(lv.ALIGN.CENTER);
obj.set_pos(10, 20);

//Or in one function
obj.align(lv.ALIGN.CENTER, 10, 20);

父对象和子对象(Parents and children)

除了界面对象，所有LVGL组件对象都有父对象。

父对象和子对象具有以下特点：

一起移动
子对象仅在父对象范围可见

组件对象在创建的时候，就需要指定父级对象。您可以使用 obj.set_parent(new_parent)为对象设置新的父级。要获取当前父级，请使用 obj.get_parent()。

要获取父对象的特定子对象，请使用obj.get_child(idx)。 idx 的一些示例：

0 获取创建的第一个子对象
1 获取创建的第二个子对象
-1 获取最后创建的子对象

父级的子对象们可以这样迭代：

for i in range(obj.get_child_cnt()):
    child_obj = obj.get_child(i)

obj.get_index()返回对象在其父对象中的索引。

您可以使用obj.move_foreground()和obj.move_background()将对象移到前台或将其移到后台。

显示和屏幕(Display and Screens)

在 LVGL 中，对象层次结构的最高级别是 display，它代表显示设备（物理显示器或模拟器）的驱动程序，LVGL与显示设备的关联在前面的章节已有描述，不做赘述。一个显示器可以有一个或多个与其相关联的界面。每个界面都包含图形组件的对象层次结构。

当你创建了一个像screen = lv.obj()这样的界面对象时，你可以用lv.scr_load(screen)激活它。

lv.scr_act() 函数为当前活动的界面对象。

事件(Events)-LVGL

要为对象设置事件回调，请使用 obj.add_event_cb(event_cb, lv.EVENT.type, user_data)，

要手动向对象发送事件，请使用 lv.event_send(obj, lv.EVENT.type, param)

请阅读事件概述章节，以了解有关事件的更多信息。

样式(Styles)

可以使用obj.add_style(new_style, selector)函数向对象添加新样式。

selector可以组合使用。例如：lv.PART.SCROLLBAR | lv.STATE.PRESSED。

基础对象的selector使用lv.PART.MAIN和lv.PART.SCROLLBAR。

请阅读样式概述章节详细了解。

宏开关(Flags)

有一些属性可以通过obj.add/clear_flag(lv.obj.FLAG.type)启用/禁用。lv.obj.FLAG.type见API常量。

API

注意：本章节只介绍了一些常见API，如需查看所有API，可以访问LVGL官网查看。

以下描述均默认import lvgl as lv。

构造函数-LVGL

`lv.obj(parent)`

创建一个基础对象(矩形)。

参数描述：

parent - 父对象，object类型，不指定则创建的是界面对象。

方法-LVGL

`obj.add_style(style_obj,selector)`

给对象添加样式。

参数描述：

style_obj - 样式对象，style_obj类型，要添加的样式。
selector - 选择器，常量，要添加样式的部分及状态，可以组合使用。例如：lv.PART.SCROLLBAR | lv.STATE.PRESSED。

`obj.add_flag(type)`

给对象添加宏开关。

参数描述：

type - flag类型，常量，要添加的宏开关类型，可以一个或多个类型。

`obj.clear_flag(type)`

清除对象的宏开关。

参数描述：

type - flag类型，常量，要清除的宏开关类型，可以多个类型。

`obj.add_state(state)`

向对象添加一个或多个状态。其他状态位将保持不变。如果在样式中指定，则过渡动画将从以前的状态开始到当前状态。

参数描述：

state - state类型，常量，要添加的状态类型，可以一个或多个状态。

`obj.clear_state(state)`

删除对象的一个或多个状态。其他状态位将保持不变。如果在样式中指定，则过渡动画将从以前的状态开始到当前状态。

参数描述：

state - state类型，常量，要清除的状态类型，可以一个或多个状态。

`obj.get_state()`

获取对象的状态。

常量-LVGL

`flag`

宏开关

lv.obj.FLAG.HIDDEN 隐藏对象
lv.obj.FLAG.CLICKABLE 使输入设备可点击对象
lv.obj.FLAG.CLICK_FOCUSABLE 单击时将焦点状态添加到对象
lv.obj.FLAG.CHECKABLE 对象被点击时切换选中状态
lv.obj.FLAG.SCROLLABLE 使对象可滚动
lv.obj.FLAG.SCROLL_ELASTIC 允许在内部滚动但速度较慢
lv.obj.FLAG.SCROLL_MOMENTUM 在“抛出”时使对象滚动得更远
lv.obj.FLAG.SCROLL_ONE 只允许滚动一个可捕捉的子对象
lv.obj.FLAG.SCROLL_CHAIN 允许将滚动传播到父级
lv.obj.FLAG.SCROLL_ON_FOCUS 自动滚动对象以使其在聚焦时可见
lv.obj.FLAG.SNAPPABLE 如果在父对象上启用了滚动捕捉，它可以捕捉到这个对象
lv.obj.FLAG.PRESS_LOCK 保持对象被按下，即使按下从对象上滑动
lv.obj.FLAG.EVENT_BUBBLE 也将事件传播给父级
lv.obj.FLAG.GESTURE_BUBBLE 将手势传播给父级
lv.obj.FLAG.ADV_HITTEST 允许执行更准确的命中（点击）测试。例如。考虑圆角。
lv.obj.FLAG.IGNORE_LAYOUT 使对象可以通过布局定位
lv.obj.FLAG.FLOATING 父滚动时不滚动对象，忽略布局

`PART`

lv.PART.MAIN 类似矩形的背景
lv.PART.SCROLLBAR 滚动条部分
lv.PART.INDICATOR 指示部分，例如用于圆弧、条、开关或复选框的勾选框
lv.PART.KNOB 向圆弧的帽子部分
lv.PART.SELECTED 表示当前选择的选项或部分
lv.PART.ITEMS 如果小部件有多个相似的元素（例如表格单元格）
lv.PART.TICKS 刻度上的刻度，例如对于图表或仪表
lv.PART.CURSOR 标记一个特定的地方，例如文本区域或图表的光标
lv.PART.CUSTOM_FIRST 可以从这里添加自定义部件。

`state`

lv.STATE.DEFAULT 正常, 释放状态默认状态
lv.STATE.CHECKED 切换或者选中状态
lv.STATE.FOCUSED 被按键或者编码器聚焦/被触摸屏或鼠标点击
lv.STATE.FOCUS_KEY 被按键或者编码器聚焦但不是被触摸屏或鼠标点击
lv.STATE.EDITED 被编码器编辑
lv.STATE.HOVERED 鼠标悬停（暂不支持）
lv.STATE.PRESSED 被按住
lv.STATE.SCROLLED 正在滚动
lv.STATE.DISABLED 失效状态

`flex-flow`

lv.FLEX_FLOW.ROW 将子对象排成一行而换行
lv.FLEX_FLOW.COLUMN 将子对象放在一列中而不换行
lv.FLEX_FLOW.ROW_WRAP 将子对象排成一排,不超过父容器的宽,否则换行
lv.FLEX_FLOW.COLUMN_WRAP 将子对象放成一列，不超过父容器的高，否则换行
lv.FLEX_FLOW.ROW_REVERSE 将子对象排成一行而不换行，但顺序相反
lv.FLEX_FLOW.COLUMN_REVERSE 将子对象放在一列中，不换行，但顺序相反
lv.FLEX_FLOW.ROW_WRAP_REVERSE 将子对象排成一行而不换行，但顺序相反
lv.FLEX_FLOW.COLUMN_WRAP_REVERSE 将子对象放在一列中，不换行，但顺序相反

标签(label)

概述-label

标签是用来显示文本的对象类型。

部分和风格(Parts and Styles)-label

lv.PART.MAIN表示整个背景和文本部分。填充值可用于在文本和背景之间添加间隙。
lv.PART.SCROLLBAR 当文本大于组件的大小时显示的滚动条。
lv.PART.SELECTED 表示所选文本的部分。只能使用 text_color 和 bg_color 样式属性。

用法(Usage)-label

设置文本(Set text)

您可以在LVGL运行时使用 label.set_text("New text") 设置标签上的文本。

换行符由标签对象自动处理。您可以使用 \n 来换行。例如："line1\nline2\n\nline4"

长模式(long mode)

默认情况下，标签的大小会自动扩展到文本大小。如果显式设置宽度或高度（使用例如label.set_size 或布局），则可以根据几种长模式策略来操作比标签宽度更宽的行。类似地，如果文本的高度大于标签的高度，则可以应用策略。

lv.label.LONG.WRAP 文本太长，将被剪裁。（默认）
lv.label.LONG.DOT 将标签右下角的最后 3 个字符替换为点 (.)
lv.label.LONG.SCROLL 如果文本比标签宽，则水平来回滚动它。如果它更高，垂直滚动。只滚动一个方向，水平滚动的优先级更高。
lv.label.LONG.SCROLL_CIRCULAR 如果文本比标签宽，则水平滚动它。如果它更高，请垂直滚动。只滚动一个方向，水平滚动的优先级更高。
lv.label.LONG.CLIP 只需剪掉标签外的文本部分。

您可以使用 label.set_long_mode(type) 指定长模式。

事件(Events)-label

标签组件不发送特殊事件。

可以使用lv.obj.FLAG.CLICKABLE 使标签变成可点击对象，这样它近似于一个透明的按钮，可以添加点击事件。

API-label

注意：本章节只介绍了一些常见API，如需查看所有API，可以访问LVGL官网查看。

构造函数-label

`lv.label(parent)`

创建一个标签。

参数描述：

parent - 父对象，object类型，必填。

方法-label

`label.set_text(text)`

给标签设置显示文本。

参数描述：

text - 文本内容，string类型，要显示的文本。

`label.set_long_mode(type)`

给标签设置长文本模式。

参数描述：

type - 模式，常量，长文本模式。

`label.get_text()`

获取标签的显示文本。

返回值描述：

text - 文本内容，string类型，显示的文本。

常量-label

`LONG`

长文本模式

lv.label.LONG.WRAP 文本太长，将被剪裁。（默认）
lv.label.LONG.DOT 将标签右下角的最后 3 个字符替换为点 (.)
lv.label.LONG.SCROLL 如果显示文本比标签宽，则水平来回滚动它。如果它更高，垂直滚动。只滚动一个方向，水平滚动的优先级更高。
lv.label.LONG.SCROLL_CIRCULAR 如果文本比标签宽，则水平滚动它。如果它更高，垂直滚动。只滚动一个方向，水平滚动的优先级更高。
lv.label.LONG.CLIP 只需剪掉标签外的文本部分。

图像(image)

概述-image

图像是显示来自闪存（作为数组）或来自文件的图像的基本对象。图像也可以显示符号（lv.SYMBOL....）。

部分和风格(Parts and Styles)-image

lv.PART.MAIN表示整个背景和图像部分。

用法(Usage)-image

图片来源(Image source)

为了提供最大的灵活性，图像的来源可以是：

文件系统的文件。
Symbols图标。

要设置图像的来源，请使用img.set_src(src)。

要使用文件系统的文件，请将图片文件下载至文件系统，使用img.set_src("U:/my_img.jpg")。

您还可以设置类似于标签的符号。在这种情况下，图像将根据样式中指定的 font 呈现为文本。它其实是一个轻量级单色“字母”而不是真实图像。你可以设置像img.set_src(lv.SYMBOL.OK)这样的符号。

转换(Transformations)-image

使用 img.set_zoom(factor) 图像将被缩放。将 factor 设置为 256 为原图大小。较大的值会放大图像（例如“512”双倍尺寸），较小的值会缩小图像（例如“128”半尺寸）。分数尺度也有效。例如。 281 放大 10%。

要旋转图像，请使用 img.set_angle(angle)。角度的精度为 0.1 度，因此对于 45.8° 设置 458。

默认情况下，旋转的轴心点是图像的中心。它可以通过 img.set_pivot(pivot_x, pivot_y) 改变。 0;0 是左上角。

转换的质量可以通过 img.set_antialias(True/False) 来调整。启用抗锯齿后，转换质量更高但速度更慢。

请注意，图像对象的真实坐标在转换过程中不会改变。即obj.get_width/height/x/y() 将返回原始的、未缩放的坐标。

事件(Events)-image

图像组件不发送特殊事件。

可以使用lv.obj.FLAG.CLICKABLE 使标签变成可点击对象，这样它近似于一个图像按钮，可以添加点击事件。

注意：图像组件能使用图片缓存机制，所以相较于图像按钮组件，更推荐使用图像组件。

API-image

注意：本章节只介绍了一些常见API，如需查看所有API，可以访问LVGL官网查看。

构造函数-image

`lv.img(parent)`

创建一个图像。

参数描述：

parent - 父对象，object类型，必填。

方法-image

`img.set_src(src)`

给图像设置图像源。

参数描述：

src - 1)图像文件的路径，string类型，要显示的图像的路径。2)SYMBOL，例如lv.SYMBOL.OK

`img.set_offset_x(x)`

为图像的源设置x轴偏移，以便从新原点显示图像。

参数描述：

x - x轴偏移，int类型。

`img.set_offset_y(y)`

为图像的源设置y轴偏移，以便从新原点显示图像。

参数描述：

y - y轴偏移，int类型。

`img.set_angle(angle)`

图像设置旋转角度。

参数描述：

angle - 角度，int类型，精度为0.1度。

`img.set_zoom(factor)`

图像设置缩放大小。

参数描述：

factor - 缩放程度，int类型，256为原图大小，512双倍尺寸。

`img.set_pivot(x,y)`

设置图像的旋转中心，图像将围绕此点旋转。

参数描述：

x - 旋转中心x轴坐标，int类型。
y - 旋转中心y轴坐标，int类型。

`img.set_antialias(antialias)`

是否启用/禁用变换的抗锯齿（旋转、缩放）。抗锯齿效果更好，但速度较慢。

参数描述：

antialias - 抗锯齿，bool类型，True为使能，False为禁止。

按钮(Button)

概述-Button

与基础对象相比，按钮没有新功能。它们可用于语义目的，并且默认设置略有不同。

默认情况下，按钮在以下方面与基础对象不同：

不可滚动
添加到默认组
默认高度和宽度设置为 LV_SIZE_CONTENT

部分和风格(Parts and Styles)-Button

lv.PART.MAIN表示按钮的背景部分。

用法(Usage)-Button

与基础对象相比，按钮没有新功能

事件(Events)-Button

当对象被点击时有选中切换(Toggle)状态的效果，并且可以在 lv.EVENT.VALUE_CHANGED 事件类型中处理事件。

请注意，lv.KEY.ENTER 的状态被转换为 lv.EVENT.PRESSED/PRESSING/RELEASED 等。

参见基础对象的事件。

API-Button

注意：本章节只介绍了一些常见API，如需查看所有API，可以访问LVGL官网查看。

构造函数-Button

`lv.btn(parent)`

创建一个按钮。

参数描述：

parent - 父对象，object类型，必填。

LVGL其他组件

除了上述介绍的组件，LVGL还提供以下组件，项目中选择使用哪种组件请视需求而定。

组件	构造函数	说明	LVGL官网链接
列表	`lv.list()`	一个垂直布局的矩形，可以向其中添加按钮和文本	点击此处查看组件详细信息
窗口	`lv.win()`	由一个带有标题、按钮和内容区域的标题构建而成的容器	点击此处查看组件详细信息
弧	`lv.acr()`	圆弧由背景和前景弧组成。前景（指示器）可以进行触摸调整	点击此处查看组件详细信息
进度条	`lv.bar()`	显示进度	点击此处查看组件详细信息
开关	`lv.switch()`	看起来像一个小滑块，开关的功能类似于按钮，也可以用来打开和关闭某些东西	点击此处查看组件详细信息
滑动页	`lv.tileview()`	菜单页可用，比较界面切换的动画，多出了手指跟随的效果	点击此处查看组件详细信息
仪表盘	`lv.meter()`	以非常灵活的方式可视化数据。在中可以显示圆弧、指针、刻度线和标签	点击此处查看组件详细信息
图表	`lv.chart()`	折线图，直方图，散点图	点击此处查看组件详细信息
键盘	`lv.keyboard()`	特殊的按钮矩阵，自身实现了按键映射	点击此处查看组件详细信息
菜单	`lv.menu()`	多级菜单，它自动处理页面之间的遍历	点击此处查看组件详细信息

LVGL工作流程

LVGL简单示例

QuecPython

LVGL-常用组件

LVGL基础对象

概述-LVGL

坐标(Coordinates)

大小(Size)

位置(Position)

对齐(Alignment)

父对象和子对象(Parents and children)

显示和屏幕(Display and Screens)

事件(Events)-LVGL

样式(Styles)

宏开关(Flags)

API

构造函数-LVGL

lv.obj(parent)

方法-LVGL

obj.add_style(style_obj,selector)

obj.add_flag(type)

obj.clear_flag(type)

obj.add_state(state)

obj.clear_state(state)

obj.get_state()

常量-LVGL

flag

PART

state

flex-flow

标签(label)

概述-label

部分和风格(Parts and Styles)-label

用法(Usage)-label

设置文本(Set text)

长模式(long mode)

事件(Events)-label

API-label

构造函数-label

lv.label(parent)

方法-label

label.set_text(text)

label.set_long_mode(type)

label.get_text()

常量-label

LONG

图像(image)

概述-image

部分和风格(Parts and Styles)-image

用法(Usage)-image

图片来源(Image source)

转换(Transformations)-image

事件(Events)-image

API-image

构造函数-image

lv.img(parent)

方法-image

img.set_src(src)

img.set_offset_x(x)

img.set_offset_y(y)

img.set_angle(angle)

img.set_zoom(factor)

img.set_pivot(x,y)

img.set_antialias(antialias)

按钮(Button)

概述-Button

部分和风格(Parts and Styles)-Button

用法(Usage)-Button

事件(Events)-Button

API-Button

构造函数-Button

lv.btn(parent)

LVGL其他组件

`lv.obj(parent)`

`obj.add_style(style_obj,selector)`

`obj.add_flag(type)`

`obj.clear_flag(type)`

`obj.add_state(state)`

`obj.clear_state(state)`

`obj.get_state()`

`flag`

`PART`

`state`

`flex-flow`

`lv.label(parent)`

`label.set_text(text)`

`label.set_long_mode(type)`

`label.get_text()`

`LONG`

`lv.img(parent)`

`img.set_src(src)`

`img.set_offset_x(x)`

`img.set_offset_y(y)`

`img.set_angle(angle)`

`img.set_zoom(factor)`

`img.set_pivot(x,y)`

`img.set_antialias(antialias)`

`lv.btn(parent)`