4、自定义控件开发：从零实现一个可复用的自定义控件

说实话，很多做嵌入式GUI的朋友，一开始都习惯用现成的控件库。按钮、标签、进度条，拖一拖就完事了。但做到仪表盘、波形图这种复杂界面时，你会发现——嗯，现成的根本不够用。

我最早做工业HMI项目时，客户要求一个圆形的车速表盘，带指针和刻度。翻遍了当时用的GUI库，没有一个能直接满足。怎么办？只能自己写。从那以后，我养成了一个习惯：每个项目都预留20%的时间做自定义控件开发。这不是炫技，而是刚需。

核心观点：自定义控件不是“造轮子”，而是“造适合你车轮的轮子”。掌握绘制回调、事件处理、样式封装这三板斧，你就能在任何嵌入式GUI框架中游刃有余。

4.1 自定义控件的三层架构

我习惯把自定义控件拆成三层。你想想看，这样设计的好处是——每一层都能独立测试，出了问题也容易定位。

层次	职责	典型代码
绘制层	负责控件的视觉呈现，包括背景、边框、图形元素	`on_draw(canvas)`
事件层	处理触摸、按键、定时器等输入事件	`on_touch(event)`
样式层	管理颜色、字体、尺寸等外观属性	`StyleSheet` 结构体

这三层之间通过一个控件上下文来通信。说白了，就是一个结构体指针，里面装着当前控件的状态、样式和回调函数。我在项目中遇到过有人把这三层写在一个大文件里，结果后期维护时改一个颜色都要翻半天代码。所以，分层是底线。

4.2 绘制回调：让控件“画”出来

绘制回调是自定义控件的灵魂。无论你用的是什么GUI框架——LVGL、TouchGFX、还是自己写的简易引擎——底层原理都一样：在指定的矩形区域内，用像素画你需要的东西。

拿仪表盘举例。一个标准的车速表盘，需要画这几样东西：

圆弧背景（半透明灰色）
刻度线（长短交替，均匀分布）
数字标签（0、20、40...直到最大值）
指针（从圆心指向当前值）
中心圆点（装饰）

下面是一个简化版的绘制回调代码。注意，我用了极坐标转直角坐标的公式来计算刻度和指针的位置：

// 仪表盘绘制回调
void gauge_draw(gauge_t *gauge, canvas_t *canvas) {
    int cx = gauge->width / 2;   // 圆心X
    int cy = gauge->height / 2;  // 圆心Y
    int radius = (cx < cy) ? cx : cy;  // 取较小值

    // 1. 画圆弧背景（从 -135° 到 +135°）
    canvas_draw_arc(canvas, cx, cy, radius - 10,
                    -135, 135, gauge->style.bg_color);

    // 2. 画刻度线
    for (int i = 0; i <= 10; i++) {
        float angle = -135 + (i * 27.0f);  // 270° / 10 段
        float rad = angle * 3.14159f / 180.0f;

        int inner_r = (i % 5 == 0) ? radius - 25 : radius - 15;
        int outer_r = radius - 10;

        int x1 = cx + inner_r * cos(rad);
        int y1 = cy + inner_r * sin(rad);
        int x2 = cx + outer_r * cos(rad);
        int y2 = cy + outer_r * sin(rad);

        canvas_draw_line(canvas, x1, y1, x2, y2,
                         gauge->style.tick_color, 2);
    }

    // 3. 画指针
    float angle = -135 + (gauge->value / gauge->max_value) * 270.0f;
    float rad = angle * 3.14159f / 180.0f;
    int px = cx + (radius - 30) * cos(rad);
    int py = cy + (radius - 30) * sin(rad);

    canvas_draw_line(canvas, cx, cy, px, py,
                     gauge->style.needle_color, 4);
    canvas_fill_circle(canvas, cx, cy, 6,
                       gauge->style.center_color);
}

我的经验：绘制回调里不要做任何内存分配。我曾经在回调里用 malloc 临时创建了一个路径缓存，结果在60fps的刷新率下，内存碎片暴涨，系统三天后挂了。绘制回调应该是纯计算+纯绘制，所有资源在控件初始化时准备好。

4.3 事件处理：让控件“活”起来

光能画还不够。控件得能响应用户操作。比如点击仪表盘切换显示模式，或者拖动波形图的缩放条。

事件处理的核心是命中检测。说白了，就是判断用户点在了控件的哪个区域。我一般用区域矩形来做第一层过滤，再用几何计算做精确判断。

举个例子，波形图控件需要支持双指缩放：

