1. 快速上手

1. 根据ESP32 MicroPython教程下载、烧录固件

2. 上传对应的屏幕驱动（screen.py）到MicroPython设备。上传文件方法

3. 将下面代码复制到Thonny中，点击执行脚本，可以看到屏幕上显示效果

import screen
import lvgl as lv

scr = lv.screen_active()# 获取当前激活的屏幕对象
scr.set_style_bg_color(lv.color_hex(0x000000), 0)# 设置屏幕的背景颜色为黑色

slider = lv.slider(scr)# 创建一个滑块
slider.set_size(100, 25)# 设置滑块的大小为宽度300，高50
slider.center()# 将滑块居中显示

label = lv.label(scr)# 创建一个标签
label.set_text('HELLO LVGL_MICROPYTHON!')# 标签内容
label.align(lv.ALIGN.CENTER, 0, -50)# 将标签对齐到屏幕中心，并向上偏移50

显示效果

2. 显示案例

2.1 时间表盘

import screen
import time
import lvgl as lv
from machine import Timer
import math

scrn = lv.screen_active()
scrn.set_style_bg_color(lv.color_hex(0x000000), 0)

class AnalogClock:
    def __init__(self, parent):
        self.scale = None
        self.second_hand = None
        self.minute_hand = None
        self.hour_hand = None
        # 获取当前时间
        now = time.localtime()
        self.hour = now[3] % 12  # 转换为12小时制
        self.minute = now[4]
        self.second = now[5]
        self.create_clock(parent)
        self.start_timer()

    def create_clock(self, parent):
        """创建模拟时钟组件"""
        # 创建表盘主体（保持120x120大小）
        self.scale = lv.scale(parent)
        self.scale.set_size(200, 200)
        self.scale.set_mode(lv.scale.MODE.ROUND_INNER)
        
        # 设置表盘样式（保持不变）
        self.scale.set_style_bg_opa(lv.OPA._60, 0)
        self.scale.set_style_bg_color(lv.color_hex(0x222222), 0)
        self.scale.set_style_radius(lv.RADIUS_CIRCLE, 0)
        self.scale.set_style_clip_corner(True, 0)
        self.scale.center()

        # 配置刻度系统（保持不变）
        self.scale.set_label_show(True)
        hour_labels = ["12", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", None]
        self.scale.set_text_src(hour_labels)
        self.scale.set_style_text_font(lv.font_montserrat_12, 0)
        self.scale.set_total_tick_count(61)
        self.scale.set_major_tick_every(5)

        # 主刻度样式（保持不变）
        style_indicator = lv.style_t()
        style_indicator.init()
        style_indicator.set_text_color(lv.color_hex(0xFFFFFF))
        style_indicator.set_line_color(lv.color_hex(0xFFFFFF))
        style_indicator.set_length(5)
        style_indicator.set_line_width(2)
        self.scale.add_style(style_indicator, lv.PART.INDICATOR)

        # 次刻度样式（保持不变）
        style_minor = lv.style_t()
        style_minor.init()
        style_minor.set_line_color(lv.color_hex(0xAAAAAA))
        style_minor.set_length(3)
        style_minor.set_line_width(1)
        self.scale.add_style(style_minor, lv.PART.ITEMS)

        # 表盘边框样式（保持不变）
        style_main = lv.style_t()
        style_main.init()
        style_main.set_arc_color(lv.color_hex(0x222222))
        style_main.set_arc_width(3)
        self.scale.add_style(style_main, lv.PART.MAIN)

        # 设置量程和角度（保持不变）
        self.scale.set_range(0, 60)
        self.scale.set_angle_range(360)
        self.scale.set_rotation(270)

        # 创建秒针（红色，长度90px，细线）
        self.second_hand = lv.line(self.scale)
        self.second_hand.set_style_line_width(1, 0)  # 更细的线宽
        self.second_hand.set_style_line_rounded(True, 0)
        self.second_hand.set_style_line_color(lv.color_hex(0xFFFFFF), 0)

        # 创建分钟指针（蓝色，长度75px）
        self.minute_hand = lv.line(self.scale)
        self.minute_hand.set_style_line_width(3, 0)
        self.minute_hand.set_style_line_rounded(True, 0)
        self.minute_hand.set_style_line_color(lv.color_hex(0x00BFFF), 0)

        # 创建小时指针（橙色，长度60px）
        self.hour_hand = lv.line(self.scale)
        self.hour_hand.set_style_line_width(5, 0)
        self.hour_hand.set_style_line_rounded(True, 0)
        self.hour_hand.set_style_line_color(lv.color_hex(0xFFA500), 0)

        # 添加中心点（保持不变）
        center = lv.obj(self.scale)
        center.set_size(8, 8)  # 稍微减小中心点大小
        center.center()
        center.set_style_radius(lv.RADIUS_CIRCLE, 0)
        center.set_style_bg_color(lv.color_hex(0xFFD700), 0)
        center.set_style_bg_opa(lv.OPA.COVER, 0)

        self.update_hands()

    def update_hands(self):
        """更新所有指针位置"""
        # 秒针（90px长度）
        lv.scale.set_line_needle_value(self.scale, self.second_hand, 90, self.second)
        
        # 分钟指针（75px长度）
        lv.scale.set_line_needle_value(self.scale, self.minute_hand, 75, self.minute)
        
        # 小时指针（60px长度），考虑分钟偏移
        hour_value = self.hour * 5 + (self.minute // 12)
        lv.scale.set_line_needle_value(self.scale, self.hour_hand, 60, hour_value)

    def timer_callback(self, timer):
        """定时器回调(每秒更新)"""
        # 获取当前时间
        now = time.localtime()
        self.hour = now[3] % 12
        self.minute = now[4]
        self.second = now[5]
        
        self.update_hands()

    def start_timer(self):
        """启动硬件定时器(每秒触发)"""
        self.timer = Timer(1)
        self.timer.init(period=1000, mode=Timer.PERIODIC, callback=self.timer_callback)

# 创建时钟实例
clock = AnalogClock(scrn)

2.1 菜单选项卡切换页面

import lvgl as lv
import screen

scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

def controls_create(parent):
    parent.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)
    parent.set_flex_align(lv.FLEX_ALIGN.SPACE_EVENLY, lv.FLEX_ALIGN.CENTER,
                          lv.FLEX_ALIGN.CENTER)

    # Button
    btn = lv.button(parent)
    btn.set_size(100, 50)
    lbl = lv.label(btn)
    lbl.set_text("Button")
    lbl.center()

    # Switch
    sw = lv.switch(parent)

    # Checkbox
    cb = lv.checkbox(parent)
    cb.set_text("Check")

    # Slider + label
    slider = lv.slider(parent)
    slider.set_range(0, 100)
    slider.set_value(40, False)
    slider.set_size(150, 10)

    lbl_val = lv.label(parent)
    lbl_val.set_text("40")
    slider.add_event_cb(lambda e: lbl_val.set_text(str(slider.get_value())),
                        lv.EVENT.VALUE_CHANGED, None)

# ---------- Visuals 页面 ----------
def visuals_create(parent):
    parent.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)
    parent.set_flex_align(lv.FLEX_ALIGN.SPACE_EVENLY, lv.FLEX_ALIGN.CENTER,
                          lv.FLEX_ALIGN.CENTER)

    # Line chart
    chart = lv.chart(parent)
    chart.set_size(220, 130)
    chart.set_type(lv.chart.TYPE.LINE)
    chart.set_point_count(8)
    chart.set_div_line_count(3, 5)

    ser1 = chart.add_series(lv.color_hex(0x01a2b1), lv.chart.AXIS.PRIMARY_Y)
    ser2 = chart.add_series(lv.color_hex(0x44d1b6), lv.chart.AXIS.PRIMARY_Y)
    for v in [10, 90, 30, 60, 10, 90, 30, 60]:
        chart.set_next_value(ser1, v)
    for v in [32, 66, 5, 47, 32, 66, 5, 47]:
        chart.set_next_value(ser2, v)

    # Arc
    arc = lv.arc(parent)
    arc.set_size(120, 120)
    arc.set_range(0, 100)
    arc.set_value(50)

