31. Span部件
一、Span部件
Span 部件常用于文本的修饰，它可以汇聚不同字体、颜色和大小的文本。Span 部件的组成部分仅有一个：主体（LV_PART_MAIN)。
LVGL 官方提供了一些与 Span 部件相关 API。
lv_obj_t * lv_spangroup_create(lv_obj_t * par); // 创建Span组
lv_span_t * lv_spangroup_new_span(lv_obj_t * obj); // 创建Span描述符
void lv_spangroup_delete_span(lv_obj_t * obj, lv_span_t * span); // 删除Span描述符
void lv_span_set_text(lv_span_t * span, const char * text); // 设置文本
void lv_span_set_text_static(lv_span_t * span, const char * text); // 设置静态文本
void lv_spangroup_set_align(lv_obj_t * obj, lv_text_align_t align); // 设置对齐模式
lv_text_align_t lv_spangroup_get_align(lv_obj_t * obj); // 获取对齐模式
void lv_spangroup_set_overflow(lv_obj_t * obj, lv_span_overflow_t overflow); // 设置溢出模式
lv_span_overflow_t lv_spangroup_get_overflow(lv_obj_t * obj); // 获取溢出模式
void lv_spangroup_set_indent(lv_obj_t * obj, int32_t indent); // 设置文本首行缩进
int32_t lv_spangroup_get_indent(lv_obj_t * obj); // 获取文本首行缩进
void lv_spangroup_set_mode(lv_obj_t * obj, lv_span_mode_t mode); // 设置Span组模式
lv_span_mode_t lv_spangroup_get_mode(lv_obj_t * obj); // 获取Span组模式
void lv_spangroup_set_max_lines(lv_obj_t * obj, int32_t lines); // 设置显示的最大行数
int32_t lv_spangroup_get_max_lines(lv_obj_t * obj); // 获取显示的显示行数
int32_t lv_spangroup_get_max_line_height(lv_obj_t * obj); // 获取行的最大高度
uint32_t lv_spangroup_get_expand_width(lv_obj_t * obj, uint32_t max_width); // 获取扩大宽度
int32_t lv_spangroup_get_expand_height(lv_obj_t * obj, int32_t width); // 获取扩大高度
lv_span_t * lv_spangroup_get_child(const lv_obj_t * obj, int32_t id); // 获取子类
void lv_spangroup_refr_mode(lv_obj_t * obj); // 更新模式
Span 部件是用来描述文本以及修改文本样式的，在设置文本样式之前，我们必须创建 Span 部件的描述符，然后设置它的文本样式属性，最后让 Span 部件的样式通过其样式成员配置为普通样式，这样我们就可以使用跨度部件来修饰文本样式了。
static lv_style_t style; // 定义普通样式
lv_style_init(&style); // 通样式初始化
然后，我们调用 lv_spangroup_create() 函数，创建 Span 部件组，这个组是用来添加 Span 部件描述符的。
/**
* @brief 创建Span组
*
* @param par 指向父部件的指针
* @return lv_obj_t* 指向Span组件的指针
*/
lv_obj_t * lv_spangroup_create(lv_obj_t * par);
接着，调用 lv_spangroup_new_span() 函数，创建 Span 部件的描述符并添加到 Span 组中。
/**
* @brief 创建Span描述符
*
* @param obj 指向Span部件的指针
* @return lv_span_t* 指向Span描述符的指针
*/
lv_span_t * lv_spangroup_new_span(lv_obj_t * obj);
Span 部件与标签部件一样，可以设置文本对齐的模式。如果用户需要 修改文本对齐的模式，可以调用 lv_spangroup_set_align() 函数进行设置。
/**
* @brief 设置对齐模式
*
* @param obj 指向Span部件的指针
* @param align 对齐模式
*/
void lv_spangroup_set_align(lv_obj_t * obj, lv_text_align_t align);
其中，对齐模式的可选值如下：
enum _lv_text_align_t {
LV_TEXT_ALIGN_AUTO, // 文本左对齐
LV_TEXT_ALIGN_LEFT, // 文本居中对齐
LV_TEXT_ALIGN_CENTER, // 文本右对齐
LV_TEXT_ALIGN_RIGHT, // 文本自动对齐
};
当用户创建 Span 组时，该组一般默认为 LV_SPAN_MODE_EXPAND 文本模式，如果需要 修改文本模式，可以调用 lv_spangroup_set_mode() 函数进行配置。
/**
* @brief 设置Span组模式
*
* @param obj 指向Span部件的指针
* @param mode Span组模式
*/
void lv_spangroup_set_mode(lv_obj_t * obj, lv_span_mode_t mode);
Span 组的模式有三种：
enum _lv_span_mode_t {
LV_SPAN_MODE_FIXED, // 修复对象大小
LV_SPAN_MODE_EXPAND, // 将对象大小扩展为文本大小，但保持在一行上
LV_SPAN_MODE_BREAK, // 保持宽度，断开太长的行和自动扩大高度
_LV_SPAN_MODE_LAST
};
在 LV_SPAN_MODE_BREAK 模式下，我们可以 设置最大显示行数，这个最大行数的设置函数为 lv_spangroup_set_max_lines()。
/**
* @brief 设置显示的最大行数
*
* @param obj 指向父部件的指针
* @param lines 最大行数，如果是负值，则表示无限制行数
*/
void lv_spangroup_set_max_lines(lv_obj_t * obj, int32_t lines);
文本溢出是指文本的大小超过了 Span 组的区域范围，我们可以通过 lv_spangroup_set_overflow() 函数 设置溢出模式。
/**
* @brief 设置溢出模式
*
* @param obj 指向Span部件的指针
* @param overflow 溢出模式
*/
void lv_spangroup_set_overflow(lv_obj_t * obj, lv_span_overflow_t overflow);
用户需要 设置文本的首行缩进，可以调用 lv_spangroup_set_indent() 函数进行配置，该函数的第二个形参代表缩进的像素大小，除此之外，也可以使用百分比形式来设置文本缩进。
/**
* @brief 设置文本首行缩进
*
* @param obj 指向Span部件的指针
* @param indent 缩进值
*/
void lv_spangroup_set_indent(lv_obj_t * obj, int32_t indent);
二、实验例程
#include "lvgl.h"
#include "lv_port_disp_template.h"
#include "lv_port_indev_template.h"
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();
// 测试代码
lv_obj_t *spanGroup = lv_spangroup_create(lv_scr_act()); // 创建Span部件
lv_obj_center(spanGroup); // 设置Span部件居中对齐
lv_obj_set_width(spanGroup, 300); // 设置Span部件的宽度
lv_obj_set_style_border_width(spanGroup, 1, LV_PART_MAIN); // 设置Span部件的边框宽度
lv_obj_set_style_border_color(spanGroup, lv_palette_main(LV_PALETTE_ORANGE), LV_PART_MAIN); // 设置Span部件的边框颜色
lv_spangroup_set_align(spanGroup, LV_TEXT_ALIGN_LEFT); // 设置Span部件的文本对齐方式
lv_spangroup_set_overflow(spanGroup, LV_SPAN_OVERFLOW_CLIP); // 设置Span部件的溢出方式
lv_spangroup_set_indent(spanGroup, 20); // 设置Span部件的缩进
lv_spangroup_set_mode(spanGroup, LV_SPAN_MODE_BREAK); // 设置Span部件的组模式
lv_span_t *span = lv_spangroup_new_span(spanGroup); // 创建并新建Span
lv_span_set_text(span, "This is span 1."); // 设置Span文本
lv_style_set_text_font(&span->style, &lv_font_montserrat_30); // 设置Span文本样式
lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED)); // 设置Span文本颜色
lv_style_set_text_decor(&span->style, LV_TEXT_DECOR_STRIKETHROUGH | LV_TEXT_DECOR_UNDERLINE); // 设置Span文本格式
lv_style_set_text_opa(&span->style, LV_OPA_30); // 设置Span文本透明度
while (1)
{
lv_timer_handler();
Delay_ms(5);
}
return 0;
}
