LVGL新手教程：从零实现一个简单按钮界面

从零开始用 LVGL 搭出一个能点的按钮：新手实战指南

你有没有过这样的经历？手头一块 STM32 或 ESP32 开发板，接了个小屏幕，想做个带“点击”功能的界面——比如按一下启动某个功能。但一查资料发现，GUI 太重跑不动，裸机画图又太麻烦？

别急，LVGL就是为这种场景而生的。

它轻得惊人（最低只要 16KB RAM），功能却很完整：按钮、滑动条、动画、主题全都有，还支持触摸输入。最关键的是——它是开源免费的，社区活跃，文档齐全。

今天我们就来手把手实现一个可点击、会变文字的按钮界面，不讲虚的，只写你能直接用的代码，帮你跨过那道“看得懂但做不出来”的坎。

先搞清楚：LVGL 到底是怎么工作的？

在动手前，先建立一个清晰的认知模型。你可以把 LVGL 想象成一个“嵌入式世界的网页引擎”。

它不直接控制屏幕或触摸芯片；
而是通过你提供的“回调函数”，间接和硬件打交道；
你在上面创建各种控件（像 HTML 标签一样）；
用户操作时，它自动找到目标控件并通知你。

整个过程非阻塞，可以轻松集成进主循环或者 RTOS 中。

核心三步走：

初始化 LVGL 内核
注册显示和输入驱动
创建 UI + 绑定事件
循环调用任务处理函数

下面我们一步步拆解。

第一步：初始化 LVGL ——`lv_init()`必须最先调

所有 LVGL 程序都从这句开始：

#include "lvgl.h" void app_main(void) { lv_init(); // ← 所有 LVGL API 的起点！ }

就这么简单？没错。

但这背后做了不少事：
- 初始化内存池（用于分配对象）
- 准备样式系统与动画引擎
- 设置默认日志输出

⚠️ 注意：lv_init()只负责软件初始化，不涉及任何硬件操作。真正的硬件对接要靠后续的驱动注册。

这个函数依赖一个配置文件lv_conf.h，你需要确保工程中已包含它，并根据你的 MCU 资源调整关键参数，例如：

#define LV_MEM_SIZE (32U * 1024U) // 分配 32KB 内存池 #define LV_COLOR_DEPTH 16 // 使用 RGB565 颜色格式 #define LV_HOR_RES_MAX 320 #define LV_VER_RES_MAX 240

没有这个文件？去 LVGL GitHub 下载源码，复制一份lv_conf_template.h改名为lv_conf.h即可。

第二步：连接屏幕 —— 注册显示驱动

LVGL 不知道你怎么驱动 ILI9341 或 ST7789，但它提供了一个标准接口：只要你告诉它“如何把像素数据刷到屏幕上”，它就能自己算好该画哪一块区域。

这就是显示驱动（Display Driver）的作用。

关键结构体：`lv_disp_drv_t`

你需要做三件事：
1. 定义一块绘制缓冲区（Draw Buffer）
2. 实现刷新回调flush_cb
3. 填充分辨率等信息并注册

来看代码：

// 缓冲区大小建议至少一行宽度 × 10 行像素 static lv_color_t disp_buf_area[320 * 10]; static lv_disp_draw_buf_t draw_buf; // 刷新回调：将 LVGL 计算好的脏区域写入 LCD void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p) { uint32_t w = area->x2 - area->x1 + 1; uint32_t h = area->y2 - area->y1 + 1; // 调用底层LCD驱动函数写入指定区域 lcd_write_pixels(area->x1, area->y1, w, h, (uint16_t *)color_p); // ✅ 必须调用！否则 LVGL 会认为屏幕还在忙 lv_disp_flush_ready(disp_drv); } // 注册显示驱动 void register_display_driver(void) { static lv_disp_drv_t disp_drv; lv_disp_drv_init(&disp_drv); disp_drv.hor_res = 320; disp_drv.ver_res = 240; disp_drv.flush_cb = my_flush_cb; disp_drv.draw_buf = &draw_buf; // 初始化绘制缓冲区 lv_disp_draw_buf_init(&draw_buf, disp_buf_area, NULL, 320 * 10); // 向 LVGL 注册驱动 lv_disp_drv_register(&disp_drv); }

📌重点提醒：
-flush_cb是核心，必须尽快完成传输；
- 如果使用 DMA，记得在 DMA 中断里调用lv_disp_flush_ready()；
-忘记调lv_disp_flush_ready()是导致界面卡死最常见的原因！

第三步：接入触摸屏 —— 注册输入设备

现在屏幕能画了，但用户没法交互。我们需要让 LVGL “知道”手指点在哪。

LVGL 把触摸屏归类为“指针型设备”（Pointer Device），只需要你实现一个读取回调即可。

