注意

这是最新开发分支配套的文档，可能包含已发布版本中尚未提供的功能。如果您要查看特定版本的文档，请使用左侧的下拉菜单并选择所需要的版本。

LVGL Python API

LVGL Python API#

LVGL (Light and Versatile Graphics Library) Python bindings for K230 平台

自动生成自 LVGL C 头文件，通过 libclang → IR → pybind11 流水线构建。绑定方法/函数 902 个 (.def())，枚举值 651 个，模块常量 65 个，枚举类 96 个，控件 26 个，类 8 个。

快速开始#

LVGL Benchmark Demo

示例	说明	源码
仪表盘 Demo	头像/图表/动画弧形/列表	lvgl_python_benchmark.py
Hello	最小 LVGL 示例 (按钮)	quick_hello.py
摄像头 + OSD	摄像头画面叠加 LVGL 界面	quick_camera_osd.py
摄像头 + 旋转	竖屏适配	quick_camera_rotation.py
中文字体	FreeType 加载 TTF 字体	quick_chinese.py
基础控件	按钮/滑块/进度条/弧形/开关/LED	quick_widgets.py

初始化与驱动#

`lv.init(v4l2_drm=None, v4l2_drm_run_flag=0)`#

K230 平台一键初始化，内部完成：

lv_init() — 初始化 LVGL 库
注册驱动后端
初始化显示后端 (DRM 或 DRM_V4L2_K230)
初始化 EVDEV 输入后端

参数	类型	说明
`v4l2_drm`	`V4l2Drm` 或 `None`	传入 V4l2Drm 对象使用 K230 v4l2-drm 后端 (OSD 与摄像头视频共享 DRM)；`None` 使用标准 Linux DRM 后端
`v4l2_drm_run_flag`	`int`	保留参数，当前未使用，默认 0

`lv.run()`#

进入 LVGL 驱动运行循环 (阻塞)。支持 Ctrl+C 中断，中断后调用 os._exit(0) 退出。

模块级函数#

核心#

函数	说明
`lv.init()`	初始化 LVGL 库
`lv.deinit()`	反初始化 LVGL 库
`lv.is_initialized()`	LVGL 是否已初始化
`lv.timer_handler()`	调用 LVGL 定时器处理 (主循环核心)，返回空闲时间 (ms)
`lv.screen_active()`	获取当前活动屏幕对象
`lv.screen_load(screen)`	加载指定屏幕
`lv.demo_benchmark()`	运行 LVGL 性能基准测试
`lv.pct(n)`	返回百分比宽度/高度值 (用于 `set_width` 等)

版本信息#

函数	说明
`lv.version_major()`	LVGL 主版本号
`lv.version_minor()`	LVGL 次版本号
`lv.version_patch()`	LVGL 补丁版本号
`lv.version_info()`	LVGL 版本信息字符串

显示#

函数	说明
`lv.display_create(w, h)`	创建显示对象
`lv.display_get_default()`	获取默认显示对象
`lv.evdev_create(type, dev)`	创建 EVDEV 输入设备

定时器#

函数	说明
`lv.timer_create(cb, period_ms)`	创建定时器，返回 timer_t 对象

动画#

常量	说明
`lv.ANIM_REPEAT_INFINITE`	动画无限循环值

分组#

函数	说明
`lv.group_create()`	创建输入分组
`lv.group_delete(group)`	删除分组
`lv.group_set_default(group)`	设置默认分组
`lv.group_get_default()`	获取默认分组
`lv.group_add_obj(group, obj)`	将对象加入分组
`lv.group_remove_obj(obj)`	将对象从分组移除
`lv.group_focus_obj(obj)`	聚焦指定对象
`lv.group_focus_next(group)`	聚焦下一个对象
`lv.group_focus_prev(group)`	聚焦上一个对象
`lv.group_set_wrap(group, en)`	设置是否循环聚焦

主题#

函数	说明
`lv.theme_default_init(disp, ...)`	初始化默认主题
`lv.theme_get_color_primary()`	获取主题主色

调色板#

函数	说明
`lv.palette_main(palette)`	获取调色板主色
`lv.palette_lighten(pal, lvl)`	获取调色板亮色
`lv.palette_darken(pal, lvl)`	获取调色板暗色

输入设备#

函数	说明
`lv.indev_create()`	创建输入设备
`lv.indev_get_next(indev)`	获取下一个输入设备
`lv.indev_get_type(indev)`	获取输入设备类型
`lv.indev_set_group(indev, group)`	设置输入设备的分组
`lv.indev_set_type(indev, type)`	设置输入设备类型

驱动后端#

函数	说明
`lv.k230_driver_init(display_ptr, flag)`	K230 驱动初始化 (由 `lv.init()` 内部调用)
`lv.driver_backends_register()`	注册驱动后端
`lv.driver_backends_init_backend()`	初始化驱动后端
`lv.driver_backends_is_supported()`	查询后端是否支持
`lv.driver_backends_print_supported()`	打印支持的后端
`lv.driver_backends_run_loop()`	运行驱动循环

FreeType 字体#

函数	说明
`lv.freetype_font_create(path, render, size, style)`	创建 FreeType 字体
`lv.freetype_font_delete(font)`	删除 FreeType 字体

颜色 (color)#

创建颜色#

c1 = lv.color_make(255, 0, 0)          # RGB (0-255)
c2 = lv.color.from_rgb(255, 0, 0)      # RGB (0-255)，color 静态方法
c3 = lv.color_hex(0xFF0000)            # 十六进制整数
c4 = lv.color.from_hex(0xFF0000)       # 十六进制整数，color 静态方法
c5 = lv.color(r, g, b)                 # _wrapper 别名，等同于 color_make
c6 = lv.color_from_hex_str("#FF0000")  # 十六进制字符串，_wrapper 别名
c7 = lv.color_black()                  # 纯黑
c8 = lv.color_white()                  # 纯白

color 属性#

c = lv.color_make(255, 128, 0)
print(c.red, c.green, c.blue)       # 读取 RGB 分量 (只读, 0-255)

透明度常量#

常量	值	说明
`lv.OPA_TRANSP`	0	完全透明
`lv.OPA_0`	0	0% 不透明
`lv.OPA_10`	25	10% 不透明
`lv.OPA_20`	51	20%
`lv.OPA_30`	76	30%
`lv.OPA_40`	102	40%
`lv.OPA_50`	127	50%
`lv.OPA_60`	153	60%
`lv.OPA_70`	178	70%
`lv.OPA_80`	204	80%
`lv.OPA_90`	229	90%
`lv.OPA_100`	255	100% 不透明
`lv.OPA_COVER`	255	完全不透明

类 (Classes)#

类	Python 名称	说明
`obj`	`lv.obj`	所有控件的基类
`event`	`lv.event`	事件对象
`color`	`lv.color`	颜色对象
`display`	`lv.display`	显示对象
`indev`	`lv.indev`	输入设备对象
`timer_t`	`lv.timer_t`	定时器对象
`anim_t`	`lv.anim_t`	动画对象
`font`	`lv.font`	字体对象 (FreeType)

基础对象 obj#

obj 是所有控件的基类。所有控件都继承 obj 的方法。

创建 (obj)#

obj = lv.obj()                      # 无参构造
child = parent.obj()                # 创建子对象 (在 parent 下创建新的 obj)

注意: lv.obj() 无参构造创建基础对象，parent.obj() 在父对象下创建子对象。

位置与尺寸#

方法	说明
`set_pos(x, y)`	设置位置
`set_x(x)`	设置 X 坐标
`set_y(y)`	设置 Y 坐标
`set_size(w, h)`	设置宽高
`set_width(w)`	设置宽度
`set_height(h)`	设置高度
`set_content_width(w)`	设置内容宽度
`set_content_height(h)`	设置内容高度
`get_x()` / `get_y()`	获取坐标
`get_width()` / `get_height()`	获取宽高
`get_content_width()` / `get_content_height()`	获取内容宽高

对齐#

方法	说明
`set_align(align)`	设置对齐方式
`align(align, x_ofs, y_ofs)`	相对父对象对齐
`align_to(base, align, x_ofs, y_ofs)`	相对另一对象对齐
`center()`	居中

对齐值使用 lv.ALIGN 枚举：

lv.ALIGN.CENTER           # 居中
lv.ALIGN.TOP_LEFT         # 左上
lv.ALIGN.TOP_MID          # 上中
lv.ALIGN.TOP_RIGHT        # 右上
lv.ALIGN.BOTTOM_LEFT      # 左下
lv.ALIGN.BOTTOM_MID       # 下中
lv.ALIGN.BOTTOM_RIGHT     # 右下
lv.ALIGN.LEFT_MID         # 左中
lv.ALIGN.RIGHT_MID        # 右中
lv.ALIGN.OUT_TOP_LEFT     # 父对象外侧上方左对齐
lv.ALIGN.OUT_BOTTOM_MID   # 父对象外侧下方居中
# ... 更多 OUT_ 变体