# ---------- Selectors 页面 ----------
def selectors_create(parent):
    parent.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)
    parent.set_flex_align(lv.FLEX_ALIGN.SPACE_EVENLY, lv.FLEX_ALIGN.CENTER,
                          lv.FLEX_ALIGN.CENTER)

    # Calendar
    cal = lv.calendar(parent)
    cal.set_size(160, 160)

    # Dropdown
    dd = lv.dropdown(parent)
    dd.set_options("Alpha\nBravo\nCharlie\nDelta")
    dd.set_size(120, 40)

    # Roller
    roller = lv.roller(parent)
    roller.set_options("A\nB\nC\nD\nE", lv.roller.MODE.NORMAL)
    roller.set_size(120, 60)

# ---------- 主界面 ----------
tabview = lv.tabview(scr)
tabview.set_size(480, 320)

tab1 = tabview.add_tab("Controls")
tab2 = tabview.add_tab("Visuals")
tab3 = tabview.add_tab("Selectors")

controls_create(tab1)
visuals_create(tab2)
selectors_create(tab3)

显示效果

注：该显示效果图为在线模拟图像，实际屏幕显示颜色、大小可能不同。

3.基础知识

3.1 对象

在 LVGL（Light and Versatile Graphics Library）中，对象（Object） 是整个 UI 系统的核心构建块，是所有 UI 元素的基础。可以将其理解为构成用户界面的 "基本单元"。
LVGL 中的对象具有以下特点：