static lv_indev_drv_t indev_drv; void my_touch_read_cb(lv_indev_drv_t * drv, lv_indev_data_t * data) { if (touch_pressed()) { // 检测是否按下 >// 创建按钮，父对象是当前屏幕 lv_obj_t * btn = lv_btn_create(lv_scr_act()); lv_obj_set_size(btn, 120, 50); lv_obj_align(btn, LV_ALIGN_CENTER, 0, 0); // 居中对齐 // 创建标签作为按钮的子对象 lv_obj_t * label = lv_label_create(btn); lv_label_set_text(label, "Click Me"); lv_obj_center(label); // 自动居中标签

💡 解释一下：
-lv_scr_act()返回当前活动屏幕，相当于 HTML 中的<body>；
- 按钮 (lv_btn) 本质是一个容器，标签 (lv_label) 作为其子元素会随父级移动；
-lv_obj_align(..., LV_ALIGN_CENTER, ...)是 LVGL 提供的强大布局工具，免去手动计算坐标。

此时运行程序，你应该已经看到屏幕上出现了一个灰色矩形按钮。

第五步：让按钮“活起来”——绑定点击事件

光有按钮不够，我们希望点击后能计数并更新文字。

这就需要用到事件机制。

如何监听点击？

给按钮添加一个事件回调函数：

void btn_event_cb(lv_event_t * e) { lv_event_code_t code = lv_event_get_code(e); // 获取事件类型 lv_obj_t * btn = lv_event_get_target(e); // 获取触发事件的对象 static uint8_t click_count = 0; if (code == LV_EVENT_CLICKED) { click_count++; printf("按钮被点击了 %d 次\n", click_count); // 修改按钮上的文字 lv_obj_t * label = lv_obj_get_child(btn, 0); // 获取第一个子对象（即 label） char buf[32]; sprintf(buf, "Clicked %d", click_count); lv_label_set_text(label, buf); } }

然后把这个回调“挂上去”：

lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_ALL, NULL);

📌 小贴士：
-LV_EVENT_ALL会监听所有事件，适合调试；
- 正式项目建议改为LV_EVENT_CLICKED，减少不必要的回调开销；
- 事件是在lv_task_handler()中被检测和分发的，所以必须周期性调用它。

最后一步：启动 GUI 引擎 ——`lv_task_handler()`

LVGL 不是实时响应中断的系统，而是基于定时轮询的方式工作。

你需要在一个循环中定期调用：

while(1) { lv_task_handler(); // ← GUI 的“心跳” lv_tick_inc(5); // 手动递增系统滴答（每5ms一次） vTaskDelay(pdMS_TO_TICKS(5)); }

📌lv_tick_inc()替代了硬件定时器中断的作用，告诉 LVGL 时间过去了多少毫秒，用于动画、长按判定等功能。

如果你用了 FreeRTOS，可以把lv_task_handler()放在一个低优先级任务中执行。

整体流程串一遍

回顾一下完整流程：

int main(void) { system_init(); // 初始化 MCU、时钟等 lv_init(); // 1. 初始化 LVGL register_display_driver(); // 2. 注册显示驱动 register_touch_driver(); // 3. 注册触摸驱动 create_ui(); // 4. 创建按钮和标签 // 5. 绑定事件（在 create_ui 内完成） while(1) { lv_task_handler(); // 6. 处理 GUI 任务 lv_tick_inc(5); delay_ms(5); } }

只要这几步都走通，你的按钮就能正常响应点击，文字也会跟着变化！

新手常踩的坑 & 实战建议

❌ 常见问题一：界面卡死不动

原因：没调lv_disp_flush_ready()。
解决：确保在flush_cb结束前调用该函数，尤其是使用 DMA 时要在传输完成中断中调。

❌ 常见问题二：触摸不准或无反应

检查点：
read_cb是否正确返回坐标？
触摸 IC 驱动是否正常工作？
是否需要校准坐标系？（某些模块 X/Y 轴可能翻转）

✅ 性能优化建议

绘制缓冲区大小：建议至少一行宽 × 10 行高。太小会导致频繁重绘，太大吃内存。
避免在事件回调中干重活：如开启电机、发网络请求。应设标志位，由主循环处理。
调用频率：lv_task_handler()每 5~10ms 调一次最佳，太快浪费 CPU，太慢动画卡顿。

✅ 进阶方向

学会了基础按钮，下一步你可以尝试：
- 添加多个页面切换（用lv_obj_clean(lv_scr_act())清屏）
- 使用lv_label_set_text_fmt()显示变量值
- 引入主题美化界面（lv_theme_default_init()）
- 创建自定义控件组合（如带图标+文字的按钮）