文章目录
- 一、`lv_textarea` 是什么？
- 二、基本用法
- 1. 创建 `lv_textarea` 对象
- 2. 设置提示文字（占位符）
- 3. 设置最大长度
- 4. 设置密码模式（显示为\*号）
- 5. 获取和设置内容
- 6. 配合虚拟键盘使用（常用于触摸屏）
- 三、常用 API 汇总
- 四、实际应用示例
- 五、注意事项
- 六、典型应用场景
- 总结
lv_textarea 是 LVGL（Light and Versatile Graphics Library）中用于实现**文本输入框（多行或单行）**的控件，通常与虚拟键盘配合使用，是用户输入内容（如用户名、密码、配置参数等）时的关键组件。
一、lv_textarea 是什么？
lv_textarea 是一个支持编辑和滚动的文本显示区域。它提供了如下功能：
- 文本显示与换行
- 光标显示与移动
- 支持字符插入与删除
- 可设置最大长度、密码模式
- 可与虚拟键盘结合使用
二、基本用法
1. 创建 lv_textarea 对象
lv_obj_t * ta = lv_textarea_create(lv_scr_act());
lv_obj_set_size(ta, 200, 100);
lv_obj_align(ta, LV_ALIGN_CENTER, 0, 0);
2. 设置提示文字（占位符）
lv_textarea_set_placeholder_text(ta, "请输入内容...");
3. 设置最大长度
lv_textarea_set_max_length(ta, 32); // 最多输入32字符
4. 设置密码模式（显示为*号）
lv_textarea_set_password_mode(ta, true);
5. 获取和设置内容
const char *text = lv_textarea_get_text(ta);
lv_textarea_set_text(ta, "预设值");
6. 配合虚拟键盘使用（常用于触摸屏）
lv_obj_t *kb = lv_keyboard_create(lv_scr_act());
lv_keyboard_set_textarea(kb, ta); // 关联输入框
三、常用 API 汇总
| 函数 | 说明 |
|---|---|
lv_textarea_create(parent) | 创建文本框控件 |
lv_textarea_set_text() | 设置内容 |
lv_textarea_get_text() | 获取内容 |
lv_textarea_set_cursor_pos() | 设置光标位置 |
lv_textarea_set_one_line(true) | 设置为单行输入模式 |
lv_textarea_set_password_mode(true) | 开启密码模式（显示为 *） |
lv_textarea_set_placeholder_text() | 设置占位提示文本 |
lv_textarea_set_max_length(n) | 限制最大字符数 |
lv_textarea_add_char() | 插入字符 |
lv_textarea_del_char() | 删除字符 |
四、实际应用示例
void create_textarea_with_keyboard(void) {
lv_obj_t *ta = lv_textarea_create(lv_scr_act());
lv_obj_set_size(ta, 200, 80);
lv_textarea_set_placeholder_text(ta, "请输入用户名");
lv_obj_t *kb = lv_keyboard_create(lv_scr_act());
lv_keyboard_set_textarea(kb, ta);
lv_obj_align(kb, LV_ALIGN_BOTTOM_MID, 0, 0);
}
五、注意事项
lv_textarea默认支持多行输入，如需单行模式需手动设置。- 结合键盘时需要明确焦点指向哪个输入框。
- 当字符数达到最大长度后，输入无效但不会报错。
六、典型应用场景
- 用户登录输入框（用户名/密码）
- 配置界面输入参数（如 IP 地址、设备名等）
- 日志编辑、搜索框等需要输入文字的界面
总结
lv_textarea 是 LVGL 中实现用户交互输入的核心控件，功能类似于桌面 GUI 中的输入框（如 Qt 的 QLineEdit/QTextEdit）。通过合理使用其密码模式、占位符、最大长度控制等功能，并配合 lv_keyboard 虚拟键盘，可以轻松实现丰富的嵌入式触控输入界面。
