目录

Using the Text Component

The ArkUI development framework provides the Text component in the NDK APIs to display the text content. The Text component supports various style settings, including the font, color, alignment mode, and text effect. It also supports multiple child components, such as Span, ImageSpan, and StyledString, to implement complex text display effects.

Creating the Text Component

The Text component is a basic component for displaying text content. It supports multiple style settings and child components.

[h2]Creating Basic Text

The createNode API creates the Text component. The node type is ARKUI_NODE_TEXT.

ArkUI_NodeHandle text = Manager::nodeAPI_->createNode(ARKUI_NODE_TEXT);
ArkUI_NumberValue textWidth[] = {{.f32 = VALUE_300}};
ArkUI_AttributeItem textWidthItem = {.value = textWidth, .size = VALUE_1};
Manager::nodeAPI_->setAttribute(text, NODE_WIDTH, &textWidthItem);
ArkUI_NumberValue textHeight[] = {{.f32 = VALUE_30}};
ArkUI_AttributeItem textHeightItem = {.value = textHeight, .size = VALUE_1};
Manager::nodeAPI_->setAttribute(text, NODE_HEIGHT, &textHeightItem);

[h2]Setting the Text Content

Setting the Text Style

The Text component supports various style settings, including the font, color, and alignment mode.

[h2]Setting Font Attributes

Set basic attributes such as font size, weight, and style through the following attributes.

Table 1 Font attributes

Attribute Description
NODE_FONT_SIZE Sets the font size.
NODE_FONT_WEIGHT Sets the font weight.
NODE_FONT_STYLE Sets the font style.
NODE_FONT_FAMILY Sets the font families. 
// Set the font size to 28 and text color to 0xFFFF0000 (red).
ArkUI_NumberValue fontSize[] = {{.f32 = VALUE_28}};
ArkUI_AttributeItem fontSizeItem = {.value = fontSize, .size = VALUE_1};
Manager::nodeAPI_->setAttribute(text2, NODE_FONT_SIZE, &fontSizeItem);
ArkUI_NumberValue fontColor = {.u32 = 0xFFFF0000};
ArkUI_AttributeItem fontColorItem = {.value = &fontColor, .size = VALUE_1};
Manager::nodeAPI_->setAttribute(text2, NODE_FONT_COLOR, &fontColorItem);

// Set the font style to italic (ARKUI_FONT_STYLE_ITALIC).
ArkUI_NumberValue fontStyleVal = {.i32 = ARKUI_FONT_STYLE_ITALIC};
ArkUI_AttributeItem fontStyleItem = {&fontStyleVal, VALUE_1};
Manager::nodeAPI_->setAttribute(text2, NODE_FONT_STYLE, &fontStyleItem);

// Set the font weight to bold (ARKUI_FONT_WEIGHT_W800).
ArkUI_NumberValue fontWeightVal = {.i32 = ARKUI_FONT_WEIGHT_W800};
ArkUI_AttributeItem textWeightItem = {.value = &fontWeightVal, .size = 1};
Manager::nodeAPI_->setAttribute(text2, NODE_FONT_WEIGHT, &textWeightItem);

[h2]Setting Text Alignment

Set the horizontal and vertical alignment of the text through the following attributes.

Table 2 Text alignment attributes

Attribute Description
NODE_TEXT_ALIGN Sets the horizontal text alignment.
NODE_TEXT_VERTICAL_ALIGN Sets the vertical text alignment.

[h2]Setting the Text Decoration and Effect

Set effects such as text decoration lines and shadows through the following attributes.

Table 3 Text decoration and effect attributes

Attribute Description
NODE_TEXT_DECORATION Sets the text decoration line.
NODE_TEXT_TEXT_SHADOW Sets the text shadow effect.

Setting the Text Layout

The Text component supports various text layout settings, including line wrapping, line height, and ellipsis.

[h2]Setting Text Line Wrapping

Set the line break rule of the text through the NODE_TEXT_WORD_BREAK attribute.

// Set the line break rule to allowing word breaks between any two characters.
ArkUI_NumberValue wordBreakVal = {.i32 = ARKUI_WORD_BREAK_BREAK_ALL};
ArkUI_AttributeItem wordBreakItem = {&wordBreakVal, VALUE_1};
Manager::nodeAPI_->setAttribute(text3, NODE_TEXT_WORD_BREAK, &wordBreakItem);