1. 抽象概念：对象是一个抽象的概念，代表屏幕上可以交互或显示的元素
2. 继承关系：所有具体的 UI 组件（如按钮、标签、滑块等）都是基于基础对象扩展而来
3. 属性丰富：每个对象都有位置、大小、颜色、透明度等基本属性
4. 层级结构：对象可以相互嵌套，形成父子关系，便于管理复杂 UI
5. 事件驱动：对象可以响应各种事件（如点击、滑动等）
   例如，当你创建一个按钮时，它本质上是一个特殊的对象，继承了基础对象的所有属性和方法，同时又添加了按钮特有的功能（如按下状态、点击事件等）。
   通过操作对象，可以实现几乎所有 UI 功能：创建组件、设置样式、处理交互等。

3.2 状态

在 LVGL 中，状态（State） 是描述对象（如按钮、滑块等 UI 组件）当前行为或交互状态的属性，用于控制对象在不同场景下的外观和行为。状态会影响对象的样式表现（如颜色、尺寸、透明度等），是实现交互反馈的核心机制。
基础状态

'''
DEFAULT   #控件的默认状态样式,当没有其他状态触发时，默认应用此样式。
CHECKED   #控件被选中时的样式,适用于复选框（checkbox）、单选按钮（radio button）等具有 "选中" 状态的控件。
FOCUSED   #控件获得焦点时的样式（例如通过键盘导航或触摸选中），通常用于指示当前可交互的控件。
FOCUS_KEY #控件通过键盘（如 Tab 键）获得焦点时的样式，与FOCUSED的区别在于它专门针对键盘触发的焦点。
EDITED    #控件处于编辑状态时的样式，例如输入框（text field）被激活并正在输入内容时。
HOVERED   #鼠标悬停在控件上时的样式（仅在支持鼠标的设备上有效），用于增强桌面或触控板设备的交互体验。
PRESSED   #控件被按下时的样式（如按钮被点击但未释放时），用于提供即时的视觉反馈。
SCROLLED  #滚动类控件（如列表、页面、滚动容器）处于滚动状态时的样式，可用于美化滚动过程中的视觉效果。
DISABLED  #控件被禁用时的样式，通常表现为灰度化或半透明，提示用户该控件当前不可交互。
USER_1    #用户自定义状态
USER_2    #用户自定义状态
USER_3    #用户自定义状态
USER_4    #用户自定义状态
ANY       #匹配控件的所有状态
'''

组合状态
对象可以通过位运算组合，同时处于多个状态，例如：

• 一个按钮可能同时处于按下且聚焦状态 (lv.STATE.PRESSED | lv.STATE.FOCUSED)
• 一个复选框可能同时处于选中但禁用 (lv.STATE.CHECKED | lv.STATE.DISABLED)

3.3 样式

在 LVGL 中，样式（Style） 是定义 UI 对象外观特征的核心机制，用于统一控制界面元素的视觉表现，如颜色、尺寸、字体、边框等。通过样式系统，你可以轻松实现美观且一致的 UI 设计，并灵活应对不同状态下的视觉变化。
样式的核心特性

1. 属性集合：样式是一系列视觉属性的集合，涵盖背景、边框、文本、间距距等多种视觉特征。
2. 状态绑定：同一对象在不同状态（如默认、按下、选中）下可应用不同样式（例如按钮按下时变色）。
3. 复用与继承：一个样式可被多个对象共享，也可基于现有样式扩展新样式，减少重复定义。
4. 动态修改：运行时可实时修改样式属性，实现主题切换、动画效果等动态视觉变化。

LVGL 提供了丰富的样式属性，可满足各类视觉需求，更多样式见MicroPython LVGL API.py文件的"class style_t"部分
示例：样式与状态结合使用

#创建样式。更多api见api.py文件的"class style_t"部分
style_btn = lv.style_t()
#设置背景颜色
style_btn.set_bg_color(lv.color_hex(0xFF0000))
#应用为点击状态样式。
btn.add_style(style_btn,lv.STATE.PRESSED)

3.4 事件

在 LVGL 中，事件（Event） 是用于处理用户交互或系统状态变化的机制，是实现 UI 交互逻辑的核心。当用户对 UI 元素（如按钮、滑块等）进行操作（点击、滑动等），或对象状态发生变化时，LVGL 会触发相应的事件，开发者可以通过注册事件回调函数来响应这些事件，实现特定功能。有如下事件类型：

def btn_clicked(e):  #点击按键回调函数
    print("Button clicked!")
