---

---

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 機、工業設備）

---