📚 课程目录第3章事件系统核心概念

3. 事件系统核心概念

回调函数，说白了就是「你写逻辑，LVGL 帮你调用」。你不需要自己去轮询按键状态，也不需要写一个巨大的 switch-case 去判断哪个控件被点了。你只需要把处理逻辑打包成一个函数，然后告诉 LVGL：「嘿，这个按钮被点击时，你帮我跑这个函数。」

我刚开始接触 LVGL 时，总觉得回调函数有点绕。明明可以直接在循环里判断状态，为什么要多一层间接调用？后来项目越做越大，控件越来越多，我才明白——回调函数是事件驱动架构的基石。没有它，你的代码会变成一团乱麻。

3.1 回调函数的定义

在 LVGL 里，回调函数其实就是一个普通的 C 函数。但它必须遵循固定的签名格式。你想想看，LVGL 怎么知道你的函数接受几个参数？返回值是什么？所以它规定了一个统一的接口。

// 回调函数的典型定义
static void my_button_event_handler(lv_event_t * e)
{
    // 你的处理逻辑写在这里
    lv_obj_t * btn = lv_event_get_target(e);
    LV_LOG_USER("按钮被点击了！");
}

这个 lv_event_t * e 就是事件对象。它包含了所有你需要的信息：谁触发了事件、事件类型是什么、有没有额外的参数。我个人习惯把事件处理函数命名为 xxx_event_handler，这样看代码时一目了然。

核心要点：回调函数的返回值必须是 void，参数必须是 lv_event_t *。这是 LVGL 的硬性规定，不要试图改变它。

3.2 参数传递——从事件对象中提取信息

很多新手会问：「我的回调函数怎么知道是哪个按钮被按了？」答案就在 lv_event_t 这个结构体里。LVGL 提供了一系列 API 让你从中提取信息。

API 函数	作用	返回值
`lv_event_get_target(e)`	获取触发事件的原始控件	`lv_obj_t *`
`lv_event_get_current_target(e)`	获取当前处理事件的控件（事件冒泡时有用）	`lv_obj_t *`
`lv_event_get_code(e)`	获取事件类型（如点击、长按、释放等）	`lv_event_code_t`
`lv_event_get_param(e)`	获取用户绑定的自定义参数	`void *`

举个例子。假设你有三个按钮，点击后要打印不同的信息。你可以这样写：

static void btn_event_handler(lv_event_t * e)
{
    lv_obj_t * btn = lv_event_get_target(e);
    lv_event_code_t code = lv_event_get_code(e);

    if(code == LV_EVENT_CLICKED) {
        if(btn == btn_red) {
            LV_LOG_USER("红色按钮被点击");
        } else if(btn == btn_green) {
            LV_LOG_USER("绿色按钮被点击");
        } else if(btn == btn_blue) {
            LV_LOG_USER("蓝色按钮被点击");
        }
    }
}

嗯，这里要注意。如果你有几十个按钮，用 if-else 链会非常痛苦。这时候就需要用户数据绑定了。

3.3 用户数据绑定——让回调函数更聪明

我在项目中遇到过一个问题：一个列表里有 50 个条目，每个条目点击后要跳转到不同的页面。如果用 if-else 判断控件地址，代码会膨胀到没法看。解决方案就是用户数据绑定。

LVGL 允许你在注册回调时，附带一个 void * 类型的用户数据。这个数据会被保存在事件对象里，回调函数可以通过 lv_event_get_user_data(e) 取出来。

// 定义回调函数
static void list_item_click_handler(lv_event_t * e)
{
    int * page_id = (int *)lv_event_get_user_data(e);
    LV_LOG_USER("跳转到页面 %d", *page_id);
    // 执行页面跳转逻辑...
}

// 注册回调时绑定用户数据
for(int i = 0; i < 50; i++) {
    lv_obj_t * btn = lv_btn_create(list);
    lv_obj_add_event_cb(btn, list_item_click_handler, LV_EVENT_CLICKED, &page_ids[i]);
}

小技巧：用户数据可以是任何类型的指针。你可以传整数、字符串、结构体，甚至是一个函数指针。我个人习惯把页面 ID、设备索引这类「小数据」用 int 类型传，而不是用全局变量。

但是要注意一个坑：用户数据的生命周期。如果你传的是一个局部变量的地址，当局部变量被销毁后，回调函数里访问的就是野指针了。我曾经因为这个 bug 查了一整天……

避坑指南：用户数据必须保证在事件处理期间有效。建议使用静态变量、全局变量或者动态分配的内存（记得释放）。不要传局部变量的地址！

3.4 回调函数的注册与注销

注册回调函数，用的是 lv_obj_add_event_cb。这个函数有四个参数：

lv_obj_add_event_cb(obj, event_cb, filter, user_data);

obj：要监听事件的控件
event_cb：回调函数指针
filter：事件类型过滤，比如 LV_EVENT_CLICKED、LV_EVENT_VALUE_CHANGED 等
user_data：用户自定义数据，不需要就传 NULL

注销回调函数，用的是 lv_obj_remove_event_cb 或 lv_obj_remove_event_cb_with_user_data。

// 注销指定回调函数
lv_obj_remove_event_cb(btn, my_event_handler);

// 注销所有回调函数
lv_obj_remove_event_cb(btn, NULL);

// 根据用户数据注销
lv_obj_remove_event_cb_with_user_data(btn, my_event_handler, &my_data);

你想想看，什么时候需要注销回调？最常见的就是控件被删除前。虽然 LVGL 在删除控件时会自动清理事件回调，但如果你在回调函数里引用了外部资源，最好手动注销一下，避免悬空指针。

最佳实践：在控件的 LV_EVENT_DELETE 事件中，释放用户数据绑定的动态内存。这样能保证内存不会泄漏。

static void cleanup_handler(lv_event_t * e)
{
    int * data = (int *)lv_event_get_user_data(e);
    if(data) {
        free(data);
    }
}

// 注册清理回调
lv_obj_add_event_cb(obj, cleanup_handler, LV_EVENT_DELETE, my_dynamic_data);

3.5 知识体系总览

说了这么多，我们来画一张图，把回调函数的整个流程串起来。这样你脑子里会有一个清晰的脉络。

这张图把回调函数的四个核心环节串在了一起。从定义开始，到参数传递、用户数据绑定，再到注册与注销，每一步都有对应的 API 和注意事项。你写代码时，脑子里可以过一遍这个流程，基本不会出错。

3.6 实战中的一些建议

最后，分享几个我在实际项目中积累的经验：

回调函数尽量短小精悍。不要在回调里做耗时操作，比如文件读写、网络请求。LVGL 的事件处理是在主循环里跑的，阻塞太久会导致界面卡顿。
善用事件过滤。如果你只关心点击事件，就只注册 LV_EVENT_CLICKED，不要注册 LV_EVENT_ALL 然后在回调里做过滤。这样性能更好，代码也更清晰。
用户数据优先用结构体。当需要传递多个参数时，把它们打包成一个结构体，传结构体指针。比传多个全局变量优雅得多。
注销回调要成对出现。如果你在某个时机注册了回调，一定要在对应的时机注销。尤其是在动态创建和销毁控件的场景下，漏掉注销会导致内存泄漏或者野指针。

嗯，回调函数这块内容其实不难，但细节很多。你只要把定义、参数、数据绑定、注册注销这四个点吃透了，LVGL 的事件处理你就掌握了八成。剩下的就是在项目里多练，踩几个坑自然就记住了。