层级与父子关系#

方法	说明
`set_parent(parent)`	设置父对象
`get_parent()`	获取父对象
`get_child(idx)`	获取子对象
`get_child_count()`	获取子对象数量
`get_index()`	获取在兄弟中的索引
`move_to_index(idx)`	移动到指定索引位置
`move_foreground()`	移到最前
`move_background()`	移到最后
`swap(obj2)`	交换两个对象位置

删除#

方法	说明
`delete_obj()`	删除对象
`delete_async()`	异步删除对象
`clean()`	删除所有子对象

事件绑定 (简写)#

btn.add_event_cb(lv.EVENT.CLICKED, callback)        # 添加事件回调
btn.on(lv.EVENT.CLICKED, callback)                  # 简写，等同于 add_event_cb
btn.off(lv.EVENT.CLICKED, callback)                 # 移除事件回调 (LED 专用)
btn.remove_event(idx)                               # 按索引移除事件
btn.remove_event_cb_with_user_data(cb, data)        # 按回调移除事件

淡入淡出#

obj.fade_in(time_ms, delay_ms)   # 淡入
obj.fade_out(time_ms, delay_ms)  # 淡出

变换#

obj.set_transform(matrix)     # 设置变换矩阵
obj.reset_transform()         # 重置变换
obj.transform_point(point)    # 变换坐标点

坐标与可见性#

方法	说明
`get_coords()`	获取绝对坐标区域
`get_content_coords()`	获取内容区域坐标
`invalidate()`	标记区域为无效 (重绘)
`invalidate_area(area)`	标记指定区域为无效
`is_visible()`	对象是否可见
`area_is_visible(area)`	区域是否在对象内可见
`move_to(x, y)`	移动到绝对位置
`move_children_by(dx, dy)`	移动所有子对象

控件 (Widgets)#

所有控件通过模块级工厂函数创建，传入 parent 参数 (可选，默认为当前屏幕)：

btn = lv.button(parent)   # 创建按钮

统一命名: 所有控件共享 obj 基类，但每个控件的方法都使用统一短名称（如 set_text、set_value、close），无需加控件前缀。同名方法在不同控件上自动调用对应实现（如 arc.set_value() 和 slider.set_value() 各自更新对应控件的值）。每个控件章节的”常用方法”表已列出该控件支持的完整方法。

button#

基础交互控件，用于触发操作。

创建

btn = lv.button(scr)
btn.set_size(120, 40)
btn.center()

常用方法

方法	说明
`set_size(w, h)`	设置宽高
`set_pos(x, y)`	设置位置
`center()`	居中
`align(align, x_ofs, y_ofs)`	相对父对象对齐
`align_to(base, align, x_ofs, y_ofs)`	相对另一对象对齐
`add_event_cb(event, cb)`	添加事件回调
`add_flag(flag)`	添加标志
`remove_flag(flag)`	移除标志
`set_style_bg_color(color, selector)`	设置背景颜色
`set_style_bg_opa(opa, selector)`	设置背景透明度

事件

事件	说明
`lv.EVENT.CLICKED`	点击
`lv.EVENT.PRESSED`	按下
`lv.EVENT.RELEASED`	释放
`lv.EVENT.LONG_PRESSED`	长按

完整示例

demo_button.py

label#

文本显示控件，支持多行、滚动、重新着色等模式。

创建

label = lv.label(scr)
label.set_text("Hello World")

常用方法

方法	说明
`set_text(text)`	设置文本
`set_text_static(text)`	设置静态文本 (不复制)
`set_long_mode(mode)`	设置长文本模式
`set_recolor(True)`	启用重新着色
`set_max_lines(n)`	最大行数
`get_text()`	获取文本
`ins_text(pos, text)`	在位置插入文本
`cut_text(pos, count)`	从位置剪切文本

枚举

长文本模式 (lv.LABEL_LONG)：

枚举值	说明
`WRAP`	自动换行 (默认)
`DOTS`	超出部分显示省略号
`SCROLL`	滚动显示
`SCROLL_CIRCULAR`	循环滚动
`CLIP`	裁剪

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	文本改变

完整示例

demo_label.py

image#

图片显示控件，支持缩放、旋转、偏移等变换。

创建

img = lv.image(scr)
img.set_src("A:/path/to/image.png")   # LVGL 文件系统需要 'A:' 前缀

文件路径: LVGL 使用 FS_STDIO 后端，驱动器盘符为 A:，所有文件路径必须以 A: 开头 (如 "A:/root/image.png")。支持 PNG (推荐)、BMP、JPEG (仅 baseline) 格式。

常用方法

方法	说明
`set_src(src)`	设置图片源
`set_offset_x(x)`	X 偏移
`set_offset_y(y)`	Y 偏移
`set_rotation(angle)`	旋转 (0.1度单位, 450=45.0°)
`set_pivot(x, y)`	设置旋转中心
`set_scale(zoom)`	缩放 (256=1x, 512=2x)
`set_scale_x(zoom)`	X 方向缩放
`set_scale_y(zoom)`	Y 方向缩放
`set_blend_mode(mode)`	混合模式
`set_antialias(True)`	抗锯齿
`set_inner_align(align)`	内部对齐
`get_scale()`	获取缩放值
`get_rotation()`	获取旋转角度
`get_src_width()`	获取源图宽度
`get_src_height()`	获取源图高度
`get_pivot()`	获取旋转中心

枚举

图片对齐 (lv.IMAGE_ALIGN)：DEFAULT, TOP_LEFT, TOP_MID, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_MID, BOTTOM_RIGHT, LEFT_MID, RIGHT_MID, CENTER, STRETCH, TILE, CONTAIN, COVER

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	图片改变

完整示例

demo_image.py

arc#

弧形控件，用于显示角度范围或作为旋钮调节值。

创建

arc = lv.arc(scr)
arc.set_range(0, 100)
arc.set_value(70)

常用方法

方法	说明
`set_range(min, max)`	设置值范围
`set_value(value)`	设置当前值
`set_min_value(val)`	设置最小值
`set_max_value(val)`	设置最大值
`set_angles(start, end)`	设置前景弧角度
`set_bg_angles(start, end)`	设置背景弧角度
`set_rotation(angle)`	旋转偏移
`set_mode(mode)`	模式
`set_change_rate(rate)`	值变化速率
`set_knob_offset(offset)`	旋钮偏移
`get_value()`	获取当前值
`get_min_value()`	获取最小值
`get_max_value()`	获取最大值
`get_rotation()`	获取旋转偏移
`get_angle_start()`	获取前景起始角
`get_angle_end()`	获取前景结束角
`get_mode()`	获取模式

枚举

弧形模式 (lv.ARC_MODE)：NORMAL, SYMMETRICAL, REVERSE

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	值改变

完整示例

demo_arc.py

bar#

进度条控件，用于显示比例或进度。

创建

bar = lv.bar(scr)
bar.set_range(0, 100)
bar.set_value(60, True)

常用方法

方法	说明
`set_range(min, max)`	设置范围
`set_value(value, anim)`	设置值 (是否动画)
`set_start_value(value, anim)`	设置起始值 (范围模式)
`set_min_value(val)`	设置最小值
`set_max_value(val)`	设置最大值
`set_mode(mode)`	模式
`set_orientation(orient)`	方向
`get_value()`	获取当前值
`get_start_value()`	获取起始值
`get_min_value()`	获取最小值
`get_max_value()`	获取最大值
`get_mode()`	获取模式
`get_orientation()`	获取方向
`is_symmetrical()`	是否对称模式

枚举

条形模式 (lv.BAR_MODE)：NORMAL, SYMMETRICAL, RANGE

方向 (lv.BAR_ORIENTATION)：AUTO, HORIZONTAL, VERTICAL

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	值改变

完整示例

demo_bar.py

slider#

滑块控件，用于拖拽调节值。

创建

slider = lv.slider(scr)
slider.set_range(0, 100)
slider.set_value(50, True)

常用方法

方法	说明
`set_range(min, max)`	设置范围
`set_value(value, anim)`	设置值 (是否动画)
`set_start_value(value, anim)`	设置起始值 (范围模式，是否动画)
`set_min_value(val)`	设置最小值
`set_max_value(val)`	设置最大值
`set_mode(mode)`	模式
`set_orientation(orient)`	方向
`get_value()`	获取当前值
`get_left_value()`	获取左值 (范围模式)
`get_min_value()`	获取最小值
`get_max_value()`	获取最大值
`get_mode()`	获取模式
`get_orientation()`	获取方向
`is_symmetrical()`	是否对称模式
`is_dragged()`	是否正在拖拽

枚举

滑块模式 (lv.SLIDER_MODE)：NORMAL, SYMMETRICAL, RANGE

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	值改变

完整示例

demo_slider.py

switch#

