ESP32 LVGL 教程：构建触摸屏 UI

为什么要用可视化编辑器来构建 ESP32 UI？

用传统方式为 ESP32 构建触摸屏界面非常耗时。你需要手写 LVGL C 代码来放置每个控件，设置颜色和尺寸，烧录到开发板，盯着屏幕看，调整几个像素，再次烧录。每次小修改都要和硬件来回折腾。

可视化编辑器彻底改变了这一切。你把 LVGL 控件拖到画布上，点击设置样式，立即看到效果——满意后再导出 C 代码。你把时间花在设计上，而不是重新编译。

你需要什么

跟着本教程学习并不需要太多准备：

• 一块带显示屏的 ESP32 开发板，任何能运行 LVGL 的 ESP32 变体都可以（关于具体支持的开发板，请参阅下文）。
• 你偏好的固件工具链：ESP-IDF、Arduino 或 PlatformIO，需已添加 LVGL 8.x 并且显示屏和触摸驱动已正常工作。
• 一个免费的 PicoPixel 账号，本教程所有操作都在浏览器中完成。

第一步 - 设置显示屏尺寸

打开编辑器，新建一个项目。首先需要正确设置分辨率，让你的设计与物理屏幕逐像素对应。

选择与你的显示屏匹配的预设：

• 320×240，最常见的小型 SPI TFT 面板（ST7789、ILI9341）。
• 240×240，GC9A01 等圆形显示屏。
• 480×320、480×480 或 800×480，较大的及方形面板。

一开始就设置正确，意味着你设计的内容与设备上显示的内容完全一致。

第二步 - 拖放设计

现在是最有趣的部分。从调色板中将 LVGL 控件拖到画布上——按钮、标签、滑块、弧形、开关、图表、下拉菜单等（共 30 多种控件类型）。摆放好位置后，使用侧面板可视化地设置颜色、字体、间距和圆角。这个阶段不需要写任何 C 代码。

构建过程中有几点值得注意：

• 多屏支持。 根据需要添加任意数量的屏幕，并设置屏幕间的导航——非常适合菜单、设置页面和仪表盘。
• 从一开始就支持触摸。 控件响应点击，容器支持滚动，因此你可以设计真实的触摸屏交互，而不仅仅是静态布局。
• 字体和图片是一等公民。 嵌入式设备上的文字和图形需要转换为 LVGL 可以存储的格式。PicoPixel 会帮你处理这些——如何精简字体大小请参阅我们的字体指南，如果你想要带动画的多状态控件请查看精灵指南。

第三步 - 实时预览

在动用硬件之前，先点击预览。PicoPixel 将真正的 LVGL 引擎编译为 WebAssembly 并直接在浏览器中运行，因此你看到的是真实的 LVGL 渲染，而不是模拟图或粗略近似。

点击按钮、拖动滑块、滚动并检查屏幕导航。在这里修复布局问题只需几秒钟；在设备上修复则需要一次烧录循环。你甚至可以把预览链接分享给团队成员或客户以获取反馈。

第四步 - 导出生产就绪的 C 代码

当设计看起来满意了，就可以导出。你将得到一个 picopixel_lvgl_ui.zip，其中包含干净、标准的 LVGL 8.x C 代码：

• ui.c / ui.h，入口点，包含 ui_init() 和 ui_tick()。
• screens.c / screens.h，你的屏幕及其布局。
• styles、fonts、images、actions 和 vars，设计中用到的所有内容，均自动生成。
• README.md，对导出内容的通俗描述（在第五步中介绍）。

没有专有依赖，也不需要添加 PicoPixel 运行时库——这是原生 LVGL，无论你使用 ESP-IDF、Arduino 还是 PlatformIO，效果完全一样。

第五步 - 将 UI 添加到 ESP32 项目中

将导出内容解压到你的项目中（大多数人将其放在 ui/ 文件夹下）。然后你只需在固件中做两件事：在 LVGL 和显示/触摸驱动初始化完成后调用一次 ui_init()，并在主循环中调用 ui_tick()。

在 Arduino 风格的草图中，大致如下：

#include <lvgl.h>
#include "ui/ui.h"          // exported by PicoPixel

void setup() {
  lv_init();
  // ... initialize your display + touch drivers here ...
  ui_init();                // builds the UI you designed
}

void loop() {
  lv_timer_handler();       // let LVGL render and handle input
  ui_tick();                // keep PicoPixel's screens updated
  delay(5);
}

要在运行时切换屏幕（例如按下按钮时），使用目标屏幕调用 loadScreen()。集成就这么简单——编译、烧录，ESP32 上的 UI 与你在浏览器中看到的完全一致。

哪些 ESP32 开发板可以使用？

由于 PicoPixel 导出标准的 LVGL C 代码，它几乎可以在任何能运行 LVGL 8.x 的 ESP32 上使用。各变体简要指南：

• ESP32-S3，大多数显示项目的最佳选择：双核带 PSRAM，有充足的余量运行复杂 UI。
• ESP32（原版）/ ESP32-S2，适合较简单的界面；注意内存预算。
• ESP32-C3 / C6，轻量级单核 RISC-V 芯片，适合较小的 UI。
• ESP32-P4，Espressif 最强大的芯片，带有专用 GPU，可实现流畅的高分辨率界面。PicoPixel 的导出已在 Waveshare 和 Guition 的 ESP32-P4 开发板上测试通过。

常见的成品开发板——LILYGO T-Display-S3、M5Stack Core2/CoreS3、Waveshare 和 Sunton 显示板、Espressif ESP32-S3-BOX 以及经济实惠的"Cheap Yellow Display"——均可使用，常见驱动如 ST7789、ILI9341、GC9A01（圆形）和 ILI9488 也同样支持。

保持 UI 的内存占用精简

嵌入式显示屏的内存远少于手机或电脑，因此稍加注意就能让 UI 保持快速且节省 Flash：

• 合理控制字体大小。 每种字体以固定的像素大小存储，而大型字符集（尤其是中文、日文和韩文）会迅速占满空间。字体指南介绍了如何只包含你实际使用的字符。
• 颜色深度与显示屏匹配。 16 位面板不需要 32 位图片——选择合适的颜色深度可以缩小资源文件。
• 复用而非重复创建。 将控件创建一次，在不同屏幕和项目中复用。

常见问题

PicoPixel 支持 ESP32 吗？

支持。它生成标准的 LVGL C 代码，可在所有能运行 LVGL 8.x 的 ESP32 变体上与 ESP-IDF、Arduino 和 PlatformIO 配合使用——导出内容已在 ESP32-P4 硬件上测试通过。

支持哪个 LVGL 版本？

LVGL 8.x。导出的代码使用 LVGL 8.x API，不要与 LVGL 9.x 的调用混用。（v9 支持已在计划中。）

需要写 C 代码吗？

只需要第五步中少量的胶水代码——调用 ui_init() 和 ui_tick()。UI 本身通过可视化方式设计并自动生成。

免费吗？

是的。PicoPixel 个人和爱好使用免费，无需信用卡。商业使用从 $17/月（$204/年）起。

下一步

你现在已经掌握了从创意到烧录完成的完整流程：设置分辨率、拖放设计、实时预览、导出并集成。接下来：

• 进入编辑器，在 app.picopixel.io 开始一个项目。
• 浏览 ESP32 GUI 构建器页面，了解更多关于开发板和框架支持的信息。
• 使用动画精灵和自定义字体让你的控件更加丰富。
• 正在权衡选择？查看 PicoPixel 与其他 LVGL 编辑器的对比。