btn.add_event_cb(btn_clicked, lv.EVENT.CLICKED, None) #设置交互回调函数
#有以下事件类型
'''
### 交互相关事件
PRESSED：对象被按下时触发（如按钮被触摸或鼠标点击）。
PRESSING：对象被持续按压时重复触发（按下状态中持续发送）。
PRESS_LOST：按压对象时，输入设备（如触摸）意外离开对象区域时触发。
SHORT_CLICKED：短按后释放时触发（按下时间短于长按阈值）。
SINGLE_CLICKED：单次点击（按下并释放）触发。
DOUBLE_CLICKED：双击（快速两次点击）触发。
TRIPLE_CLICKED：三击（快速三次点击）触发。
LONG_PRESSED：长按达到阈值时间时触发一次。
LONG_PRESSED_REPEAT：长按持续期间重复触发（用于连续操作，如音量调节）。
CLICKED：通用点击事件（包含单 / 多击，需结合其他事件判断具体类型）。
RELEASED：对象被释放时触发（按压后抬起）。

### 滚动与滑动事件
SCROLL_BEGIN：滚动开始时触发。
SCROLL_THROW_BEGIN：滑动（fling）动作开始时触发（如快速滑动列表后松手，列表继续滚动）。
SCROLL_END：滚动（包括滑动惯性滚动）结束时触发。
SCROLL：滚动过程中持续触发（可获取实时滚动位置）。

### 手势与输入事件
GESTURE：检测到手势时触发（如滑动、缩放、旋转等）。
KEY：键盘或按键输入时触发（如按下 / 释放按键）。
ROTARY：旋转编码器（如旋钮）输入时触发（用于调节数值）。

### 焦点与 hover 事件
FOCUSED：对象获得焦点时触发（如通过键盘导航选中）。
DEFOCUSED：对象失去焦点时触发。
HOVER_OVER：指针（如鼠标）悬停到对象上时触发。
HOVER_LEAVE：指针从对象上移开时触发。
LEAVE：输入设备（如触摸）离开对象区域时触发（与PRESS_LOST类似，但不依赖按压状态）。

### 绘制与渲染事件
DRAW_MAIN_BEGIN：主绘制阶段开始前触发。
DRAW_MAIN：主绘制阶段中触发（用于自定义绘制逻辑）。
DRAW_MAIN_END：主绘制阶段结束后触发。
DRAW_POST_BEGIN：后绘制阶段开始前触发（用于覆盖层绘制）。
DRAW_POST：后绘制阶段中触发。
DRAW_POST_END：后绘制阶段结束后触发。
DRAW_TASK_ADDED：新的绘制任务被添加时触发。
REFR_EXT_DRAW_SIZE：获取对象外部绘制区域大小时触发（用于阴影、边框等超出对象范围的绘制）。

### 刷新与渲染流程事件
REFR_REQUEST：请求刷新屏幕时触发。
REFR_START：屏幕刷新开始时触发。
REFR_READY：刷新数据准备就绪时触发。
RENDER_START：渲染开始时触发。
RENDER_READY：渲染完成并准备输出时触发。
FLUSH_START：将渲染数据刷新到显示设备时开始触发。
FLUSH_FINISH：数据刷新到显示设备完成时触发。
FLUSH_WAIT_START：开始等待刷新完成时触发。
FLUSH_WAIT_FINISH：结束等待刷新完成时触发。
VSYNC：垂直同步信号到来时触发（用于同步渲染帧率）。
VSYNC_REQUEST：请求垂直同步信号时触发。

### 对象状态与生命周期事件
CREATE：对象被创建时触发。
DELETE：对象被删除时触发。
MARKED_DELETING：对象被标记为待删除时触发。
CHILD_CHANGED：对象的子对象发生变化（添加 / 删除）时触发。
CHILD_CREATED：子对象被创建时触发。
CHILD_DELETED：子对象被删除时触发。
SIZE_CHANGED：对象尺寸发生变化时触发。
STYLE_CHANGED：对象样式（如颜色、字体）发生变化时触发。
LAYOUT_CHANGED：对象布局（如位置、排列）发生变化时触发。
GET_SELF_SIZE：获取对象自身尺寸（不包含子对象）时触发（用于自定义布局计算）。
INVALIDATE_AREA：对象的某个区域需要重绘时触发。

### 屏幕切换事件
SCREEN_LOAD_START：屏幕开始加载时触发。
SCREEN_LOADED：屏幕加载完成时触发。
SCREEN_UNLOAD_START：屏幕开始卸载时触发。
SCREEN_UNLOADED：屏幕卸载完成时触发。

### 其他通用事件
ALL：表示所有事件（用于注册监听所有事件）。
VALUE_CHANGED：对象值发生变化时触发（如滑块、复选框状态变化）。
INSERT：向容器中插入元素时触发（如列表添加项）。
REFRESH：对象需要刷新时触发（强制更新显示）。
READY：对象准备就绪时触发（如初始化完成）。
CANCEL：操作被取消时触发（如对话框取消按钮）。
HIT_TEST：检测输入是否命中对象时触发（用于自定义点击区域）。
INDEV_RESET：输入设备被重置时触发。
COVER_CHECK：检查对象是否被其他对象覆盖时触发。
RESOLUTION_CHANGED：屏幕分辨率变化时触发。
COLOR_FORMAT_CHANGED：屏幕颜色格式变化时触发。
PREPROCESS：事件预处理时触发（用于自定义事件过滤）。
LAST：事件类型的占位符，表示最后一个事件（用于内部枚举定义）。
'''