[h2]Setting Line Height Attributes

Set attributes such as line height and line height multiplier through the following attributes.

Since API version 22, the Text component supports setting the line height using a multiplier.

Table 4 Line height attributes

Attribute Description
NODE_TEXT_LINE_HEIGHT Sets the line height.
NODE_TEXT_LINE_HEIGHT_MULTIPLE Sets the line height multiple. Supported since API version 22.
NODE_TEXT_HALF_LEADING Sets the text to be vertically centered.

[h2]Setting Text Ellipsis

Set the ellipsis mode for text overflow through the following attributes.

Table 5 Text ellipsis attributes

Attribute Description
NODE_TEXT_MAX_LINES Sets the maximum number of lines.
NODE_TEXT_OVERFLOW Sets the text overflow mode.
NODE_TEXT_ELLIPSIS_MODE Sets the ellipsis mode. 
// Set the maximum number of lines.
ArkUI_NumberValue maxLinesValue[] = {{.i32 = VALUE_3} };
ArkUI_AttributeItem maxLinesItem = {maxLinesValue, VALUE_1};
Manager::nodeAPI_->setAttribute(text20, NODE_TEXT_MAX_LINES, &maxLinesItem);

// Set the text overflow handling method to ellipsis.
ArkUI_NumberValue textOverFlowValue[] = { {.i32 = ARKUI_TEXT_OVERFLOW_ELLIPSIS} };
ArkUI_AttributeItem textOverFlowItem = {textOverFlowValue, VALUE_1};
Manager::nodeAPI_->setAttribute(text20, NODE_TEXT_OVERFLOW, &textOverFlowItem);

// Set the ellipsis style to an ellipsis at the start of the line of text.
ArkUI_NumberValue ellipsisModeValue1[] = { {.i32 = ARKUI_ELLIPSIS_MODE_MULTILINE_START} };
ArkUI_AttributeItem ellipsisModeItem1 = {ellipsisModeValue1, VALUE_1};
Manager::nodeAPI_->setAttribute(text20, NODE_TEXT_ELLIPSIS_MODE, &ellipsisModeItem1);

[h2]Setting Trailing Space Optimization at the End of Each Line

Set whether to optimize trailing spaces at the end of each line through the following attributes. Since API version 20, the Text component supports setting whether to optimize trailing spaces at the end of each line.

Table 6 Trailing space handling attributes for each line

Attribute Description
NODE_TEXT_OPTIMIZE_TRAILING_SPACE Whether to optimize trailing spaces at the end of each line. Supported since API version 20. 
ArkUI_NumberValue optimizeValue = {.i32 = true};
ArkUI_AttributeItem optimizeTrailingSpaceItem = {&optimizeValue, VALUE_1};
Manager::nodeAPI_->setAttribute(text14, NODE_TEXT_OPTIMIZE_TRAILING_SPACE, &optimizeTrailingSpaceItem);

[h2]Setting the First Line Indent and Punctuation Compression

Set the first line indent and line start punctuation compression through the following attributes. Since API version 23, the Text component supports setting line start punctuation compression.

Table 7 First line indent and punctuation compression attributes

Attribute Description
NODE_TEXT_INDENT Sets the first-line indent.
NODE_TEXT_COMPRESS_LEADING_PUNCTUATION Sets the line-start punctuation compression. Supported since API version 23.

[h2]Setting the Trailing Indent

Set the trailing indent of the text through the following attributes. Since API version 26.0.0, the Text component supports setting the trailing indent of the text.

Table 8 Trailing indent attributes

Name Description
NODE_TEXT_TAIL_INDENTS Sets the trailing indent of the text. 
ArkUI_NumberValue multiValues[] = { { .f32 = 0.0f }, { .f32 = 50.0f }, { .f32 = 100.0f } };
ArkUI_AttributeItem tailIndentItem2 = { .value = multiValues, .size = 3 };
Manager::nodeAPI_->setAttribute(text2, NODE_TEXT_TAIL_INDENTS, &tailIndentItem2);

Adding Child Components

The Text component supports multiple child components to implement complex effects such as the mixed text and image layout.

[h2]Adding Span

