Span（富文本） (lv_span)

Overview（概述）

显示原文

A spangroup is the object that is used to display rich text. Different from the label object, spangroup can render text styled with different fonts, colors, and sizes into the spangroup object.

spangroup（富文本）是用于显示富文本（纯文本）的对象。不同于Label对象，其可以呈现多种文本样式，将不同的字体、颜色和大小添加到 spangroup 对象中。

Parts and Styles（部分和样式）

显示原文

LV_PART_MAIN The spangroup has only one part.

LV_PART_MAIN spangroup只有一个部分。

Usage（用法）

Set text and style（设置文本和样式）

显示原文

The spangroup object uses span to describe text and text style. so, first we need to create span descriptor using lv_span_t * span = lv_spangroup_new_span(spangroup). Then use lv_span_set_text(span, "text") to set text. The style of the span is configured as with a normal style object by using its style member, eg:lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED)).

If spangroup object mode != LV_SPAN_MODE_FIXED you must call lv_spangroup_refr_mode() after you have modified span style(eg:set text, changed the font size, del span).

spangroup 对象使用 span 来描述文本和文本样式。所以首先，我们需要使用函数 lv_span_t * span = lv_spangroup_new_span(spangroup) 创建 span 描述符。然后使用函数 lv_span_set_text(span, "text") 设置文本。其样式使用 style 普通样式，例如：lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))。

修改 span 的样式后（比如：大小、文本、更改大小、删除span），如果 spangroup 对象的 mode != LV_SPAN_MODE_FIXED 就需要调用函数 lv_spangroup_refr_mode()

Retrieving a span child（检索 span 子项）

显示原文

Spangroups store their children differently from normal objects, so normal functions for getting children won't work.

lv_spangroup_get_child(spangroup, id) will return a pointer to the child span at index id. In addition, id can be negative to index from the end of the spangroup where -1 is the youngest child, -2 is second youngest, etc.

E.g. lv_span_t* span = lv_spangroup_get_child(spangroup, 0) will return the first child of the spangroup. lv_span_t* span = lv_spangroup_get_child(spangroup, -1) will return the last (or most recent) child.

Spangroups 存储其子对象的方式与普通对象不同，因此常规子项的正常功能将不起作用。

lv_spangroup_get_child(spangroup, id) 将返回指向 id 索引处的子span。此外， id 可以是负数这将从跨组的末尾开始索引： -1 最小的孩子在哪里， -2 是第二年轻的孩子，等等。

例如 lv_span_t* span = lv_spangroup_get_child(spangroup, 0) 将返回 spangroup 的第一个子项。 lv_span_t* span = lv_spangroup_get_child(spangroup, -1) 将返回最后一个（或最近）的子项。

Child Count（子项计数）

显示原文

Use the function lv_spangroup_get_span_count(spangroup) to get back the number of spans the group is maintaining.

E.g. uint32_t size = lv_spangroup_get_span_count(spangroup)

使用函数 lv_spangroup_get_span_count(spangroup) 返回span的总数。

例如 uint32_t size = lv_spangroup_get_span_count(spangroup)

Text align（文本对齐）

显示原文

Like label object, the spangroup can be set to one the following modes:

LV_TEXT_ALIGN_LEFT Align to left.
LV_TEXT_ALIGN_CENTER Align to center.
LV_TEXT_ALIGN_RIGHT Align to right.
LV_TEXT_ALIGN_AUTO Align auto.

Use function lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER) to set text align.

与标签对象一样，spangroup 可以设置为以下模式之一：

LV_TEXT_ALIGN_LEFT 向左对齐。
LV_TEXT_ALIGN_CENTER 居中对齐。
LV_TEXT_ALIGN_RIGHT 向右对齐。
LV_TEXT_ALIGN_AUTO 自动对齐。

使用函数 lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER) 设置相应的文本对齐模式。

Modes（模式）

显示原文

The spangroup can be set to one the following modes:

LV_SPAN_MODE_FIXED Fixes the object size.
LV_SPAN_MODE_EXPAND Expand the object size to the text size but stay on a single line.
LV_SPAN_MODE_BREAK Keep width, break the too long lines and auto expand height.

Use the function lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK) to set object mode.

spangroup 可以设置为以下模式之一：

LV_SPAN_MODE_FIXED 固定对象大小。
LV_SPAN_MODE_EXPAND 将对象大小扩展到文本大小，但保留在一行上。
LV_SPAN_MODE_BREAK 保持宽度，打破太长的线条并自动扩展高度。