示例：事件使用

#交互回调函数
def btn_event_cb(e):  
    print("Button clicked!")
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
btn.add_event_cb(btn_event_cb, lv.EVENT.PRESSED, None) 

4. 控件介绍

注：该章节中的显示效果图为在线模拟图像，实际屏幕显示颜色、大小可能不同。

4.1 基础对象

下面代码创建了一个名为"obj "的对象，设置"obj "的坐标和尺寸，并调整其风格

• 更多API见MicroPython LVGL API.py文件的"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建对象
obj = lv.obj(scr)
#设置对象位置与尺寸
obj.set_pos(100, 100)   #设置对象的左上角坐标
obj.set_size(100, 100)  #设置对象的宽度和高度

#创建样式
style_obj = lv.style_t()
#边框与背景
style_obj .set_pad_all(10)    #设置四个方向内边距
#style_obj  .set_pad_left(10)   #设置左内边距
#style_obj .set_pad_right(10)  #设置右内边距
#style_obj .set_pad_top(10)    #设置上内边距
#style_obj  .set_pad_bottom(10) #设置下内边距
style_obj .set_bg_opa(255)  #设置背景透明度，0为完全透明
style_obj .set_bg_color(lv.color_hex(0xFF0000))   #设置背景颜色
style_obj .set_border_color(lv.color_hex(0x00FF00))   #设置边框颜色
style_obj  .set_border_width(2)   #设置边框宽度
style_obj .set_border_opa(255)   #设置边框透明度，0为完全透明
#阴影样式
style_obj .set_shadow_color(lv.color_hex(0x00FF00))#设置阴影颜色
style_obj .set_shadow_width(10)#设置阴影宽度（阴影扩散范围）
style_obj .set_shadow_opa(50)#设置阴影透明度
style_obj .set_shadow_offset_x(10)#设置阴影水平偏移量
style_obj .set_shadow_offset_y(10)#设置阴影水平偏移量
#应用样式
obj.add_style(style_obj , lv.STATE.DEFAULT)

显示效果

4.2. 标签（label）

下面代码创建了一个名为"label"的标签对象，设置"label"的显示内容、位置，并调整其风格

• 更多API见MicroPython LVGL API.py文件的"class label"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建标签
label = lv.label(scr)
#设置长文本显示模式。更多参数见api.py文件的"class LONG_MODE"部分
label.set_long_mode(label.LONG_MODE.SCROLL_CIRCULAR)
#设置标签显示长宽
label.set_size(100,20)
#设置标签内容
label.set_text('HELLO MicroPython LVGL')  
#将标签对齐到容器中心，并向上偏移50。更多参数见api.py文件的"class ALIGN"部分
label.align(lv.ALIGN.CENTER, 0, -50)

##创建样式。更多api见api.py文件的"class style_t"部分
style_label = lv.style_t()     
#文本颜色
style_label.set_text_color(lv.color_hex(0xFF0000))  
#设置字体，支持12，14，16
style_label.set_text_font(lv.font_montserrat_16)
#应用为默认状态样式。更多状态见api.py文件的"class STATE"部分
label.add_style(style_label , lv.STATE.DEFAULT)

4.3 按钮（button）

• 更多API见MicroPython LVGL API.py文件的"class button"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建按钮
btn = lv.button(scr)
#设置尺寸
btn.set_size(100, 50)
#居中显示
btn.center()

#创建样式。更多api见api.py文件的"class style_t"部分
style_btn = lv.style_t()
#设置背景颜色
style_btn.set_bg_color(lv.color_hex(0xFF0000))
#应用为点击状态样式。更多状态见api.py文件的"class STATE"部分
btn.add_style(style_btn,lv.STATE.PRESSED)

#交互回调函数
def btn_event_cb(e):  
    print("Button clicked!")
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
btn.add_event_cb(btn_event_cb, lv.EVENT.PRESSED, None) 

显示效果

4.4矩阵按钮（Button matrix）

• 更多API见MicroPython LVGL API.py文件的"class buttonmatrix"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建矩阵按钮
btnm = lv.buttonmatrix(scr)
#设置3个按钮
btnm_map = ["A1", "A2", "A3"]
btnm.set_map(btnm_map)
#居中显示
btnm.center()

#交互回调函数
def btnm_event_cb(e):
    #获取被点击的按钮索引
    pressed_btn = btnm.get_selected_button()  
    if pressed_btn != -1:
        #获取对应索引按键的本文
        text_btn = btnm.get_button_text(pressed_btn)
        print(f"按钮{text_btn}被点击")
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
btnm.add_event_cb(btnm_event_cb, lv.EVENT.CLICKED, None)

显示效果

4.5 开关（switch）

• 更多API见MicroPython LVGL API.py文件的"class switch"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建开关
switch = lv.switch(scr)
#设置尺寸
switch.set_size(100, 50)
#居中显示
switch.center()

