开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF
适用开发板：Korvo S3 · 工程
03.development.lvgl_v9· targetesp32s3
前置：SPI LCD Touch
学习时长：约 25 分钟 · 难度：★★★☆☆
学习目标
完成本节后，你将能够：
- 理解 LVGL v8 → v9 的主要 API 变化
- 掌握
esp_lvgl_adapter组件的使用方式 - 了解 LVGL v9 新特性（观察者模式、新渲染器、Event Bubble 等）
- 学会从 v8 工程迁移到 v9
1. 这个例子在干嘛
展示 LVGL v9 在 Korvo 上的完整移植——使用 esp_lvgl_adapter 组件对接 SPI LCD + 触摸，运行 LVGL v9 演示 UI（控件展示、动画、主题）。
为什么学 LVGL v9：v9 是 LVGL 的最新大版本，API 有较大变化。新项目建议直接用 v9。
SPI LCD (ST7789) ← esp_lcd_panel_io → LVGL 9 渲染器
↓
CST816S Touch ← esp_lcd_touch → LVGL 9 输入设备
↓
LVGL 9 Widget
(按钮/滑条/图表...)
2. LVGL v8 vs v9 主要变化
| 变化项 | v8 | v9 |
|---|---|---|
| 驱动注册 | lv_disp_drv_register() | lv_display_create() |
| 输入设备 | lv_indev_drv_register() | lv_indev_create() |
| 颜色格式 | LV_COLOR_16_SWAP | LV_COLOR_FORMAT_RGB565 |
| 事件系统 | lv_obj_add_event_cb() | 新增 Observer 模式 |
| 渲染器 | 内置 | 可选软件/硬件渲染器 |
| 样式 | lv_style_set_*() | 保持但部分重命名 |
| 字体 | &lv_font_montserrat_14 | 相同但增加 FreeType 支持 |
迁移最常见的改动
// v8
lv_disp_draw_buf_init(&draw_buf, buf1, buf2, size);
lv_disp_drv_init(&drv);
drv.draw_buf = &draw_buf;
lv_disp_drv_register(&drv);
// v9
lv_display_t *disp = lv_display_create(width, height);
lv_display_set_flush_cb(disp, flush_cb);
lv_display_set_buffers(disp, buf1, buf2, size, LV_DISPLAY_RENDER_MODE_PARTIAL);
3. 编译烧录
cd Korvo_Firmware\03.development.lvgl_v9
idf.py set-target esp32s3
idf.py build flash monitor
4. 运行现象
| 阶段 | 屏幕 | 串口 |
|---|---|---|
| 初始化 | — | LVGL v9 init |
| UI 加载 | LVGL Widget Demo | Widgets ready |
| 触摸交互 | 按钮/滑条/开关响应 | 事件日志 |
5. 常见问题与排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 编译报 v8 API | 混用了 v8 代码 | 按上方迁移指南修改 |
| 画面颠倒 | 旋转配置 | 检查 esp_lvgl_adapter 旋转设置 |
| 触摸偏移 | 坐标映射 | 校准触摸驱动 |
| 颜色反 | 字节序 | 检查 LV_COLOR_16_SWAP 或 RGB/BGR |
6. 动手改造建议
- v8→v9 迁移练习：拿一个 v8 工程，改为 v9 API
- Observer 模式：用
lv_subject_add_observer()实现数据绑定 - FreeType 字体：加载 TTF 文件显示中文
- 自定义主题：修改全局主题色板
7. 下一步
| 方向 | 推荐例程 | 说明 |
|---|---|---|
| LVGL 适配器 | LVGL ESP Adapter | BSP 方式 |
| SPI LCD | SPI LCD Touch | 底层驱动 |
| P4C5 版 | P4C5 LVGL v9 | MIPI 大屏版 |
| 通用 LVGL | LVGL v9 教程 | 理论详解 |
酷世DIY · Kevincoooool