The addChild API adds a text child component to Text to display inline text. A Span component is only visible when embedded within a Text component. Using a Span independently displays no content.

// Display Span only as a child component of Text.
ArkUI_NodeHandle span = Manager::nodeAPI_->createNode(ARKUI_NODE_SPAN);
const char *spanContent = "This is a span";
ArkUI_AttributeItem spanContentItem = {.string = spanContent};
Manager::nodeAPI_->setAttribute(span, NODE_SPAN_CONTENT, &spanContentItem);
if (span != nullptr) {
    // Set the background style of Span.
    ArkUI_NumberValue spanBackground[] = {
        {.u32 = 0xFFE8F4F5}, // Set the background color.
        {.f32 = 5.0f},       // Set the radius of the upper left corner.
        {.f32 = 5.0f},       // Set the radius of the upper right corner.
        {.f32 = 5.0f},       // Set the radius of the lower left corner.
        {.f32 = 5.0f}        // Set the radius of the lower right corner.
    };
    ArkUI_AttributeItem spanBackgroundItem = {.value = spanBackground, .size = VALUE_5};
    Manager::nodeAPI_->setAttribute(span, NODE_SPAN_TEXT_BACKGROUND_STYLE, &spanBackgroundItem);

    // Set the text baseline offset attribute.
    ArkUI_NumberValue baselineOffsetVal = {.f32 = VALUE_10};
    ArkUI_AttributeItem baselineOffsetItem = {&baselineOffsetVal, VALUE_1};
    Manager::nodeAPI_->setAttribute(span, NODE_SPAN_BASELINE_OFFSET, &baselineOffsetItem);
    // Set the font weight.
    ArkUI_NumberValue fontWeight = {.i32 = ARKUI_FONT_WEIGHT_W500};
    ArkUI_AttributeItem fontWeightItem = {&fontWeight, VALUE_1};
    Manager::nodeAPI_->setAttribute(span, NODE_IMMUTABLE_FONT_WEIGHT, &fontWeightItem);
    ArkUI_NumberValue fontWeight1 = {.i32 = ARKUI_FONT_WEIGHT_W500};
    ArkUI_AttributeItem fontWeight1Item = {&fontWeight1, VALUE_1};
    Manager::nodeAPI_->setAttribute(text, NODE_IMMUTABLE_FONT_WEIGHT, &fontWeight1Item);
    // Long press on the Span component to trigger the callback.
    Manager::nodeAPI_->registerNodeEvent(span, NODE_TEXT_SPAN_ON_LONG_PRESS, EVENT_SPAN_LONG_PRESS, nullptr);
    Manager::nodeAPI_->registerNodeEventReceiver(&OnEventReceive);
}
Manager::nodeAPI_->addChild(text, span);

[h2]Adding ImageSpan

The addChild API adds an image child component to Text.

void setText6(ArkUI_NodeHandle &text6)
{
    // ImageSpan
    ArkUI_NodeHandle imageSpan = Manager::nodeAPI_->createNode(ARKUI_NODE_IMAGE_SPAN);
    ArkUI_AttributeItem spanUrl = {.string = "/resources/base/media/background.png"};
    ArkUI_NumberValue widthVal[VALUE_1]{};
    widthVal[VALUE_0].f32 = 100.f;
    ArkUI_AttributeItem width = {.value = widthVal, .size = VALUE_1};
    ArkUI_NumberValue heightVal[VALUE_1]{};
    heightVal[VALUE_0].f32 = 100.f;
    ArkUI_AttributeItem height = {.value = heightVal, .size = VALUE_1};
    Manager::nodeAPI_->setAttribute(imageSpan, NODE_WIDTH, &width);
    Manager::nodeAPI_->setAttribute(imageSpan, NODE_HEIGHT, &height);
    Manager::nodeAPI_->setAttribute(imageSpan, NODE_IMAGE_SPAN_SRC, &spanUrl);
    // Set NODE_IMAGE_SPAN_VERTICAL_ALIGNMENT.
    ArkUI_NumberValue verticalAlignment = {.i32 = ARKUI_IMAGE_SPAN_ALIGNMENT_BOTTOM};
    ArkUI_AttributeItem verticalAlignmentItem = {&verticalAlignment, VALUE_1};
    Manager::nodeAPI_->setAttribute(imageSpan, NODE_IMAGE_SPAN_VERTICAL_ALIGNMENT, &verticalAlignmentItem);
    // Set the placeholder image attribute of the ImageSpan component.
    ArkUI_AttributeItem spanAlt = {.string = "/resources/base/media/startIcon.png"};
    Manager::nodeAPI_->setAttribute(imageSpan, NODE_IMAGE_SPAN_ALT, &spanAlt);
    // Set the baseline offset attribute of the ImageSpan component.
    ArkUI_NumberValue baselineOffset = {.f32 = VALUE_10};
    ArkUI_AttributeItem baselineOffsetItem = {&baselineOffset, VALUE_1};
    Manager::nodeAPI_->setAttribute(imageSpan, NODE_IMAGE_SPAN_BASELINE_OFFSET, &baselineOffsetItem);
    Manager::nodeAPI_->addChild(text6, imageSpan);
}