#交互回调函数
def switch_event_cb(e):
    if switch.has_state(lv.STATE.CHECKED):
        print("开关已开启")
    else:
        print("开关已关闭")
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
switch.add_event_cb(switch_event_cb, lv.EVENT.VALUE_CHANGED, None)

显示效果

4.6 指示灯（LED）

• 更多API见MicroPython LVGL API.py文件的"class led"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建LED
led = lv.led(scr)
#设置尺寸
led.set_size(50, 50)
#设置点亮时的颜色
led.set_color(lv.color_hex(0xFF0000))
# 设置亮度，亮度范围：0-255
led.set_brightness(150)  
#居中显示
led.center()

#点亮
#led.on()
#熄灭
#led.off()
# 翻转状态
#led.toggle() 

显示效果

4.7 复选框（checkbox）

• 更多API见MicroPython LVGL API.py文件的"class checkbox"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建复选框
cb = lv.checkbox(scr)
#设置复选框文本
cb.set_text("checkbox")  
#居中显示
cb.center()

#交互回调函数
def cb_event_cb(e):
    if cb.has_state(lv.STATE.CHECKED):
        print("已勾选")
    else:
        print("未勾选")
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
cb.add_event_cb(cb_event_cb, lv.EVENT.VALUE_CHANGED, None) 

显示效果

4.8 弧线（arc）

• 更多API见MicroPython LVGL API.py文件的"class arc"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建弧线
arc = lv.arc(scr)
#设置弧线大小
arc.set_size(150, 150)
#设置弧线数值范围
arc.set_range(0, 100)
#设置当前值
arc.set_value(10)
#居中显示
arc.center()

# 创建数值显示标签
lbl_val = lv.label(scr)
lbl_val.set_text(str(arc.get_value()))
lbl_val.align(lv.ALIGN.CENTER, 0, 0)

#交互回调函数
def arc_event_cb(e):
    current_val = arc.get_value()
    lbl_val.set_text(str(current_val))
    print(current_val)
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
arc.add_event_cb(arc_event_cb, lv.EVENT.VALUE_CHANGED, None)

显示效果

4.9滑动条（slider）

• 更多API见MicroPython LVGL API.py文件的"class slider"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建滑动条
slider = lv.slider(scr)
#设置滑动条大小
slider.set_size(300, 50)
#设置滑动条数值范围
slider.set_range(0, 100)
#居中显示
slider.center()

#创建数值显示标签
lbl_val = lv.label(scr)
lbl_val.set_text(str(slider.get_value()))
lbl_val.align(lv.ALIGN.CENTER, 0, -50)

#交互回调函数
def slider_event_cb(e):
    current_val = slider.get_value()
    lbl_val.set_text(str(current_val))
    print(current_val)
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
slider.add_event_cb(slider_event_cb, lv.EVENT.VALUE_CHANGED, None)

显示效果

4.10线段（line）

• 更多API见MicroPython LVGL API.py文件的"class line"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建线段
line = lv.line(scr)
#定义线段的顶点坐标 (x, y)
points = [
    lv.point_precise_t({'x': 50, 'y': 50}),
    lv.point_precise_t({'x': 150, 'y': 100}),
    lv.point_precise_t({'x': 250, 'y': 50}),
    lv.point_precise_t({'x': 300, 'y': 150})
]
# 设置线段的顶点
line.set_points(points, len(points))

4.11 图表（chart）

• 更多API见MicroPython LVGL API.py文件的"class chart"和"class obj"部分

折线图

import screen
import lvgl as lv
import time
import random

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建折线图
chart = lv.chart(scr)
chart.set_size(300, 200)  # 设置图表大小
chart.center()            # 居中显示

# 配置图表
chart.set_type(lv.chart.TYPE.LINE)          # 设置为折线图
chart.set_point_count(10)                   # 每个系列的数据点数量
chart.set_update_mode(lv.chart.UPDATE_MODE.SHIFT)  # 数据更新模式：移位
chart.set_div_line_count(3, 3)              # 设置网格线数量

# 设置坐标轴范围
chart.set_axis_range(lv.chart.AXIS.PRIMARY_Y, 0, 100)
chart.set_axis_range(lv.chart.AXIS.PRIMARY_X, 0, 10)

# 添加数据系列（线条）
ser1 = chart.add_series(lv.color_hex(0xFF0000), lv.chart.AXIS.PRIMARY_Y)  # 红色线条
ser2 = chart.add_series(lv.color_hex(0x0000FF), lv.chart.AXIS.PRIMARY_Y)  # 蓝色线条

# 初始化数据
chart.set_all_values(ser1, 0)
chart.set_all_values(ser2, 0)

# 模拟实时数据更新
while True:
    # 生成随机数据并添加到系列中
    val1 = random.randint(20, 80)
    val2 = random.randint(10, 90)
    chart.set_next_value(ser1, val1)
    chart.set_next_value(ser2, val2)
    time.sleep_ms(500)

柱状图

