LVGL（lv_keyboard键盘）

---

---

LVGL 中的 lv_keyboard 详解

lv_keyboard 是 LVGL 提供的一个虚拟键盘控件，通常用于触摸屏设备，在需要文本输入时配合 lv_textarea 使用。它支持数字键盘、英文键盘、符号键盘等多种模式，能够有效提高嵌入式系统下的人机交互体验。

---

一、基本概念

1. 主要用途

• 与 lv_textarea 搭配，提供触控输入。
• 适合嵌入式设备（如 STM32 + 屏幕）中替代实体键盘。

2. 类型定义

lv_obj_t * lv_keyboard_create(lv_obj_t * parent);

创建一个键盘对象，指定其父对象。

---

二、常用函数接口

1. 创建键盘

lv_obj_t * kb = lv_keyboard_create(lv_scr_act());

创建一个键盘控件，并挂载在当前活动屏幕上。

---

2. 设置目标输入框（关联文本输入）

lv_keyboard_set_textarea(kb, ta);

将键盘与一个 lv_textarea 对象 ta 关联，使得点击键盘时自动向该输入框插入文本。

---

3. 设置键盘模式

lv_keyboard_set_mode(kb, LV_KEYBOARD_MODE_TEXT);

LVGL 键盘支持几种输入模式：

模式枚举值	说明
LV_KEYBOARD_MODE_TEXT	默认英文全键盘
LV_KEYBOARD_MODE_NUM	数字键盘（0-9）
LV_KEYBOARD_MODE_SPECIAL	符号键盘
LV_KEYBOARD_MODE_USER_1/2	用户自定义模式

---

4. 获取当前模式

lv_keyboard_mode_t mode = lv_keyboard_get_mode(kb);

---

5. 设置键盘关闭时的回调（如隐藏键盘）

lv_obj_add_event_cb(kb, keyboard_event_cb, LV_EVENT_VALUE_CHANGED, NULL);

常见的处理方式是在回调中检查是否按下的是 “OK” 或 “Close” 键，然后隐藏键盘。

void keyboard_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * kb = lv_event_get_target(e);

    if(code == LV_EVENT_VALUE_CHANGED) {
        const char * txt = lv_btnmatrix_get_btn_text(kb, lv_btnmatrix_get_selected_btn(kb));
        if(strcmp(txt, "OK") == 0 || strcmp(txt, "Close") == 0) {
            lv_obj_add_flag(kb, LV_OBJ_FLAG_HIDDEN); // 隐藏键盘
        }
    }
}

---

三、使用示例

lv_obj_t * ta = lv_textarea_create(lv_scr_act());
lv_obj_set_size(ta, 200, 50);
lv_obj_center(ta);

// 创建键盘并关联输入框
lv_obj_t * kb = lv_keyboard_create(lv_scr_act());
lv_obj_set_size(kb, 320, 150);
lv_keyboard_set_textarea(kb, ta);

这样点击键盘时输入内容就会同步到 ta 上了。

---

四、自定义键盘布局（进阶）

你也可以通过 lv_btnmatrix_set_map 自定义键盘键值布局，例如：

static const char * my_map[] = {
    "A", "B", "C", "\n",
    "1", "2", "3", "\n",
    "OK", "DEL", ""
};

lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_USER_1, my_map, NULL);
lv_keyboard_set_mode(kb, LV_KEYBOARD_MODE_USER_1);

---

五、注意事项

• 创建 lv_keyboard 后默认是全键盘布局，使用 lv_keyboard_set_mode 切换其他模式。
• 键盘控件通常不需要放在滚动区域或页面中，应固定在屏幕底部。
• lv_keyboard 默认高度比较高，如有需求可根据分辨率进行缩放或裁剪。

---

六、典型应用场景

• 触摸屏上的登录界面（账号/密码输入）
• 设置界面中的数值/名称输入
• 终端设备的用户交互（如 POS 机、工业设备）

---