开关控件，用于切换开/关状态。

创建

sw = lv.switch(scr)

常用方法

方法	说明
`set_orientation(orient)`	方向
`get_orientation()`	获取方向

枚举

方向 (lv.SWITCH_ORIENTATION)：AUTO, HORIZONTAL, VERTICAL

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	值改变

完整示例

demo_switch.py

checkbox#

复选框控件，用于选择/取消选择选项。

创建

cb = lv.checkbox(scr)
cb.set_text("Option A")

常用方法

方法	说明
`set_text(text)`	设置文本
`set_text_static(text)`	设置静态文本
`get_text()`	获取文本

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	值改变

完整示例

demo_checkbox.py

dropdown#

下拉列表控件，用于从选项中选择一项。

创建

dd = lv.dropdown(scr)
dd.set_options("Red\nGreen\nBlue")

常用方法

方法	说明
`set_options(str)`	设置选项 (\n 分隔)
`add_option(str, pos)`	在位置添加选项
`set_selected(idx)`	设置选中项
`set_text(text)`	设置当前选中项文本
`set_text_static(text)`	设置静态文本
`set_dir(dir)`	设置展开方向
`set_symbol(symbol)`	设置指示符号
`clear_options()`	清除所有选项
`get_selected()`	获取选中索引
`get_text()`	获取当前选中项文本
`get_options()`	获取选项字符串
`get_option_count()`	获取选项数量
`get_option_index(name)`	按名称查找索引
`open()`	打开下拉列表
`close()`	关闭下拉列表
`is_open()`	是否打开

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	选中项改变

完整示例

demo_dropdown.py

roller#

滚轮控件，通过滚动选择选项。

创建

roller = lv.roller(scr)
roller.set_options("A\nB\nC", lv.ROLLER_MODE.NORMAL)

常用方法

方法	说明
`set_options(str, mode)`	设置选项
`set_selected(idx, anim)`	设置选中项 (是否动画)
`set_selected_str(str, anim)`	按字符串选中
`set_visible_row_count(n)`	设置可见行数
`get_selected()`	获取选中索引
`get_options()`	获取选项
`get_option_count()`	获取选项数量

枚举

滚轮模式 (lv.ROLLER_MODE)：NORMAL, INFINITE

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	选中项改变

完整示例

demo_roller.py

textarea#

文本输入框控件，支持单行/多行、密码模式、字符过滤等。

创建

ta = lv.textarea(scr)
ta.set_text("Hello")

常用方法

方法	说明
`set_text(text)`	设置文本
`set_placeholder_text(text)`	设置占位文本
`set_one_line(True)`	单行模式
`set_password_mode(True)`	密码模式
`set_max_length(len)`	最大长度
`set_accepted_chars(chars)`	限制可输入字符
`set_cursor_pos(pos)`	设置光标位置
`set_text_selection(True)`	启用文本选择
`add_text(text)`	追加文本
`add_char(code)`	追加字符 (ASCII)
`delete_char()`	删除光标前字符
`delete_char_forward()`	删除光标后字符
`clear_selection()`	清除选择
`get_cursor_pos()`	获取光标位置
`get_one_line()`	是否单行
`get_password_mode()`	是否密码模式
`get_max_length()`	获取最大长度

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	文本内容改变
`lv.EVENT.READY`	输入完成

完整示例

demo_textarea.py

keyboard#

虚拟键盘控件，用于配合 Textarea 输入文本。

创建

kb = lv.keyboard(scr)
kb.set_textarea(textarea_obj)

常用方法

方法	说明
`set_textarea(ta)`	关联文本输入框
`set_mode(mode)`	设置键盘模式
`set_popovers(True)`	启用按键弹出
`get_textarea()`	获取关联的文本框
`get_mode()`	获取当前模式
`get_button_text()`	获取按键文本

枚举

键盘模式 (lv.KEYBOARD_MODE)：TEXT_LOWER, TEXT_UPPER, SPECIAL, NUMBER, USER_1~USER_4

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	按键值改变
`lv.EVENT.READY`	输入完成 (确认键)

完整示例

demo_keyboard.py

chart#

图表控件，支持折线、曲线、柱状等数据可视化。

创建

chart = lv.chart(scr)
chart.set_type(lv.CHART_TYPE.LINE)

常用方法

方法	说明
`set_type(type)`	图表类型
`set_axis_range(axis, min, max)`	设置轴范围
`set_update_mode(mode)`	更新模式
`set_div_line_count(h, v)`	水平/垂直分割线数
`set_hor_div_line_count(n)`	水平分割线数
`set_ver_div_line_count(n)`	垂直分割线数
`set_axis_min_value(axis, val)`	设置轴最小值
`set_axis_max_value(axis, val)`	设置轴最大值
`set_point_count(n)`	设置数据点数
`add_series(color, axis)`	添加数据系列
`set_next_value(ser, val)`	追加一个数据点
`set_all_values(ser, val)`	全部设为同一值
`set_series_color(ser, color)`	设置系列颜色
`refresh()`	刷新显示
`get_type()`	获取类型
`get_point_count()`	获取点数
`get_update_mode()`	获取更新模式
`get_hor_div_line_count()`	获取水平分割线数
`get_ver_div_line_count()`	获取垂直分割线数
`get_pressed_point()`	获取按下的数据点

枚举

图表类型 (lv.CHART_TYPE)：NONE, LINE, CURVE, BAR, STACKED, SCATTER

更新模式 (lv.CHART_UPDATE_MODE)：SHIFT, CIRCULAR

轴 (lv.CHART_AXIS)：PRIMARY_Y, SECONDARY_Y, PRIMARY_X, SECONDARY_X, LAST

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	数据点改变
`lv.EVENT.PRESSED`	按下数据点

完整示例

demo_chart.py

table#

表格控件，用于显示行列数据。

创建

table = lv.table(scr)
table.set_row_count(5)
table.set_column_count(3)

常用方法

方法	说明
`set_row_count(n)`	设置行数
`set_column_count(n)`	设置列数
`set_column_width(col, w)`	设置列宽
`set_cell_value(row, col, text)`	设置单元格文本
`set_cell_ctrl(row, col, ctrl)`	设置单元格控制标志
`get_cell_value(row, col)`	获取单元格文本
`get_row_count()`	获取行数
`get_column_count()`	获取列数
`set_selected_cell(row, col)`	设置选中单元格

枚举

单元格控制 (lv.TABLE_CELL_CTRL)：NONE, MERGE_RIGHT, TEXT_CROP, CUSTOM_1~CUSTOM_4

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	选中单元格改变

完整示例

demo_table.py

tabview#

标签页控件，用于多页面切换。

创建

tv = lv.tabview(scr)
tab1 = tv.add_tab("Tab 1")
tab2 = tv.add_tab("Tab 2")

常用方法

方法	说明
`add_tab(name)`	添加标签页
`set_active(idx, anim)`	切换标签页 (是否动画)
`set_tab_bar_size(size)`	设置标签栏大小
`set_tab_bar_position(dir)`	设置标签栏位置
`get_tab_count()`	获取标签页数量
`get_tab_active()`	获取当前活动标签
`get_content()`	获取内容区域
`get_tab_bar()`	获取标签栏

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	标签页切换

完整示例

demo_tabview.py

list#

列表控件，用于显示带图标的条目列表。

创建

list = lv.list(scr)
list.add_text("Section Title")
btn = list.add_button(icon, "Item Text")

常用方法

方法	说明
`add_text(text)`	添加文本标题
`add_button(icon, text)`	添加按钮条目
`get_button_text(btn)`	获取按钮文本
`set_button_text(btn, text)`	设置按钮文本

事件

事件	说明
`lv.EVENT.CLICKED`	点击条目
`lv.EVENT.SELECTED`	选中条目

完整示例

demo_list.py

menu#

菜单控件，用于多级导航界面。

创建

menu = lv.menu(scr)

常用方法

方法	说明
`set_mode_header(mode)`	设置头部模式
`set_mode_root_back_button(mode)`	设置返回按钮模式
`clear_history()`	清除导航历史
`set_page(page)`	设置当前显示页面
`set_sidebar_page(page)`	设置侧边栏页面
`set_load_page_event(trigger, target)`	设置点击跳转
`get_cur_main_page()`	获取当前主页面
`get_cur_sidebar_page()`	获取当前侧边栏页面

枚举

头部模式 (lv.MENU_HEADER)：TOP_FIXED, TOP_UNFIXED, BOTTOM_FIXED

返回按钮 (lv.MENU_ROOT_BACK_BTN)：MENU_ROOT_BACK_BUTTON_DISABLED, MENU_ROOT_BACK_BUTTON_ENABLED

事件

事件	说明
`lv.EVENT.CLICKED`	点击菜单项

完整示例

demo_menu.py

注意事项

menu_page、menu_cont、menu_section 是模块级工厂函数，与 menu 一样通过 lv.menu_page(menu, title) 调用。