import screen
import lvgl as lv
import time
import random

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建折线图
chart = lv.chart(scr)
chart.set_size(300, 220)  # 设置图表大小
chart.center()            # 居中显示

# 配置图表为柱状图类型
chart.set_type(lv.chart.TYPE.BAR)

# 设置数据点数量（柱子数量）
chart.set_point_count(6)

# 设置网格线：3条水平线，2条垂直线
chart.set_div_line_count(3, 2)

# 设置Y轴范围（数据值范围）
chart.set_axis_range(lv.chart.AXIS.PRIMARY_Y, 0, 100)

# 添加两个数据系列（两组柱子）
# 第一组：红色柱子，使用主Y轴
ser1 = chart.add_series(lv.color_hex(0xFF5733), lv.chart.AXIS.PRIMARY_Y)
# 第二组：蓝色柱子，使用主Y轴
ser2 = chart.add_series(lv.color_hex(0x3377FF), lv.chart.AXIS.PRIMARY_Y)

# 设置第一组数据
data1 = [30, 45, 28, 67, 50, 75]
chart.set_series_values(ser1, data1, len(data1))

# 设置第二组数据
data2 = [20, 55, 38, 47, 60, 55]
chart.set_series_values(ser2, data2, len(data2))

4.12日历（Calendar）

• 更多API见MicroPython LVGL API.py文件的"class calendar"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建日历对象
calendar = lv.calendar(scr)
#设置大小
calendar.set_size(250, 250)
#居中显示
calendar.center()
# 设置今天日期（2023年10月15日）
calendar.set_today_date(2023, 10, 15)
# 设置当前显示的月份
shown_date = lv.calendar_date_t()
shown_date.year = 2023
shown_date.month = 10
# 添加头部箭头（用于切换月份）
calendar.add_header_arrow()
# 添加头部下拉菜单（用于选择年月）
calendar.add_header_dropdown()
# 设置年份列表（2020-2030）
year_list = "\n".join([str(y) for y in range(2020, 2031)])
calendar.header_dropdown_set_year_list(year_list)

4.13文本框（Text area）

• 更多API见MicroPython LVGL API.py文件的"class textarea"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)


# 创建普通文本框（多行输入）
textarea1 = lv.textarea(scr)
textarea1.set_size(lv.pct(90), 100)
textarea1.set_pos(lv.pct(5), lv.pct(5))
textarea1.set_placeholder_text("Multi-line input...")
textarea1.set_max_length(100)  # 最大100个字符

# 创建密码框
password_area = lv.textarea(scr)
password_area.set_size(lv.pct(90), 50)
password_area.set_pos(lv.pct(5), lv.pct(35))
password_area.set_placeholder_text("Please enter the password.")
password_area.set_password_mode(True)
password_area.set_password_bullet("•")  # 密码显示为圆点
password_area.set_password_show_time(1000)  # 输入的字符显示1秒后变为圆点
password_area.set_max_length(20)  # 密码最大20位

# 创建带字符限制的文本框（仅允许数字）
number_area = lv.textarea(scr)
number_area.set_size(lv.pct(90), 50)
number_area.set_pos(lv.pct(5), lv.pct(55))
number_area.set_placeholder_text("Please enter a number")
number_area.set_one_line(True)  # 单行模式
number_area.set_accepted_chars("0123456789")  # 仅允许数字输入
number_area.set_max_length(10)  # 最大10位数字

4.14 键盘（Keyboard）

• 更多API见MicroPython LVGL API.py文件的"class keyboard"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建键盘
keyboard = lv.keyboard(scr)
#设置尺寸
keyboard.set_size(400, 200)
#底部居中对齐
keyboard.align(lv.ALIGN.BOTTOM_MID, 0, 0)  
# 创建输入目标（以 textarea 为例）
textarea = lv.textarea(scr)
textarea.set_size(380, 100)
textarea.align(lv.ALIGN.TOP_MID, 0, 20)
textarea.set_placeholder_text("textarea...")  # 提示文本
# 将键盘绑定到输入目标,绑定后，键盘输入会直接传入 textarea
keyboard.set_textarea(textarea) 

显示效果

4.15 下拉列表（dropdown）

• 更多API见MicroPython LVGL API.py文件的"class dropdown"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

# 创建下拉列表控件
dropdown = lv.dropdown(scr)
#居中显示
dropdown.center()
#以换行符分隔的字符串表示多个选项
dropdown.set_options("case 1\ncase 2\ncase 3\ncase 4")

#交互回调函数
def dropdown_event_cd(e):
    #获取当前选中选项的索引
    selected_option = dropdown.get_selected()
    #获取当前选中选项的索引
    print(f"选中ID: {selected_option}")
#注册交互回调函数。更多状态见api.py文件的"class EVENT"部分
dropdown.add_event_cb(dropdown_event_cd, lv.EVENT.VALUE_CHANGED, None)

显示效果

4.16 滚轮（roller）

