LVGL（lv_spinbox微调框控件）

---

lv_spinbox 是 LVGL（Light and Versatile Graphics Library） 中的一个用于数值输入的组件，外观上类似一个可以上下调整数字的小输入框，常用于需要手动设定数值的场景，如温度设置、时间调整、计量参数输入等。

---

一、什么是 lv_spinbox

lv_spinbox 是一个派生自 lv_textarea 的控件，支持以下功能：

• 显示数字（整数或带小数点）
• 使用加减按钮或代码修改值
• 限制最大/最小值
• 控制步进值（increment）
• 设置游标位置，控制编辑哪一位数字
• 支持符号（+/-）

---

⚙️ 二、常用 API 简介

1️⃣ 创建 lv_spinbox 对象

lv_obj_t * spinbox = lv_spinbox_create(parent);

2️⃣ 设置参数

lv_spinbox_set_range(spinbox, -100, 100);       // 设置范围
lv_spinbox_set_digit_format(spinbox, 5, 2);     // 设置格式：5位数字，2位小数（例如 00.00）
lv_spinbox_set_step(spinbox, 1);                // 设置步进
lv_spinbox_set_rollover(spinbox, true);         // 设置是否值滚动（超过最大值回到最小值）

3️⃣ 增加 / 减少当前数字

lv_spinbox_increment(spinbox); // 加
lv_spinbox_decrement(spinbox); // 减

4️⃣ 光标控制

lv_spinbox_step_next(spinbox); // 游标右移
lv_spinbox_step_prev(spinbox); // 游标左移

---

三、简单示例代码

lv_obj_t * spinbox = lv_spinbox_create(lv_scr_act());
lv_spinbox_set_range(spinbox, -50, 100);
lv_spinbox_set_digit_format(spinbox, 5, 1);  // 例如：012.3
lv_spinbox_set_step(spinbox, 1);
lv_spinbox_set_rollover(spinbox, true);
lv_obj_set_width(spinbox, 100);
lv_obj_center(spinbox);

// 增加按钮
lv_obj_t * btn_up = lv_btn_create(lv_scr_act());
lv_obj_align_to(btn_up, spinbox, LV_ALIGN_OUT_RIGHT_TOP, 10, 0);
lv_obj_add_event_cb(btn_up, event_handler, LV_EVENT_CLICKED, spinbox);

// 减少按钮
lv_obj_t * btn_down = lv_btn_create(lv_scr_act());
lv_obj_align_to(btn_down, spinbox, LV_ALIGN_OUT_RIGHT_BOTTOM, 10, 0);
lv_obj_add_event_cb(btn_down, event_handler, LV_EVENT_CLICKED, spinbox);

void event_handler(lv_event_t * e) {
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * btn = lv_event_get_target(e);
    lv_obj_t * spinbox = lv_event_get_user_data(e);

    if(code == LV_EVENT_CLICKED) {
        if(btn == btn_up)
            lv_spinbox_increment(spinbox);
        else if(btn == btn_down)
            lv_spinbox_decrement(spinbox);
    }
}

---

四、显示效果

一般来说，lv_spinbox 在屏幕上显示为一个可以编辑的数字框，通过按钮或代码增减数值，像这样：

+------------+
|   123.4    |
+------------+
 ↑        ↓

---

五、注意事项

事项	说明
格式控制	lv_spinbox_set_digit_format() 非常关键，决定了显示格式
范围限制	如果设置的值超过范围，spinbox 会自动限制在合法值范围内
小数支持	可以通过 digit_format 设置显示小数点后的位数
编辑交互	支持按键控制光标移动，适合嵌入式设备的物理按钮输入

---

六、适合场景

• 设备设置页面（例如设置温度、电压、时间等）
• 表单输入框（需要明确的数字输入）
• 小屏幕设备（需要简洁明了的用户界面）

---