msgbox#

消息框控件，用于显示提示信息。无参构造时为模态 (带遮罩)。

创建

msgbox = lv.msgbox()               # 模态 (推荐)
msgbox = lv.msgbox(parent)         # 非模态 (指定父对象)

常用方法

方法	说明
`add_title(text)`	添加标题
`add_text(text)`	添加文本内容
`add_footer_button(text)`	添加底部按钮
`add_close_button()`	添加关闭按钮 (✕)
`get_header()`	获取头部区域
`get_footer()`	获取底部区域
`get_content()`	获取内容区域
`close()`	关闭消息框
`close_async()`	异步关闭消息框

事件

事件	说明
`lv.EVENT.CLICKED`	点击按钮
`lv.EVENT.CLOSED`	关闭消息框
`lv.EVENT.VALUE_CHANGED`	按钮值改变

完整示例

demo_msgbox.py

注意事项

lv.msgbox() 不传 parent 时，内部传 NULL 给 lv_msgbox_create，LVGL 会自动在 lv_layer_top() 上创建半透明遮罩 (backdrop)，实现模态效果。如果传入 parent 对象，则不会创建遮罩。

led#

LED 指示灯控件，用于显示状态。

创建

led = lv.led(scr)
led.set_size(30, 30)

常用方法

方法	说明
`set_color(color)`	设置 LED 颜色
`set_brightness(val)`	设置亮度 (0-255)
`on()`	开启 (最大亮度)
`off()`	关闭 (最小亮度)
`toggle()`	切换
`get_brightness()`	获取亮度
`get_color()`	获取颜色

完整示例

demo_led.py

line#

折线控件，用于绘制多段折线。

创建

line = lv.line(scr)
line.center()
line.set_points([(0, 0), (40, 30), (80, 0), (120, 30), (160, 0), (200, 30)])

常用方法

方法	说明
`set_points(points)`	设置坐标点 (列表 of 元组)
`set_y_invert(True)`	Y 轴反转
`get_y_invert()`	获取 Y 反转状态
`get_point_count()`	获取坐标点数量

完整示例

demo_line.py

注意事项

set_points() 接受 Python 列表 of (x, y) 元组。Line 控件必须调用 set_points() 设置坐标点才能显示，否则为空白。

canvas#

画布控件，用于逐像素绘制图形。

创建

import numpy as np

canvas = lv.canvas(scr)
buf = np.zeros((H, W, 4), dtype=np.uint8)
canvas.set_buffer(buf.ctypes.data, W, H, lv.COLOR_FORMAT.ARGB8888)

常用方法

方法	说明
`set_buffer(buf, w, h, cf)`	设置绘制缓冲区
`set_px(x, y, color, opa)`	设置像素
`get_px(x, y)`	获取像素
`fill_bg(color, opa)`	填充背景
`set_palette(index, color)`	设置调色板
`get_draw_buf()`	获取绘制缓冲区

完整示例

demo_canvas.py

注意事项

set_buffer(buf, w, h, cf) 的 buf 参数为内存地址整数（uintptr_t），使用 numpy 数组时传 buf.ctypes.data，不要传 ctypes 指针对象。

scale#

刻度尺控件，用于显示刻度标记。

创建

scale = lv.scale(scr)
scale.set_range(0, 100)

常用方法

方法	说明
`set_mode(mode)`	模式
`set_total_tick_count(n)`	总刻度数
`set_major_tick_every(n)`	主刻度间隔
`set_range(min, max)`	设置范围
`set_min_value(val)`	设置最小值
`set_max_value(val)`	设置最大值
`set_angle_range(angle)`	圆形刻度角度范围
`set_rotation(angle)`	旋转偏移
`set_label_show(True)`	显示标签
`set_draw_ticks_on_top(True)`	刻度绘制在顶部
`get_mode()`	获取模式
`get_total_tick_count()`	获取总刻度数
`get_min_value()`	获取最小值
`get_max_value()`	获取最大值
`get_angle_range()`	获取角度范围
`get_rotation()`	获取旋转偏移

枚举

刻度模式 (lv.SCALE_MODE)：HORIZONTAL_TOP, HORIZONTAL_BOTTOM, VERTICAL_LEFT, VERTICAL_RIGHT, ROUND_INNER, ROUND_OUTER, LAST

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	值改变

完整示例

demo_scale.py

spinbox#

数字输入框控件，用于精确数值调节。

创建

sb = lv.spinbox(scr)
sb.set_value(50)

常用方法

方法	说明
`set_value(value)`	设置值
`set_digit_format(digits, sep_pos)`	位数, 小数点位置
`set_step(step)`	步进值
`set_range(min, max)`	设置范围
`set_min_value(val)`	设置最小值
`set_max_value(val)`	设置最大值
`set_rollover(True)`	循环
`set_cursor_pos(pos)`	光标位置
`set_digit_step_direction(dir)`	数字步进方向
`get_value()`	获取值
`get_min_value()`	获取最小值
`get_max_value()`	获取最大值
`increment()`	增加一步
`decrement()`	减少一步
`step_next()`	光标移到下一位
`step_prev()`	光标移到上一位

事件

事件	说明
`lv.EVENT.VALUE_CHANGED`	值改变

完整示例

demo_spinbox.py

spinner#

加载动画控件，用于显示等待状态。

创建

sp = lv.spinner(scr)
sp.set_size(50, 50)

常用方法

方法	说明
`set_anim_params(period, angle)`	周期(ms), 扫过角度
`set_anim_duration(ms)`	设置动画周期
`set_arc_sweep(angle)`	设置弧扫角度
`get_anim_duration()`	获取动画周期
`get_arc_sweep()`	获取弧扫角度

完整示例

demo_spinner.py

tileview#

平铺视图控件，用于左右/上下滑动切换页面。

创建

tv = lv.tileview(scr)
tile1 = tv.add_tile(0, 0, lv.DIR.RIGHT)
tile2 = tv.add_tile(1, 0, lv.DIR.LEFT)

常用方法

方法	说明
`add_tile(col, row, dir)`	添加 tile (列, 行, 可滑动方向)
`set_tile(tile, anim)`	滑动到指定 tile (是否动画)
`set_tile_by_index(col, row, anim)`	按索引滑动
`get_tile_active()`	获取当前活动 tile

完整示例

demo_tileview.py

win#

窗口控件，带标题栏和内容区域。

创建

win = lv.win(scr)
title = win.add_title("Window")

常用方法

方法	说明
`add_title(text)`	添加标题
`add_button(icon, width)`	添加按钮
`get_header()`	获取头部
`get_content()`	获取内容区域

完整示例

demo_win.py

animimg#

动画图片控件，用于播放帧动画。

创建

anim = lv.animimg(scr)
anim.set_src(["A:/path/to/frame1.png", "A:/path/to/frame2.png"])

常用方法

方法	说明
`set_src(paths)`	设置图片路径列表
`set_duration(ms)`	一个完整循环时间 (ms)
`set_repeat_count(n)`	重复次数 (255 = 无限循环)
`start()`	开始播放
`get_duration()`	获取循环时间
`get_repeat_count()`	获取重复次数

完整示例

demo_animimg.py

动画 (anim_t)#

动画对象，用于驱动控件属性随时间变化。

创建 (anim_t)#

a = lv.anim_t()
a.set_var(obj)                                   # 设置动画目标对象
a.set_exec_cb(obj, lambda var, v: var.set_value(v))  # 设置执行回调 fn(var, value)
a.set_values(0, 100)                             # 起始值, 结束值
a.set_duration(1000)                             # 持续时间 (ms)
a.set_repeat_count(lv.ANIM_REPEAT_INFINITE)      # 无限循环
a.start()                                        # 启动动画

常用方法 (anim_t) |#

运动路径#

方法	说明
`set_path_linear()`	线性
`set_path_ease_in()`	缓入
`set_path_ease_out()`	缓出
`set_path_ease_in_out()`	缓入缓出
`set_path_overshoot()`	过冲
`set_path_bounce()`	弹跳
`set_path_step()`	阶梯

常量#

常量	说明
`lv.ANIM_REPEAT_INFINITE`	无限循环标志

定时器 (timer_t)#

定时器对象，用于周期性执行回调。

创建 (timer_t)#

def on_timer(timer):
    # 周期性执行的代码
    pass

timer = lv.timer_create(on_timer, 100)  # 每 100ms 调用一次

常用方法 (timer_t) |#

显示 (display)#

显示对象，用于管理屏幕分辨率和旋转。

创建 (display)#

disp = lv.display_create(800, 480)       # 创建 800x480 显示
disp = lv.display_get_default()          # 获取默认显示对象

常用方法 (display) |#

枚举 (display)#

显示旋转 (lv.DISPLAY_ROTATION)：_0, _90, _180, _270

输入设备 (indev)#