// 波形图事件处理
int waveform_on_touch(waveform_t *wf, touch_event_t *evt) {
    // 先判断是否在控件区域内
    if (!rect_contains(&wf->rect, evt->x, evt->y)) {
        return 0;  // 不处理
    }

    if (evt->type == TOUCH_DOWN) {
        wf->touch_count++;
        if (wf->touch_count == 1) {
            // 单指：记录起始位置，准备平移
            wf->pan_start_x = evt->x;
            wf->pan_start_offset = wf->x_offset;
        } else if (wf->touch_count == 2) {
            // 双指：记录间距，准备缩放
            wf->pinch_distance = get_distance(evt->x, evt->y,
                                              wf->last_x, wf->last_y);
            wf->pinch_scale = wf->scale;
        }
        return 1;
    }

    if (evt->type == TOUCH_MOVE) {
        if (wf->touch_count == 1) {
            // 平移波形
            int dx = evt->x - wf->pan_start_x;
            wf->x_offset = wf->pan_start_offset + dx;
        } else if (wf->touch_count == 2) {
            // 缩放波形
            float dist = get_distance(evt->x, evt->y,
                                      wf->last_x, wf->last_y);
            float ratio = dist / wf->pinch_distance;
            wf->scale = wf->pinch_scale * ratio;
            if (wf->scale < 0.5f) wf->scale = 0.5f;
            if (wf->scale > 5.0f) wf->scale = 5.0f;
        }
        return 1;
    }

    return 0;
}

避坑指南：我曾经在事件处理里直接修改了控件的尺寸，然后触发了重绘，重绘又触发了布局更新，布局更新又调用了事件处理——死循环了。所以，事件处理里不要触发自身控件的布局变更。如果需要改尺寸，用标志位延迟到主循环里处理。

4.4 样式封装：让控件“变”得好看

样式封装，说白了就是把所有跟外观相关的参数抽出来，放到一个结构体里。这样，换皮肤、改主题就只需要改这个结构体，不用动绘制逻辑。

我一般这样定义样式：

// 仪表盘样式结构体
typedef struct {
    uint32_t bg_color;       // 背景色
    uint32_t arc_color;      // 圆弧颜色
    uint32_t tick_color;     // 刻度颜色
    uint32_t label_color;    // 数字标签颜色
    uint32_t needle_color;   // 指针颜色
    uint32_t center_color;   // 中心圆颜色
    uint8_t  border_width;   // 边框宽度
    uint8_t  tick_count;     // 刻度数量
    uint16_t min_value;      // 最小值
    uint16_t max_value;      // 最大值
    const char *unit;        // 单位字符串
} gauge_style_t;

然后提供几个预设样式：

样式名称	适用场景	主色调
`GAUGE_STYLE_DARK`	夜间模式、车载仪表	深灰底 + 蓝绿指针
`GAUGE_STYLE_LIGHT`	室内设备、消费电子	白底 + 红指针
`GAUGE_STYLE_INDUSTRIAL`	工控屏、PLC面板	黑底 + 黄绿刻度

使用时，只需要一行代码切换：

gauge_set_style(my_gauge, &GAUGE_STYLE_DARK);

我的习惯：样式结构体里不要放函数指针。有人喜欢把绘制回调也塞进样式里，觉得这样“更面向对象”。但实际项目中，样式是数据，回调是行为，混在一起会导致同一个控件实例无法动态切换绘制逻辑。把回调放在控件主结构体里，样式只负责“长什么样”。

4.5 集成到现有框架：三步走

好了，控件写好了。怎么把它塞进你现有的GUI框架里？我总结了三步：

注册控件类型：告诉框架“我有一个新控件，叫仪表盘”。框架会分配一个唯一的类型ID。
绑定生命周期：实现创建、销毁、绘制、事件这四个回调函数，注册到框架的调度器里。
暴露配置接口：提供 gauge_create()、gauge_set_value()、gauge_set_style() 等API，让上层应用调用。

下面是一个集成到LVGL的示例（伪代码）：

// 1. 注册控件
lv_obj_t *gauge = lv_gauge_create(lv_scr_act(), NULL);
lv_obj_set_size(gauge, 200, 200);
lv_obj_align(gauge, NULL, LV_ALIGN_CENTER, 0, 0);

// 2. 设置值
lv_gauge_set_value(gauge, 75);

// 3. 切换样式
lv_gauge_set_style(gauge, &GAUGE_STYLE_INDUSTRIAL);

你看，对上层应用来说，自定义控件用起来跟原生控件一模一样。这就是封装的力量。

4.6 知识体系总览

下面这张图，是我做自定义控件开发时的思维导图。每次动手前，我都会先过一遍这个框架：

嗯，这张图基本概括了本章的所有内容。你写自定义控件时，可以把它贴在工位上，每写完一层就打个勾。我当年就是这么干的，效率提升很明显。

最后说一句：不要追求一次写出完美的控件。先跑起来，再优化。我在第一个仪表盘项目里，指针绘制用了整整三天才调对角度。但跑通的那一刻，那种成就感——值得。

📚 课程目录

4、自定义控件开发：从零实现一个可复用的自定义控件

4.1 自定义控件的三层架构

4.2 绘制回调：让控件“画”出来

4.3 事件处理：让控件“活”起来

4.4 样式封装：让控件“变”得好看

4.5 集成到现有框架：三步走

4.6 知识体系总览