使用函数 lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK) 设置相应的对象模式。

Overflow（溢出）

显示原文

The spangroup can be set to one the following modes:

LV_SPAN_OVERFLOW_CLIP truncates the text at the limit of the area.
LV_SPAN_OVERFLOW_ELLIPSIS will display an ellipsis (...) when text overflows the area.

Use function lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP) to set object overflow mode.

spangroup 可以设置为以下模式之一，应对文本溢出：

LV_SPAN_OVERFLOW_CLIP 在区域的边界处截断文本。
LV_SPAN_OVERFLOW_ELLIPSIS 当文本溢出该区域时将显示省略号 (...)。

使用函数 lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP) 设置相应的溢出模式。

First line indent（首行缩进）

显示原文

Use function lv_spangroup_set_indent(spangroup, 20) to set the indent of the first line. all modes support pixel units, in addition to LV_SPAN_MODE_FIXED and LV_SPAN_MODE_BREAK mode supports percentage units too.

使用函数 lv_spangroup_set_indent(spangroup, 20) 设置第一行的缩进（像素为单位）。所有模式都支持像素单位，此外， LV_SPAN_MODE_FIXED 和 LV_SPAN_MODE_BREAK 模式还支持百分比单位。

Lines（行）

显示原文

Use function lv_spangroup_set_max_lines(spangroup, 10) to set the maximum number of lines to be displayed in :cpp:enumerator::LV_SPAN_MODE_BREAK mode, negative values indicate no limit.

使用函数 lv_spangroup_set_max_lines(spangroup, 10) 设置在 :cpp:enumerator::LV_SPAN_MODE_BREAK 模式下显示的最大行数，负值表示没有限制。

Events（事件）

显示原文

No special events are sent by this widget.

Learn more about Events（事件）.

此控件不会发送任何特殊事件。

详细了解更多 Events（事件）。

Keys（按键）

显示原文

No Keys are processed by the object type.

Learn more about Keys（按键）.

对象类型不处理任何按键。

了解有关 Keys（按键）的更多信息。

Example

[English]

Span with custom styles

#include "../../lv_examples.h"
#if LV_USE_SPAN && LV_BUILD_EXAMPLES

/**
 * Create span.
 */
void lv_example_span_1(void)
{
    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_border_width(&style, 1);
    lv_style_set_border_color(&style, lv_palette_main(LV_PALETTE_ORANGE));
    lv_style_set_pad_all(&style, 2);

    lv_obj_t * spans = lv_spangroup_create(lv_screen_active());
    lv_obj_set_width(spans, 300);
    lv_obj_set_height(spans, 300);
    lv_obj_center(spans);
    lv_obj_add_style(spans, &style, 0);

    lv_spangroup_set_align(spans, LV_TEXT_ALIGN_LEFT);
    lv_spangroup_set_overflow(spans, LV_SPAN_OVERFLOW_CLIP);
    lv_spangroup_set_indent(spans, 20);
    lv_spangroup_set_mode(spans, LV_SPAN_MODE_BREAK);

    lv_span_t * span = lv_spangroup_new_span(spans);
    lv_span_set_text(span, "China is a beautiful country.");
    lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED));
    lv_style_set_text_decor(&span->style, LV_TEXT_DECOR_UNDERLINE);
    lv_style_set_text_opa(&span->style, LV_OPA_50);

    span = lv_spangroup_new_span(spans);
    lv_span_set_text_static(span, "good good study, day day up.");
#if LV_FONT_MONTSERRAT_24
    lv_style_set_text_font(&span->style,  &lv_font_montserrat_24);
#endif
    lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_GREEN));

    span = lv_spangroup_new_span(spans);
    lv_span_set_text_static(span, "LVGL is an open-source graphics library.");
    lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_BLUE));

    span = lv_spangroup_new_span(spans);
    lv_span_set_text_static(span, "the boy no name.");
    lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_GREEN));
#if LV_FONT_MONTSERRAT_20
    lv_style_set_text_font(&span->style, &lv_font_montserrat_20);
#endif
    lv_style_set_text_decor(&span->style, LV_TEXT_DECOR_UNDERLINE);

    span = lv_spangroup_new_span(spans);
    lv_span_set_text(span, "I have a dream that hope to come true.");
    lv_style_set_text_decor(&span->style, LV_TEXT_DECOR_STRIKETHROUGH);

    lv_spangroup_refr_mode(spans);
}

#endif

API

lv_span.h