输入设备对象，用于管理触摸屏、键盘等输入。

创建 (indev)#

indev = lv.indev_create()
indev.set_type(lv.INDEV_TYPE.POINTER)

常用方法 (indev)#

方法	说明
`lv.indev_get_next(indev)`	获取下一个设备
`lv.indev_get_type(indev)`	获取设备类型
`lv.indev_set_type(indev, type)`	设置设备类型
`lv.indev_set_group(indev, grp)`	设置输入分组

枚举 (indev)：`NONE`, `POINTER`, `KEYPAD`, `BUTTON`, `ENCODER`#

EVDEV 类型 (lv.EVDEV_TYPE)：REL, ABS, KEY

分组 (group)#

分组用于键盘/编码器导航，将多个控件组织在一起，通过方向键在控件间切换焦点。

使用方式#

# 创建分组
g = lv.group_create()
lv.group_set_default(g)

# 将输入设备绑定到分组
indev = lv.indev_create()
indev.set_type(lv.INDEV_TYPE.KEYPAD)
lv.indev_set_group(indev, g)

# 将控件加入分组
lv.group_add_obj(g, btn1)
lv.group_add_obj(g, btn2)

分组函数#

函数	说明
`lv.group_create()`	创建分组
`lv.group_delete(group)`	删除分组
`lv.group_set_default(group)`	设置默认分组
`lv.group_get_default()`	获取默认分组
`lv.group_add_obj(group, obj)`	将对象加入分组
`lv.group_remove_obj(obj)`	将对象从分组移除
`lv.group_focus_obj(obj)`	聚焦指定对象
`lv.group_focus_next(group)`	聚焦下一个对象
`lv.group_focus_prev(group)`	聚焦上一个对象
`lv.group_set_wrap(group, en)`	设置是否循环聚焦

事件与回调#

注册事件回调#

def on_clicked(event):
    if event.code == lv.EVENT.CLICKED:
        print("Button clicked!")
        print("Target:", event.target)  # 触发事件的对象

btn.add_event_cb(lv.EVENT.CLICKED, on_clicked)
btn.on(lv.EVENT.CLICKED, on_clicked)    # 简写，等同于 add_event_cb

event 对象#

回调函数接收 event 对象，提供以下属性和方法：

属性/方法	说明
`event.code`	事件码 (int，可与 `lv.EVENT.XXX` 比较)
`event.target`	触发事件的对象 (Obj)
`event.current_target`	当前处理事件的对象 (事件冒泡路径上的对象)
`event.stop_bubbling()`	停止事件冒泡
`event.stop_processing()`	停止当前对象的事件处理
`event.stop_trickling()`	停止向子对象传递事件

向后兼容: Event 对象支持 == int 比较（event == lv.EVENT.CLICKED 等效于 event.code == lv.EVENT.CLICKED），旧代码无需修改即可运行。

完整事件码 (`lv.EVENT`, 76 个)#

事件	说明
`ALL`	所有事件
`PRESSED`	按下
`PRESSING`	持续按压
`PRESS_LOST`	按压丢失
`SHORT_CLICKED`	短点击
`SINGLE_CLICKED`	单击
`DOUBLE_CLICKED`	双击
`TRIPLE_CLICKED`	三击
`LONG_PRESSED`	长按
`LONG_PRESSED_REPEAT`	长按重复
`CLICKED`	点击
`RELEASED`	释放
`SCROLL_BEGIN`	滚动开始
`SCROLL_THROW_BEGIN`	惯性滚动开始
`SCROLL_END`	滚动结束
`SCROLL`	滚动
`GESTURE`	手势
`KEY`	按键
`ROTARY`	旋钮
`FOCUSED`	获得焦点
`DEFOCUSED`	失去焦点
`LEAVE`	离开
`HIT_TEST`	命中测试
`INDEV_RESET`	输入设备重置
`HOVER_OVER`	悬停经过
`HOVER_STILL`	悬停静止
`HOVER_LEAVE`	悬停离开
`VALUE_CHANGED`	值改变
`INSERT`	插入
`REFRESH`	刷新
`READY`	就绪
`CANCEL`	取消
`SCREEN_LOADED`	屏幕加载完成
`SCREEN_LOAD_START`	屏幕开始加载
`SCREEN_UNLOADED`	屏幕卸载完成
`SCREEN_UNLOAD_START`	屏幕开始卸载
`SIZE_CHANGED`	尺寸改变
`DRAW_TASK_ADDED`	绘制任务添加
`CHILD_CHANGED`	子对象改变
`CHILD_CREATED`	子对象创建
`CHILD_DELETED`	子对象删除
`SELECTED`	选中
`CHECKED`	勾选

样式系统#

样式通过 set_style_*(value, selector) 方法设置。selector 参数指定样式应用的目标，推荐使用 lv.SELECTOR.DEFAULT (默认状态 LV_PART_MAIN | LV_STATE_DEFAULT)，避免使用裸数字 0。

常用 selector 值#

值	说明
`lv.SELECTOR.DEFAULT`	`LV_PART_MAIN` + 默认状态 (= 0)
`lv.PART.MAIN`	主部分
`lv.PART.INDICATOR`	指示器部分 (Slider/Bar 的填充)
`lv.PART.KNOB`	旋钮部分
`lv.PART.ITEMS`	项目部分
`lv.PART.CURSOR`	光标部分
`lv.PART.SELECTED`	选中部分
`lv.PART.SCROLLBAR`	滚动条部分
`lv.PART.CUSTOM_FIRST`	自定义部分起始
`lv.PART.ANY`	任意部分

提示: 组合 Part + State 使用位或运算：lv.PART.KNOB | lv.STATE.FOCUSED

背景样式#

obj.set_style_bg_color(lv.color_make(255, 0, 0), lv.SELECTOR.DEFAULT)       # 背景颜色
obj.set_style_bg_opa(lv.OPA_50, lv.SELECTOR.DEFAULT)                 # 背景透明度
obj.set_style_bg_grad_color(lv.color_make(0, 0, 255), lv.SELECTOR.DEFAULT)   # 渐变终止颜色
obj.set_style_bg_grad_dir(lv.GRAD_DIR.VER, lv.SELECTOR.DEFAULT)  # 渐变方向
obj.set_style_bg_main_stop(0, lv.SELECTOR.DEFAULT)                       # 渐变起始位置 (0-255)
obj.set_style_bg_grad_stop(255, lv.SELECTOR.DEFAULT)                     # 渐变结束位置
obj.set_style_bg_main_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # 渐变起始透明度
obj.set_style_bg_grad_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # 渐变终止透明度
obj.set_style_bg_image_src(src, lv.SELECTOR.DEFAULT)                     # 背景图片
obj.set_style_bg_image_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)              # 背景图片透明度
obj.set_style_bg_image_recolor(color, lv.SELECTOR.DEFAULT)               # 背景图片重新着色
obj.set_style_bg_image_tiled(True, lv.SELECTOR.DEFAULT)                  # 背景图片平铺

边框样式#

obj.set_style_border_width(2, lv.SELECTOR.DEFAULT)                       # 边框宽度
obj.set_style_border_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT)       # 边框颜色
obj.set_style_border_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)             # 边框透明度
obj.set_style_border_side(lv.BORDER_SIDE.FULL, lv.SELECTOR.DEFAULT)  # 边框边
obj.set_style_border_post(True, lv.SELECTOR.DEFAULT)                     # 边框后绘制

圆角与阴影#

obj.set_style_radius(10, lv.SELECTOR.DEFAULT)                            # 圆角半径
obj.set_style_shadow_width(10, lv.SELECTOR.DEFAULT)                      # 阴影宽度
obj.set_style_shadow_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT)       # 阴影颜色
obj.set_style_shadow_offset_x(3, lv.SELECTOR.DEFAULT)                    # 阴影 X 偏移
obj.set_style_shadow_offset_y(3, lv.SELECTOR.DEFAULT)                    # 阴影 Y 偏移
obj.set_style_shadow_spread(2, lv.SELECTOR.DEFAULT)                      # 阴影扩散
obj.set_style_shadow_opa(lv.OPA_50, lv.SELECTOR.DEFAULT)              # 阴影透明度

模糊样式#

obj.set_style_blur_radius(r, lv.SELECTOR.DEFAULT)                        # 模糊半径
obj.set_style_blur_quality(lv.BLUR_QUALITY.AUTO, lv.SELECTOR.DEFAULT)    # 模糊质量
obj.set_style_blur_backdrop(True, lv.SELECTOR.DEFAULT)                   # 模糊背景

轮廓样式#

obj.set_style_outline_width(2, lv.SELECTOR.DEFAULT)                      # 轮廓宽度
obj.set_style_outline_color(lv.color_make(0, 128, 255), lv.SELECTOR.DEFAULT)  # 轮廓颜色
obj.set_style_outline_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)            # 轮廓透明度
obj.set_style_outline_pad(3, lv.SELECTOR.DEFAULT)                        # 轮廓内边距