Setting Advanced Text Effects

The Text component supports various advanced text effects, such as gradient and marquee.

[h2]Setting the Gradient Effect

Set the gradient color effect through the following attributes. Since API version 20, the Text component supports setting the gradient color effect.

Table 9 Gradient effect attributes

Attribute Description
NODE_TEXT_LINEAR_GRADIENT Sets linear gradient. Supported since API version 20.
NODE_TEXT_RADIAL_GRADIENT Sets radial gradient. Supported since API version 20. 
// Set the color and position of a gradient stop.
float stops[] = { 0.0f, 0.5f };
uint32_t colors[] = { 0xFFFFFF00, 0xFF0000FF };
ArkUI_ColorStop colorStop = { colors, stops, VALUE_2 };
ArkUI_ColorStop *colorStopPtr = &colorStop;

// Set the linear gradient.
ArkUI_NumberValue linearGradient[] = {
    {.f32 = FLOAT_50}, {.f32 = FLOAT_50}, {.f32 = FLOAT_50}};
ArkUI_AttributeItem linearGradientItem = {
    linearGradient, sizeof(linearGradient) / sizeof(ArkUI_NumberValue)};
linearGradientItem.object = reinterpret_cast<void *>(colorStopPtr);
Manager::nodeAPI_->setAttribute(text5, NODE_TEXT_LINEAR_GRADIENT, &linearGradientItem);

[h2]Setting the Marquee Effect

Since API version 23, the Text component supports setting the marquee effect through the NODE_TEXT_MARQUEE_OPTIONS attribute.

// Create a marquee option.
ArkUI_TextMarqueeOptions* marqueeOptions = OH_ArkUI_TextMarqueeOptions_Create();
OH_ArkUI_TextMarqueeOptions_SetStart(marqueeOptions, true);
OH_ArkUI_TextMarqueeOptions_SetStep(marqueeOptions, 5.0f);
OH_ArkUI_TextMarqueeOptions_SetSpacing(marqueeOptions, 30.0f);
OH_ArkUI_TextMarqueeOptions_SetFromStart(marqueeOptions, true);
OH_ArkUI_TextMarqueeOptions_SetDelay(marqueeOptions, VALUE_400);
OH_ArkUI_TextMarqueeOptions_SetUpdatePolicy(marqueeOptions,
    ArkUI_MarqueeUpdatePolicy::ARKUI_MARQUEEUPDATEPOLICY_PRESERVEPOSITION);
// Apply the effect to the Text component.
ArkUI_AttributeItem marqueeOptions_item = {
    .object = marqueeOptions
};
Manager::nodeAPI_->setAttribute(text18, NODE_TEXT_MARQUEE_OPTIONS, &marqueeOptions_item);
OH_ArkUI_TextMarqueeOptions_Dispose(marqueeOptions);

[h2]Setting the Text Direction

Since API version 23, the Text component supports setting the text direction through the NODE_TEXT_DIRECTION attribute.

// Set the text direction to right-to-left.
ArkUI_NumberValue directionValue[] = {{.i32 = ARKUI_TEXT_DIRECTION_RTL}};
ArkUI_AttributeItem direction_item = {directionValue, sizeof(directionValue) / sizeof(ArkUI_NumberValue)};
Manager::nodeAPI_->setAttribute(text19, NODE_TEXT_DIRECTION, &direction_item);