LVGL（lv_list列表控件）

---

lv_list 是 LVGL（Light and Versatile Graphics Library）中的一个 UI 组件，用于创建可滚动的项目列表，类似于常见的设置菜单或选项列表，支持图标、文字、点击事件等，非常适合在嵌入式 GUI 项目中使用。

---

🌟 一、lv_list 的基本概念

lv_list 是一个容器（container），可以容纳多个子项（list button）。每个子项可以是带图标的按钮、仅文字的按钮，甚至可以进一步自定义为复杂内容。

每一个子项本质上是一个 lv_obj_t*，并且通常是通过 lv_list_add_btn() 添加。

---

🛠️ 二、lv_list 的常用 API

1. 创建列表对象

lv_obj_t * list = lv_list_create(lv_scr_act());  // 创建在当前活动屏幕上

2. 添加按钮（项目）

lv_obj_t * btn1 = lv_list_add_btn(list, LV_SYMBOL_FILE, "File");
lv_obj_t * btn2 = lv_list_add_btn(list, LV_SYMBOL_SAVE, "Save");

• LV_SYMBOL_FILE：图标（可省略，用 NULL）
• "File"：文本

每个按钮都是可点击的 lv_obj，你可以注册事件。

3. 设置点击事件回调

lv_obj_add_event_cb(btn1, my_event_cb, LV_EVENT_CLICKED, NULL);

4. 获取按钮文字

const char * txt = lv_list_get_btn_text(btn1);

5. 设置样式（可选）

可以通过 lv_obj_add_style() 设置列表本身、按钮等的背景色、边框、字体等样式。

---

🔁 三、lv_list 的滚动和布局

• 列表默认垂直方向滚动，超出部分自动显示滚动条。
• LVGL 8.x 之后使用 flex 布局自动管理子项排列。
• 每个按钮的大小会自动适配内容，也可以手动设置大小。

---

✅ 四、完整示例代码

void my_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);if (code == LV_EVENT_CLICKED) {const char * txt = lv_list_get_btn_text(btn);printf("Clicked: %s\n", txt);}
}void create_list_example() {lv_obj_t * list = lv_list_create(lv_scr_act());lv_obj_set_size(list, 200, 200);lv_obj_center(list);lv_obj_t * btn1 = lv_list_add_btn(list, LV_SYMBOL_WIFI, "Wi-Fi");lv_obj_t * btn2 = lv_list_add_btn(list, LV_SYMBOL_SETTINGS, "Settings");lv_obj_add_event_cb(btn1, my_event_cb, LV_EVENT_CLICKED, NULL);lv_obj_add_event_cb(btn2, my_event_cb, LV_EVENT_CLICKED, NULL);
}

---

🧠 五、进阶使用技巧

功能	方法
设置图标间距	自定义样式或修改 pad
支持多级菜单	点击按钮后创建新 lv_list 或切换页面
添加分割线	可使用空白按钮或自定义绘图
添加长按事件支持	LV_EVENT_LONG_PRESSED

---

📌 六、LVGL v8 与 v7 的区别

• v8 使用 lv_obj_add_event_cb，而 v7 使用 lv_obj_set_event_cb
• v8 使用 flex 布局自动管理，v7 布局方式更原始
• 建议使用 LVGL v8 以上版本，功能更完善、API 更统一

---