文本样式#

obj.set_style_text_color(lv.color_make(255, 255, 255), lv.SELECTOR.DEFAULT)   # 文本颜色
obj.set_style_text_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)               # 文本透明度
obj.set_style_text_font(font_ptr, lv.SELECTOR.DEFAULT)                    # 文本字体
obj.set_style_text_letter_space(2, lv.SELECTOR.DEFAULT)                   # 字间距
obj.set_style_text_line_space(4, lv.SELECTOR.DEFAULT)                     # 行间距
obj.set_style_text_align(lv.TEXT_ALIGN.CENTER, lv.SELECTOR.DEFAULT)  # 文本对齐
obj.set_style_text_decor(lv.TEXT_DECOR.UNDERLINE, lv.SELECTOR.DEFAULT)  # 文本装饰
obj.set_style_text_outline_stroke_width(1, lv.SELECTOR.DEFAULT)           # 文本描边宽度
obj.set_style_text_outline_stroke_color(lv.color_make(0, 0, 0), lv.SELECTOR.DEFAULT) # 描边颜色

内边距与外边距#

obj.set_style_pad_top(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_bottom(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_left(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_right(10, lv.SELECTOR.DEFAULT)
obj.set_style_pad_row(5, lv.SELECTOR.DEFAULT)       # 行间距 (Flex/Grid)
obj.set_style_pad_column(5, lv.SELECTOR.DEFAULT)    # 列间距

# 简写 (padding)
obj.set_style_pad_all(10, lv.SELECTOR.DEFAULT)      # 四边相同
obj.set_style_pad_hor(10, lv.SELECTOR.DEFAULT)      # 左右相同
obj.set_style_pad_ver(10, lv.SELECTOR.DEFAULT)      # 上下相同
obj.set_style_pad_gap(5, lv.SELECTOR.DEFAULT)       # 行列间距相同

obj.set_style_margin_top(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_bottom(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_left(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_right(5, lv.SELECTOR.DEFAULT)

# 简写 (margin)
obj.set_style_margin_all(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_hor(5, lv.SELECTOR.DEFAULT)
obj.set_style_margin_ver(5, lv.SELECTOR.DEFAULT)

变换样式#

obj.set_style_transform_scale_x(256, lv.SELECTOR.DEFAULT)        # X 缩放 (256=1x)
obj.set_style_transform_scale_y(256, lv.SELECTOR.DEFAULT)        # Y 缩放
obj.set_style_transform_scale(256, lv.SELECTOR.DEFAULT)          # XY 同时缩放
obj.set_style_transform_rotation(0, lv.SELECTOR.DEFAULT)          # 旋转 (0.1° 单位)
obj.set_style_transform_pivot_x(0, lv.SELECTOR.DEFAULT)           # 旋转中心 X
obj.set_style_transform_pivot_y(0, lv.SELECTOR.DEFAULT)           # 旋转中心 Y
obj.set_style_transform_skew_x(0, lv.SELECTOR.DEFAULT)            # X 倾斜
obj.set_style_transform_skew_y(0, lv.SELECTOR.DEFAULT)            # Y 倾斜
obj.set_style_translate_x(10, lv.SELECTOR.DEFAULT)                # X 平移
obj.set_style_translate_y(10, lv.SELECTOR.DEFAULT)                # Y 平移

其他样式#

obj.set_style_opa(lv.OPA_80, lv.SELECTOR.DEFAULT)              # 整体透明度
obj.set_style_opa_layered(lv.OPA_80, lv.SELECTOR.DEFAULT)      # 层叠透明度
obj.set_style_clip_corner(True, lv.SELECTOR.DEFAULT)               # 裁剪圆角
obj.set_style_blend_mode(lv.BLEND_MODE.NORMAL, lv.SELECTOR.DEFAULT)  # 混合模式
obj.set_style_anim_duration(300, lv.SELECTOR.DEFAULT)              # 动画持续时间
obj.set_style_base_dir(lv.BASE_DIR.LTR, lv.SELECTOR.DEFAULT)  # 文本方向
obj.set_style_bitmap_mask_src(src, lv.SELECTOR.DEFAULT)            # 位图遮罩
obj.set_style_color_filter_opa(lv.OPA_100, lv.SELECTOR.DEFAULT)   # 颜色过滤透明度
obj.set_style_layout(lv.LAYOUT.FLEX, lv.SELECTOR.DEFAULT)         # 布局类型
obj.set_style_radial_offset(0, lv.SELECTOR.DEFAULT)               # 径向偏移
obj.set_style_recolor(color, lv.SELECTOR.DEFAULT)                 # 重新着色
obj.set_style_rotary_sensitivity(256, lv.SELECTOR.DEFAULT)        # 旋钮灵敏度

线与弧样式#

obj.set_style_line_width(2, lv.SELECTOR.DEFAULT)                   # 线宽
obj.set_style_line_color(lv.color_make(0, 0, 255), lv.SELECTOR.DEFAULT) # 线颜色
obj.set_style_line_rounded(True, lv.SELECTOR.DEFAULT)              # 线端圆角
obj.set_style_line_dash_width(10, lv.SELECTOR.DEFAULT)             # 虚线宽度
obj.set_style_line_dash_gap(5, lv.SELECTOR.DEFAULT)                # 虚线间隔

obj.set_style_arc_width(4, lv.SELECTOR.DEFAULT)                    # 弧宽
obj.set_style_arc_color(lv.color_make(255, 0, 0), lv.SELECTOR.DEFAULT)  # 弧颜色
obj.set_style_arc_rounded(True, lv.SELECTOR.DEFAULT)               # 弧端圆角
obj.set_style_arc_image_src(src, lv.SELECTOR.DEFAULT)              # 弧图片

尺寸约束样式#

obj.set_style_min_width(50, lv.SELECTOR.DEFAULT)
obj.set_style_max_width(200, lv.SELECTOR.DEFAULT)
obj.set_style_min_height(30, lv.SELECTOR.DEFAULT)
obj.set_style_max_height(100, lv.SELECTOR.DEFAULT)
obj.set_style_width(100, lv.SELECTOR.DEFAULT)           # 固定宽度
obj.set_style_height(50, lv.SELECTOR.DEFAULT)            # 固定高度
obj.set_style_size(100, lv.SELECTOR.DEFAULT)             # 固定尺寸 (宽=高)

布局 (Flex / Grid)#

Flex 布局#

# 父容器设置 Flex
container.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)  # 行 + 换行
container.set_flex_align(
    lv.FLEX_ALIGN.CENTER,       # 主轴对齐
    lv.FLEX_ALIGN.CENTER,       # 交叉轴对齐
    lv.FLEX_ALIGN.CENTER        # 行对齐
)

# 子项设置
child.set_flex_grow(1)  # 弹性增长

Flex 流向 (lv.FLEX_FLOW)：ROW, COLUMN, ROW_WRAP, ROW_REVERSE, ROW_WRAP_REVERSE, COLUMN_WRAP, COLUMN_REVERSE, COLUMN_WRAP_REVERSE

Flex 对齐 (lv.FLEX_ALIGN)：START, END, CENTER, SPACE_EVENLY, SPACE_AROUND, SPACE_BETWEEN

Grid 布局#

container.set_grid_align(
    lv.GRID_ALIGN.CENTER,  # 列对齐
    lv.GRID_ALIGN.CENTER   # 行对齐
)

child.set_grid_cell(
    lv.GRID_ALIGN.CENTER,  # 列对齐
    0, 1,                                 # 列位置, 列跨度
    lv.GRID_ALIGN.CENTER,  # 行对齐
    0, 1                                  # 行位置, 行跨度
)

Grid 对齐 (lv.GRID_ALIGN)：START, CENTER, END, STRETCH, SPACE_EVENLY, SPACE_AROUND, SPACE_BETWEEN

布局类型 (lv.LAYOUT)：NONE, FLEX, GRID, LAST

滚动#

obj.set_scrollbar_mode(lv.SCROLLBAR_MODE.AUTO)
obj.set_scroll_dir(lv.DIR.VER)        # 限制滚动方向
obj.set_scroll_snap_x(lv.SCROLL_SNAP.CENTER)
obj.set_scroll_snap_y(lv.SCROLL_SNAP.CENTER)

obj.scroll_by(dx, dy, anim_en)               # 滚动偏移
obj.scroll_to(x, y, anim_en)                 # 滚动到位置
obj.scroll_to_view(anim_en)                  # 滚动到可见
obj.is_scrolling()                           # 是否正在滚动
obj.stop_scroll_anim()                       # 停止滚动动画

obj.get_scroll_x()                           # 获取水平滚动位置
obj.get_scroll_y()                           # 获取垂直滚动位置
obj.get_scroll_bottom()                      # 获取底部滚动距离
obj.get_scroll_top()                         # 获取顶部滚动距离
obj.get_scroll_left()                        # 获取左侧滚动距离
obj.get_scroll_right()                       # 获取右侧滚动距离

Flags-and-states#

对象标志 (`lv.OBJ_FLAG`)#

obj.add_flag(lv.OBJ_FLAG.HIDDEN)        # 隐藏
obj.remove_flag(lv.OBJ_FLAG.HIDDEN)     # 取消隐藏
obj.has_flag(lv.OBJ_FLAG.CLICKABLE)     # 检查标志
obj.has_flag_any(lv.OBJ_FLAG.CLICKABLE) # 检查是否包含任一标志
obj.set_flag(lv.OBJ_FLAG.CLICKABLE, True) # 设置标志开/关

位运算支持: add_flag/remove_flag 等方法已通过 _wrapper.py 补丁支持位或运算，如 obj.add_flag(lv.OBJ_FLAG.CLICKABLE | lv.OBJ_FLAG.CHECKABLE)。

常用标志	说明
`HIDDEN`	隐藏
`CLICKABLE`	可点击
`CLICK_FOCUSABLE`	点击可聚焦
`CHECKABLE`	可选中
`SCROLLABLE`	可滚动
`SCROLL_ELASTIC`	弹性滚动
`SCROLL_MOMENTUM`	惯性滚动
`SCROLL_ONE`	一次只滚动一个子项
`SCROLL_CHAIN_HOR`	水平滚动链
`SCROLL_CHAIN_VER`	垂直滚动链
`SCROLL_ON_FOCUS`	聚焦时滚动
`SCROLL_WITH_ARROW`	方向键滚动
`SNAPPABLE`	可对齐到滚动位置
`PRESS_LOCK`	按压锁定
`EVENT_BUBBLE`	事件冒泡
`GESTURE_BUBBLE`	手势冒泡
`ADV_HITTEST`	高级命中测试
`IGNORE_LAYOUT`	忽略布局
`FLOATING`	浮动 (不参与布局)
`SEND_DRAW_TASK_EVENTS`	发送绘制任务事件
`OVERFLOW_VISIBLE`	溢出可见
`EVENT_TRICKLE`	事件渗透
`LAYOUT_1` ~ `LAYOUT_4`	布局自定义标志
`USER_1` ~ `USER_4`	用户自定义标志

对象状态 (`lv.STATE`)#

obj.add_state(lv.STATE.CHECKED)             # 添加状态
obj.remove_state(lv.STATE.CHECKED)          # 移除状态
obj.get_state()                             # 获取状态
obj.has_state(lv.STATE.CHECKED)             # 检查状态

常用状态	说明
`DEFAULT`	默认
`ALT`	替代
`CHECKED`	选中
`FOCUSED`	聚焦
`FOCUS_KEY`	按键聚焦
`EDITED`	编辑
`HOVERED`	悬停
`PRESSED`	按压
`SCROLLED`	滚动
`DISABLED`	禁用
`USER_1` ~ `USER_4`	用户自定义状态
`ANY`	任意状态

屏幕管理#

scr = lv.screen_active()          # 获取当前活动屏幕
lv.screen_load(scr)               # 加载屏幕 (无动画)

# 创建新屏幕 (使用 obj 无参构造)
scr2 = lv.obj()
lv.screen_load(scr2)

屏幕加载动画 (lv.SCREEN_LOAD)：NONE, OVER_LEFT, OVER_RIGHT, OVER_TOP, OVER_BOTTOM, MOVE_LEFT, MOVE_RIGHT, MOVE_TOP, MOVE_BOTTOM, FADE_IN, FADE_ON, FADE_OUT, OUT_LEFT, OUT_RIGHT, OUT_TOP, OUT_BOTTOM

枚举参考#

对齐 (`lv.ALIGN`)#

DEFAULT, TOP_LEFT, TOP_MID, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_MID, BOTTOM_RIGHT, LEFT_MID, RIGHT_MID, CENTER, 以及 OUT_* 外侧对齐变体 (OUT_TOP_LEFT, OUT_TOP_MID, OUT_TOP_RIGHT, OUT_BOTTOM_LEFT, OUT_BOTTOM_MID, OUT_BOTTOM_RIGHT, OUT_LEFT_TOP, OUT_LEFT_MID, OUT_LEFT_BOTTOM, OUT_RIGHT_TOP, OUT_RIGHT_MID, OUT_RIGHT_BOTTOM)。共 22 个。

方向 (`lv.DIR`)#

NONE, LEFT, RIGHT, TOP, BOTTOM, HOR, VER, ALL

文本对齐 (`lv.TEXT_ALIGN`)#

AUTO, LEFT, CENTER, RIGHT

文本装饰 (`lv.TEXT_DECOR`)#

NONE, UNDERLINE, STRIKETHROUGH

颜色格式 (`lv.COLOR_FORMAT`)#

UNKNOWN, RAW, RAW_ALPHA, L8, I1, I2, I4, I8, A8, RGB565, ARGB8565, RGB565A8, AL88, RGB565_SWAPPED, RGB888, ARGB8888, XRGB8888, ARGB8888_PREMULTIPLIED, A1, A2, A4, ARGB1555, ARGB4444, ARGB2222, YUV_START, I420, NV12, NV21, YUY2, UYVY 等。共 45 个。

调色板 (`lv.PALETTE`)#

RED, PINK, PURPLE, DEEP_PURPLE, INDIGO, BLUE, LIGHT_BLUE, CYAN, TEAL, GREEN, LIGHT_GREEN, LIME, YELLOW, AMBER, ORANGE, DEEP_ORANGE, BROWN, BLUE_GREY, GREY, LAST, NONE

混合模式 (`lv.BLEND_MODE`)#

NORMAL, ADDITIVE, SUBTRACTIVE, MULTIPLY, DIFFERENCE

滚动条模式 (`lv.SCROLLBAR_MODE`)#

OFF, ON, ACTIVE, AUTO

边框边 (`lv.BORDER_SIDE`)#

NONE, BOTTOM, TOP, LEFT, RIGHT, FULL, INTERNAL

按键 (`lv.KEY`)#

UP, DOWN, RIGHT, LEFT, ESC, DEL, BACKSPACE, ENTER, NEXT, PREV, HOME, END

渐变方向 (`lv.GRAD_DIR`)#

NONE, VER, HOR, LINEAR, RADIAL, CONICAL

渐变扩展 (`lv.GRAD_EXTEND`)#

PAD, REPEAT, REFLECT

模糊质量 (`lv.BLUR_QUALITY`)#

AUTO, SPEED, PRECISION

文本方向 (`lv.BASE_DIR`)#

LTR, RTL, AUTO, NEUTRAL, WEAK

输入设备类型 (`lv.INDEV_TYPE`)#

NONE, POINTER, KEYPAD, BUTTON, ENCODER

输入设备模式 (`lv.INDEV_MODE`)#

NONE, TIMER, EVENT

显示渲染模式 (`lv.DISPLAY_RENDER`)#

PARTIAL, DIRECT, FULL

控件部分 (`lv.PART`)#

MAIN, SCROLLBAR, INDICATOR, KNOB, SELECTED, ITEMS, CURSOR, CUSTOM_FIRST, ANY

覆盖结果 (`lv.COVER`)#

COVER, NOT_COVER, MASKED

符号常量#

常量	说明	常量	说明
`lv.SYMBOL_BULLET`	项目符号	`lv.SYMBOL_AUDIO`	音频
`lv.SYMBOL_VIDEO`	视频	`lv.SYMBOL_LIST`	列表
`lv.SYMBOL_OK`	确认	`lv.SYMBOL_CLOSE`	关闭
`lv.SYMBOL_POWER`	电源	`lv.SYMBOL_SETTINGS`	设置
`lv.SYMBOL_HOME`	主页	`lv.SYMBOL_DOWNLOAD`	下载
`lv.SYMBOL_DRIVE`	驱动器	`lv.SYMBOL_REFRESH`	刷新
`lv.SYMBOL_MUTE`	静音	`lv.SYMBOL_VOLUME_MID`	音量中
`lv.SYMBOL_VOLUME_MAX`	音量最大	`lv.SYMBOL_IMAGE`	图片
`lv.SYMBOL_TINT`	色调	`lv.SYMBOL_PREV`	上一曲
`lv.SYMBOL_PLAY`	播放	`lv.SYMBOL_PAUSE`	暂停
`lv.SYMBOL_STOP`	停止	`lv.SYMBOL_NEXT`	下一曲
`lv.SYMBOL_EJECT`	弹出	`lv.SYMBOL_LEFT`	左
`lv.SYMBOL_RIGHT`	右	`lv.SYMBOL_PLUS`	加
`lv.SYMBOL_MINUS`	减	`lv.SYMBOL_EYE_OPEN`	睁眼
`lv.SYMBOL_EYE_CLOSE`	闭眼	`lv.SYMBOL_WARNING`	警告
`lv.SYMBOL_SHUFFLE`	随机	`lv.SYMBOL_UP`	上
`lv.SYMBOL_DOWN`	下	`lv.SYMBOL_LOOP`	循环
`lv.SYMBOL_DIRECTORY`	目录	`lv.SYMBOL_UPLOAD`	上传
`lv.SYMBOL_CALL`	呼叫	`lv.SYMBOL_CUT`	剪切
`lv.SYMBOL_COPY`	复制	`lv.SYMBOL_SAVE`	保存
`lv.SYMBOL_BARS`	柱状图	`lv.SYMBOL_ENVELOPE`	信封
`lv.SYMBOL_CHARGE`	充电	`lv.SYMBOL_PASTE`	粘贴
`lv.SYMBOL_BELL`	铃铛	`lv.SYMBOL_KEYBOARD`	键盘
`lv.SYMBOL_GPS`	GPS	`lv.SYMBOL_FILE`	文件
`lv.SYMBOL_WIFI`	WiFi	`lv.SYMBOL_BATTERY_FULL`	满电
`lv.SYMBOL_BATTERY_3`	电量3	`lv.SYMBOL_BATTERY_2`	电量2
`lv.SYMBOL_BATTERY_1`	电量1	`lv.SYMBOL_BATTERY_EMPTY`	空电
`lv.SYMBOL_USB`	USB	`lv.SYMBOL_BLUETOOTH`	蓝牙
`lv.SYMBOL_TRASH`	回收站	`lv.SYMBOL_EDIT`	编辑
`lv.SYMBOL_BACKSPACE`	退格	`lv.SYMBOL_SD_CARD`	SD 卡

完整示例#

示例	说明	源码
基础控件	按钮/复选框/滑块/进度条/弧形/开关/LED	quick_widgets.py
图片加载	PNG/BMP 加载、旋转、缩放	demo_image.py
样式定制	颜色/圆角/阴影/渐变/模糊	demo_style.py
Flex 布局	行/列/换行/对齐	demo_flex.py
FreeType 中文	加载 TTF 字体显示中文	demo_chinese.py
动画图片	animimg 帧动画	demo_animimg.py
仪表盘	anim_t 驱动弧形动画 / timer 定时刷新	lvgl_python_benchmark.py

FreeType 字体支持#

LVGL 内置的 Montserrat 字体仅包含拉丁字符。要显示中文、日文、韩文等 CJK 字符，需通过 FreeType 加载 TTF/OTF 字体。

加载字体#

# 创建 FreeType 字体 (返回 lv.font 对象)
font = lv.freetype_font_create(
    "/usr/lib/fonts/SourceHanSansSC-Normal-Min.ttf",  # 字体文件路径
    lv.FREETYPE_RENDER.BITMAP,                     # 渲染模式
    24,                                                  # 字号 (px)
    lv.FREETYPE_STYLE.NORMAL,                      # 样式
)

使用字体#

label = lv.label(scr)
label.set_style_text_font(font, lv.SELECTOR.DEFAULT)   # 设置字体 (SELECTOR.DEFAULT = 默认状态)
label.set_text("你好，世界！")

释放字体#

字体对象在 Python GC 回收时自动释放，也可手动释放：

lv.freetype_font_delete(font)

渲染模式 (`lv.FREETYPE_RENDER`)#

模式	说明
`BITMAP`	位图渲染 (推荐，性能好)
`OUTLINE`	矢量轮廓渲染 (支持任意缩放，性能较低)

字体样式 (`lv.FREETYPE_STYLE`)#

样式	说明
`NORMAL`	正常
`ITALIC`	斜体
`BOLD`	粗体

font 类#

font = lv.freetype_font_create(...)
font.is_valid()   # 检查字体是否有效

完整示例

完整源码: quick_chinese.py | demo_chinese.py

注意事项#

字体文件: K230 设备预装 SourceHanSansSC-Normal-Min.ttf（思源黑体精简版）于 /usr/lib/fonts/。精简版仅包含常用汉字，部分特殊符号（如 °、℃）可能缺失，可用中文替代（如”度”）。
性能: FreeType 字体首次渲染某个字符时需要光栅化，后续使用缓存。BITMAP 模式比 OUTLINE 模式性能更好。
字号: 每个字号需创建独立的字体对象。如需 16px 和 24px，需调用两次 freetype_font_create。
生命周期: 字体对象由 Python GC 管理。确保字体对象在 label 使用期间不被回收。

已知限制#

以下功能因 C API 参数/返回类型限制，未在 Python 绑定中暴露：

类别	未绑定功能	原因
样式对象	`lv_style_*`	涉及 `lv_style_t*` 结构体操作
事件发送	`lv_event_send`, `lv_event_get_*`	涉及 `lv_event_t*` 参数
内存/字符串	`lv_malloc`, `lv_memcpy`, `lv_strdup` 等	手动跳过规则
日志	`lv_log`, `lv_log_register_print_cb`	手动跳过规则
按钮/控件矩阵	`lv_buttonmatrix_*`	涉及复杂 C 数组/回调参数

注意: 动画 (anim_t)、定时器 (timer_t)、分组 (group_*)、输入设备 (indev_*)、显示 (display_*) 已在本次更新中绑定暴露。

统计：

统计项	数量
`.def()` 绑定 (方法+函数，含重载)	902
└ 模块级独立函数 `m.def()`	78
└ Obj 类方法 `obj_cls.def()` (含 99 个 `_widget_method` 分派)	786+
去重后唯一方法名	881
枚举类 `py::enum_`	96
枚举成员值 `.value()`	651
模块常量 `m.attr()` (SYMBOL/OPA/ANIM)	651+
类 `py::class_`	8
控件工厂函数	26

文档生成时间: 2026-07-28

基于 lvgl_pybind_generated.cpp 自动分析 + _wrapper.py 手动补充生成

LVGL Python API

目录

LVGL Python API#

快速开始#

初始化与驱动#

lv.init(v4l2_drm=None, v4l2_drm_run_flag=0)#

lv.run()#

模块级函数#

核心#

版本信息#

显示#

定时器#

动画#

分组#

主题#

调色板#

输入设备#

驱动后端#

FreeType 字体#

颜色 (color)#

创建颜色#

color 属性#

透明度常量#

类 (Classes)#

基础对象 obj#

创建 (obj)#

位置与尺寸#

对齐#

层级与父子关系#

删除#

事件绑定 (简写)#

淡入淡出#

变换#

坐标与可见性#

控件 (Widgets)#

button#

label#

image#

arc#

bar#

slider#

switch#

checkbox#

dropdown#

roller#

textarea#

keyboard#

chart#

table#

tabview#

list#

menu#

msgbox#

led#

line#

canvas#

scale#

spinbox#

spinner#

tileview#

win#

animimg#

动画 (anim_t)#

创建 (anim_t)#

常用方法 (anim_t) |#

运动路径#

常量#

定时器 (timer_t)#

创建 (timer_t)#

常用方法 (timer_t) |#

显示 (display)#

创建 (display)#

常用方法 (display) |#

枚举 (display)#

输入设备 (indev)#

创建 (indev)#

常用方法 (indev)#

枚举 (indev)：NONE, POINTER, KEYPAD, BUTTON, ENCODER#

分组 (group)#

使用方式#

`lv.init(v4l2_drm=None, v4l2_drm_run_flag=0)`#

`lv.run()`#

枚举 (indev)：`NONE`, `POINTER`, `KEYPAD`, `BUTTON`, `ENCODER`#

完整事件码 (`lv.EVENT`, 76 个)#

对象标志 (`lv.OBJ_FLAG`)#

对象状态 (`lv.STATE`)#

对齐 (`lv.ALIGN`)#

方向 (`lv.DIR`)#

文本对齐 (`lv.TEXT_ALIGN`)#

文本装饰 (`lv.TEXT_DECOR`)#

颜色格式 (`lv.COLOR_FORMAT`)#

调色板 (`lv.PALETTE`)#

混合模式 (`lv.BLEND_MODE`)#

滚动条模式 (`lv.SCROLLBAR_MODE`)#

边框边 (`lv.BORDER_SIDE`)#

按键 (`lv.KEY`)#

渐变方向 (`lv.GRAD_DIR`)#

渐变扩展 (`lv.GRAD_EXTEND`)#

模糊质量 (`lv.BLUR_QUALITY`)#

文本方向 (`lv.BASE_DIR`)#

输入设备类型 (`lv.INDEV_TYPE`)#

输入设备模式 (`lv.INDEV_MODE`)#

显示渲染模式 (`lv.DISPLAY_RENDER`)#

控件部分 (`lv.PART`)#

覆盖结果 (`lv.COVER`)#

渲染模式 (`lv.FREETYPE_RENDER`)#

字体样式 (`lv.FREETYPE_STYLE`)#