• 更多API见MicroPython LVGL API.py文件的"class roller"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建下拉列表控件
roller_normal = lv.roller(scr)
roller_normal.set_pos(20, 20)
roller_normal.set_size(200, 150)
#设置选项和普通模式
days = "Monday‌\nTuesday\nWednesday‌\n‌Thursday\n‌Friday\n‌Saturday‌\nSunday"
roller_normal.set_options(days, roller_normal.MODE.NORMAL)
#设置可见行数
roller_normal.set_visible_row_count(5)

#创建循环模式滚轮
roller_infinite = lv.roller(scr)
roller_infinite.set_pos(240, 20)
roller_infinite.set_size(200, 150)
#设置选项和循环模式
months = "January\n‌February\nMarch‌\nApril‌\nMay\nJune\nJuly‌\nAugust‌\n‌September\nOctober\nNovember‌\nDecember"
roller_infinite.set_options(months, roller_normal.MODE.INFINITE)
#设置可见行数
roller_infinite.set_visible_row_count(5)

显示效果

4.17 列表（list）

• 更多API见MicroPython LVGL API.py文件的"class list"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建列表对象
list_obj = lv.list(scr)
list_obj.set_size(300, 200)
list_obj.center()
#添加文本项
list_obj.add_text("button A")
#添加按钮项
btnA1 = list_obj.add_button(None, "A1")
btnA2 = list_obj.add_button(None, "A2")
btnA3 = list_obj.add_button(None, "A3")
#添加文本项
list_obj.add_text("button B")
#添加按钮项
btnB1 = list_obj.add_button(None, "B1")
btnB2 = list_obj.add_button(None, "B2")
btnB3 = list_obj.add_button(None, "B3")

显示效果

4.18 选项卡（tabview）

• 更多API见MicroPython LVGL API.py文件的"class tabview"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

#创建选项卡视图
tabview = lv.tabview(scr)
#添加选项卡
tab1 = tabview.add_tab("A")
tab2 = tabview.add_tab("B")
tab3 = tabview.add_tab("C")
#添加选项卡内容
label1 = lv.label(tab1)
label1.set_text("tabview A")
label1.center()
label2 = lv.label(tab2)
label2.set_text("tabview B")
label2.center()
label3 = lv.label(tab3)
label3.set_text("tabview C")
label3.center()

显示效果

4.19 菜单（menu）

• 更多API见MicroPython LVGL API.py文件的"class menu"和"class obj"部分

注：该控件目前存在部分问题

4.20 表格（table）

• 更多API见MicroPython LVGL API.py文件的"class table"和"class obj"部分

import screen
import lvgl as lv

#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

# 1. 创建表格实例
table = lv.table(scr)
table.set_size(300, 200)  # 设置表格大小
table.align(lv.ALIGN.CENTER, 0, 0)  # 居中显示
#设置表格行列数
table.set_row_count(4)
table.set_column_count(3)
#设置列宽
table.set_column_width(0, 80)
table.set_column_width(1, 100)

#填充表格数据
table.set_cell_value(0, 0, "ID")
table.set_cell_value(0, 1, "NAME")
table.set_cell_value(0, 2, "STATE")

table.set_cell_value(1, 0, "001")
table.set_cell_value(1, 1, "Device A")
table.set_cell_value(1, 2, "ON")

table.set_cell_value(2, 0, "002")
table.set_cell_value(2, 1, "Device B")
table.set_cell_value(2, 2, "OFF")

table.set_cell_value(3, 0, "003")
table.set_cell_value(3, 1, "Device C")
table.set_cell_value(3, 2, "ON")

显示效果

4.21 图片（image）和动图（gif）

• 更多API见MicroPython LVGL API.py文件的"class image"、"class gif"和"class obj"部分

import screen
import lvgl as lv
import fs_driver

fs_drv = lv.fs_drv_t()
fs_driver.fs_register(fs_drv, 'S')
#获取当前激活的屏幕对象
scr = lv.screen_active()
#设置屏幕的背景颜色为黑色
scr.set_style_bg_color(lv.color_hex(0x000000), 0)

'''显示LVGL内置符号'''
#创建图像
img_symbol = lv.image(scr)
#显示LVGL内置符号（"home" 图标）,更多图标见api.py文件的"class SYMBOL"部分
img_symbol.set_src(lv.SYMBOL.HOME)
#居中显示
img_symbol.align(lv.ALIGN.CENTER, 0, 0)

'''显示存储中图片'''
img_symbol2 = lv.image(scr)
#显示png
img_symbol2.set_src('S:001.png')
#显示jpg
#img_symbol2.set_src('S:001.jpg')
img_symbol2.align(lv.ALIGN.RIGHT_MID, 0, 0)  # 居右显示

'''显示gif'''
img_symbol3 = lv.gif(scr)
img_symbol3.set_src('S:001.gif')
img_symbol3.align(lv.ALIGN.LEFT_MID, 0, 0)  # 居左显示

5. 资料下载

• MicroPython LVGL API.py文件
• 图片素材