13. 文本区域部件
一、文本区域部件
文本域部件就是我们常用的文本输入框，用户可以在其中输入所需文本。文本区域部件由五个部分组成：
- 主体（
LV_PART_MAIN）：可设置背景属性以及文本样式属性。 - 滚动条（
LV_PART_SCROLLBAR）：可设置滚动条样式属性。 - 所选文本（
LV_PART_SELECTED）：可设置所选文本的样式。 - 光标（
LV_PART_CURSOR）：设置光标的位置、闪烁时间和样式属性。 - 占位符（
LV_PART_TEXTAREA_PLACEHOLDER）：可设置占位符（提示文本）的样式。
LVGL 官方提供了一些与文本区域部件相关 API。
lv_obj_t * lv_textarea_create(lv_obj_t * parent); // 创建文本区域对象
void lv_textarea_add_char(lv_obj_t * obj, uint32_t c); // 插入一个字符到当前光标位置
void lv_textarea_delete_char(lv_obj_t * obj); // 删除当前光标左侧的字符
void lv_textarea_delete_char_forward(lv_obj_t * obj); // 删除当前光标右侧的字符
void lv_textarea_add_text(lv_obj_t * obj, const char * txt); // 将文本插入到当前光标位置
void lv_textarea_set_text(lv_obj_t * obj, const char * txt); // 设置文本
const char * lv_textarea_get_text(const lv_obj_t * obj); // 获取文本区域的文本
void lv_textarea_set_placeholder_text(lv_obj_t * obj, const char * txt); // 设置占位符文本
const char * lv_textarea_get_placeholder_text(lv_obj_t * obj); // 获取文本区域的占位符文本
lv_obj_t * lv_textarea_get_label(const lv_obj_t * obj); // 获取文本区域的标签
void lv_textarea_set_cursor_pos(lv_obj_t * obj, int32_t pos); // 设置光标位置
uint32_t lv_textarea_get_cursor_pos(const lv_obj_t * obj); // 获取当前光标在字符索引中的位置
void lv_textarea_cursor_up(lv_obj_t * obj); // 将光标向上移动一个字符
void lv_textarea_cursor_down(lv_obj_t * obj); // 将光标向下移动一个字符
void lv_textarea_cursor_left(lv_obj_t * obj); // 将光标向左移动一个字符
void lv_textarea_cursor_right(lv_obj_t * obj); // 将光标向右移动一个字符
void lv_textarea_set_cursor_click_pos(lv_obj_t * obj, bool en); // 启用/禁用光标的位置
bool lv_textarea_get_cursor_click_pos(lv_obj_t * obj); // 获取是否启用光标单击定位
void lv_textarea_set_password_mode(lv_obj_t * obj, bool en); // 设置密码模式
bool lv_textarea_get_password_mode(const lv_obj_t * obj); // 获取密码模式属性
void lv_textarea_set_password_show_time(lv_obj_t * obj, uint32_t time); // 将密码更改为“*”之前显示多长时间
uint32_t lv_textarea_get_password_show_time(lv_obj_t * obj); // 获取密码更改为“*”之前显示的时间
void lv_textarea_set_one_line(lv_obj_t * obj, bool en); // 设置单行模式
bool lv_textarea_get_one_line(const lv_obj_t * obj); // 查看是否启用了一行模式
void lv_textarea_set_text_selection(lv_obj_t * obj, bool en); // 启用/禁用选择模式
bool lv_textarea_get_text_selection(lv_obj_t * obj); // 查看是否启用了选择模式
bool lv_textarea_text_is_selected(const lv_obj_t * obj); // 查找文本是否被选中
void lv_textarea_clear_selection(lv_obj_t * obj); // 清除文本区域上的选择
void lv_textarea_set_accepted_chars(lv_obj_t * obj, const char * list); // 限制输入字符的类型
const char * lv_textarea_get_accepted_chars(lv_obj_t * obj); // 获取可接收字符的列表
void lv_textarea_set_max_length(lv_obj_t * obj, uint32_t num); // 限制输入字符的长度
uint32_t lv_textarea_get_max_length(lv_obj_t * obj); // 获取文本区域的最大长度
void lv_textarea_set_insert_replace(lv_obj_t * obj, const char * txt); // 文本区域添加自动格式
我们可以使用 lv_textarea_create() 函数 创建文本区域部件。
/**
* @brief 创建文本区域对象
*
* @param parent 指向父部件的指针
* @return lv_obj_t* 指向文本区域部件的指针
*/
lv_obj_t * lv_textarea_create(lv_obj_t * parent);
文本区域部件就是一个文本输入框， 用户可以在该部件的文本区域中输入字符和删除字符。用户需要在文本区域中 添加一个字符或者一段字符串，可分别调用 lv_textarea_add_char() 和 lv_textarea_add_text() 函数。
/**
* @brief 插入一个字符到当前光标位置
*
* @param obj 指向文本区域部件的指针
* @param c 要插入的字符
*/
void lv_textarea_add_char(lv_obj_t * obj, uint32_t c);
/**
* @brief 将文本插入到当前光标位置
*
* @param obj 指向文本区域部件的指针
* @param txt 要插入的字符串
*/
void lv_textarea_add_text(lv_obj_t * obj, const char * txt);
在 LVGL 中，我们可以调用 lv_textarea_delete_char() 函数，从光标位置的左侧删除一个字符，也可以调用 lv_textarea_delete_char_forward() 函数，从光标位置的右侧删除一个字符。
/**
* @brief 删除当前光标左侧的字符
*
* @param obj 指向文本区域部件的指针
*/
void lv_textarea_delete_char(lv_obj_t * obj);
/**
* @brief 删除当前光标右侧的字符
*
* @param obj 指向文本区域部件的指针
*/
void lv_textarea_delete_char_forward(lv_obj_t * obj);
占位符（Placeholder）即默认显示的文本，常用于对用户进行默认的提示、说明或引导。在 LVGL 中，用户可调用 lv_textarea_set_placeholder_text() 函数 设置占位文本。
/**
* @brief 设置占位符文本
*
* @param obj 指向文本区域部件的指针
* @param txt 占位文本
*/
void lv_textarea_set_placeholder_text(lv_obj_t * obj, const char * txt);
在 LVGL 中，文本区域的光标默认在左上角的位置。当我们添加一个字符时，该光标从左往右移动，默认情况下，光标会一直在文本最后一个字符的右侧。如果用户需要 设置光标的位置，可调用 lv_textarea_set_cursor_pos() 函数，该函数的第二个形参表示光标的移动位置，当该形参设置为 0，则光标在第一个字符之前；当该形参设置为 LV_TA_CURSOR_LAST，则光标在最后一个字符之后。
/**
* @brief 设置光标位置
*
* @param obj 指向文本区域部件的指针
* @param pos 光标的移动位置
*/
void lv_textarea_set_cursor_pos(lv_obj_t * obj, int32_t pos);
如果用户不想使用上述的方式设置光标的位置，可使用以下函数，单步移动光标。
void lv_textarea_cursor_up(lv_obj_t * obj); // 将光标向上移动一个字符
void lv_textarea_cursor_down(lv_obj_t * obj); // 将光标向下移动一个字符
void lv_textarea_cursor_left(lv_obj_t * obj); // 将光标向左移动一个字符
void lv_textarea_cursor_right(lv_obj_t * obj); // 将光标向右移动一个字符
在 LVGL 中，文本区域部件的特殊模式有两个：单行模式 和 密码模式。
- 单行模式：默认情况下，文本区域的文本超出它的宽度时，该文本将自动换行。如果将文本区域部件设置为单行模式，当它的文本超出其宽度后，文本并不会自动换行，超出的文本将水平滚动显示。单行模式可通过
lv_textarea_set_one_line()函数进行设置。 - 密码模式：为了保证文本的机密性，LVGL 的文本区域部件为用户提供了密码模式，当用户输入文本之后，这些文本内容将以“*”字符替代。用户需要设置密码模式，可调用
lv_textarea_set_password_mode()函数。
/**
* @brief 设置单行模式
*
* @param obj 指向文本区域部件的指针
* @param en true: 启用; false: 不启用
*/
void lv_textarea_set_one_line(lv_obj_t * obj, bool en);
/**
* @brief 设置密码模式
*
* @param obj 指向文本区域部件的指针
* @param en true: 启用; false: 不启用
*/
void lv_textarea_set_password_mode(lv_obj_t * obj, bool en);
当用户使用密码模式时，原始文本会先显示一段时间，然后隐藏，该显示时间可以在 lv_conf.h 文件的
LV_TEXTAREA_DEF_PWD_SHOW_TIME宏定义中设置。如果用户想获取密码框的文本内容，可调用
lv_textarea_get_text()函数，返回的文本并不是“*”字符，而是原始的文本内容。
文本区域部件可以限制输入字符的范围。LVGL 文本区域部件限制输入字符的内容有两个：限制字符类型 和 限制字符长度。
- 限制字符类型，它只能输入数字 0~9。用户需要限制字符类型，可以调用
lv_textarea_set_accepted_chars()函数进行设置。 - 限制字符长度，，它只能输入 6 位密码。用户需要限制字符长度，可以调用
lv_textarea_set_max_length()函数进行设置。
/**
* @brief 限制输入字符的类型
*
* @param obj 指向文本区域部件的指针
* @param list 允许输入的字符列表指针
*/
void lv_textarea_set_accepted_chars(lv_obj_t * obj, const char * list);
/**
* @brief 限制输入字符的长度
*
* @param obj 指向文本区域部件的指针
* @param num 限制输入字符的长度
*/
void lv_textarea_set_max_length(lv_obj_t * obj, uint32_t num);
二、实验例程
#include "lvgl.h"
#include "lv_port_disp_template.h"
#include "lv_port_indev_template.h"
lv_obj_t *label;
int main(void)
{
HAL_Init();
System_Clock_Init(8, 336, 2, 7);
Delay_Init(168);
SPI_Simulate_Init();
// SRAM_Init();
TIM_Base_Init(&g_tim6_handle, TIM6, 83, 999);
__HAL_TIM_CLEAR_IT(&g_tim6_handle, TIM_IT_UPDATE); // 清除更新中断标志位
HAL_TIM_Base_Start_IT(&g_tim6_handle); // 使能更新中断，并启动计数器
lv_init();
lv_port_disp_init();
lv_port_indev_init();
// 测试代码
label = lv_label_create(lv_scr_act()); // 创建标签部件
lv_obj_set_align(label, LV_ALIGN_TOP_MID); // 设置标签部件考上居中对齐
lv_obj_set_style_text_font(label, &lv_font_montserrat_30, LV_PART_MAIN); // 设置标签部件的字体样式
lv_label_set_text(label, "textArea test"); // 设置标签部件的文本
lv_obj_t *textArea = lv_textarea_create(lv_scr_act()); // 创建文本区域部件
lv_obj_align(textArea, LV_ALIGN_TOP_MID, 0, 50); // 设置文本区域部件考上居中对齐
lv_obj_t *keyBoard = lv_keyboard_create(lv_scr_act()); // 创建键盘部件
lv_keyboard_set_textarea(keyBoard, textArea); // 关联键盘部件和文本区域部件
lv_textarea_set_one_line(textArea, true); // 设置单行模式
lv_textarea_set_password_mode(textArea, true); // 设置密码模式
lv_textarea_set_password_show_time(textArea, 1000); // 设置密码显示时间
lv_textarea_set_accepted_chars(textArea, "1234567890"); // 设置允许输入的字符
lv_textarea_set_max_length(textArea, 6); // 设置最大字符长度
lv_textarea_set_placeholder_text(textArea, "Please enter password"); // 设置占位符
lv_obj_add_event_cb(textArea, textArea_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
while (1)
{
lv_timer_handler();
Delay_ms(5);
}
return 0;
}
void textArea_event_cb(lv_event_t *e)
{
lv_event_code_t code = lv_event_get_code(e); // 获取事件的触发类型
lv_obj_t *target = lv_event_get_target(e); // 获取事件的触发源
const char *text;
if(code == LV_EVENT_VALUE_CHANGED)
{
text = lv_textarea_get_text(target); // 获取文本
lv_label_set_text(label, text);
}
}
