文章目录
- [LVGL 中的 `lv_keyboard` 详解](#LVGL 中的
lv_keyboard
详解)
LVGL 中的 lv_keyboard
详解
lv_keyboard
是 LVGL 提供的一个虚拟键盘控件 ,通常用于触摸屏设备,在需要文本输入时配合 lv_textarea
使用。它支持数字键盘、英文键盘、符号键盘等多种模式,能够有效提高嵌入式系统下的人机交互体验。
一、基本概念
1. 主要用途
- 与
lv_textarea
搭配,提供触控输入。 - 适合嵌入式设备(如 STM32 + 屏幕)中替代实体键盘。
2. 类型定义
c
lv_obj_t * lv_keyboard_create(lv_obj_t * parent);
创建一个键盘对象,指定其父对象。
二、常用函数接口
1. 创建键盘
c
lv_obj_t * kb = lv_keyboard_create(lv_scr_act());
创建一个键盘控件,并挂载在当前活动屏幕上。
2. 设置目标输入框(关联文本输入)
c
lv_keyboard_set_textarea(kb, ta);
将键盘与一个 lv_textarea
对象 ta
关联,使得点击键盘时自动向该输入框插入文本。
3. 设置键盘模式
c
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. 获取当前模式
c
lv_keyboard_mode_t mode = lv_keyboard_get_mode(kb);
5. 设置键盘关闭时的回调(如隐藏键盘)
c
lv_obj_add_event_cb(kb, keyboard_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
常见的处理方式是在回调中检查是否按下的是 "OK" 或 "Close" 键,然后隐藏键盘。
c
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); // 隐藏键盘
}
}
}
三、使用示例
c
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
自定义键盘键值布局,例如:
c
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 机、工业设备)