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.

NOTE

This section demonstrates core API usage only. For the complete sample project, see native_node_sample.

Before development of form components, you need to access the ArkTS pages. For details, see Integrating with ArkTS Pages.

Creating the Text Component

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

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);

Setting the Text Content

The NODE_TEXT_CONTENT API sets the basic text content of the Text component.

const char *textContent = "this is text 2 this is text 2 this is text 2!!!! ";
ArkUI_AttributeItem contentItem = {.string = textContent};
Manager::nodeAPI_->setAttribute(text2, NODE_TEXT_CONTENT, &contentItem);

Setting the Text Style

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

Setting Font Attributes

Sets basic attributes such as the font size, weight, and style. For details, see the enumerated values in ArkUI_NodeAttributeType.

Table 1 Font attributes

Attribute	Description
NODE_FONT_SIZE	Font size.
NODE_FONT_WEIGHT	Font weight.
NODE_FONT_STYLE	Font style.
NODE_FONT_FAMILY	Font list.

// 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);

Setting Text Alignment

Sets the horizontal and vertical alignment modes of the text. For details, see the enumerated values in ArkUI_NodeAttributeType.

Table 2 Text alignment attributes

Attribute	Description
NODE_TEXT_ALIGN	Horizontal alignment of the text.
NODE_TEXT_VERTICAL_ALIGN	Vertical alignment of the text.

Set horizontal alignment of the text.

// Set horizontal alignment to center alignment (ARKUI_TEXT_ALIGNMENT_CENTER).
ArkUI_NumberValue intVal_0 = {.i32 = ARKUI_TEXT_ALIGNMENT_CENTER};
ArkUI_AttributeItem textAlignItem = {&intVal_0, VALUE_1};
Manager::nodeAPI_->setAttribute(text14, NODE_TEXT_ALIGN, &textAlignItem);

Set vertical alignment of the text.

// Set vertical alignment to baseline-based alignment (ARKUI_TEXT_VERTICAL_ALIGNMENT_BASELINE).
ArkUI_NumberValue vAlignVal = {.i32 = ARKUI_TEXT_VERTICAL_ALIGNMENT_BASELINE};
ArkUI_AttributeItem vAlignItem = {&vAlignVal, VALUE_1};
Manager::nodeAPI_->setAttribute(text3, NODE_TEXT_VERTICAL_ALIGN, &vAlignItem);

Setting the Text Decoration and Effect

Sets the text decoration and shadow effect. For details, see the enumerated values in ArkUI_NodeAttributeType.

Table 3 Text decoration and effect attributes

Attribute	Description
NODE_TEXT_DECORATION	Text decoration.
NODE_TEXT_TEXT_SHADOW	Text shadow.

Set the text decoration.

// Set the text decoration type to underline (ARKUI_TEXT_DECORATION_TYPE_UNDERLINE) and the text decoration style to single solid line (ARKUI_TEXT_DECORATION_STYLE_SOLID).
ArkUI_NumberValue textDecoration[] = {
    {.i32 = ARKUI_TEXT_DECORATION_TYPE_UNDERLINE}, {.u32 = 0xFFFF0000}, {.i32 = ARKUI_TEXT_DECORATION_STYLE_SOLID}};
ArkUI_AttributeItem textDecorationItem = {.value = textDecoration, .size = VALUE_3};
Manager::nodeAPI_->setAttribute(text3, NODE_TEXT_DECORATION, &textDecorationItem);

Text shadow.

// Set the text shadow attribute.
ArkUI_NumberValue textShadow[] = {
    {.f32 = VALUE_5}, {.i32 = ARKUI_SHADOW_TYPE_BLUR}, {.u32 = 0xFF0000FF}, {.f32 = VALUE_5}, {.f32 = VALUE_5}};
ArkUI_AttributeItem textShadowItem = {textShadow, VALUE_5};
Manager::nodeAPI_->setAttribute(text4, NODE_TEXT_TEXT_SHADOW, &textShadowItem);

Setting the Text Layout

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

Setting Text Line Wrapping

The NODE_TEXT_WORD_BREAK API sets the line break rule of the text.

// 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);

Setting Line Height Attributes

Sets the line height and line height multiplier of the text. For details, see the enumerated values in ArkUI_NodeAttributeType.

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

Table 5 Line height attributes

Attribute	Description
NODE_TEXT_LINE_HEIGHT	Line height.
NODE_TEXT_LINE_HEIGHT_MULTIPLE	Line height multiplier. This attribute is supported since API version 22.
NODE_TEXT_HALF_LEADING	Vertically centered text.

Set the line height.

// Set the text line height.
ArkUI_NumberValue lineHeight = {.f32 = VALUE_50};
ArkUI_AttributeItem lineHeightItem = {&lineHeight, VALUE_1};
Manager::nodeAPI_->setAttribute(text4, NODE_TEXT_LINE_HEIGHT, &lineHeightItem);

Line height multiplier.

// Set the line height multiplier.
ArkUI_NumberValue value[] = {{.f32 = 2.0}};
ArkUI_AttributeItem item = {value, sizeof(value)/ sizeof(ArkUI_NumberValue)};
Manager::nodeAPI_->setAttribute(text9, NODE_TEXT_LINE_HEIGHT_MULTIPLE, &item);

Setting Text Ellipsis

Sets the ellipsis style upon text overflow. For details, see the enumerated values in ArkUI_NodeAttributeType.

Table 6 Text ellipsis attributes

Attribute	Description
NODE_TEXT_MAX_LINES	Maximum number of lines.
NODE_TEXT_OVERFLOW	Text overflow mode.
NODE_TEXT_ELLIPSIS_MODE	Ellipsis style.

// 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);

Setting Trailing Space Optimization at the End of Each Line

Sets whether to optimize trailing spaces at the end of each line. Since API version 20, the Text component supports setting trailing space optimization at the end of each line. For details, see the enumerated values in ArkUI_NodeAttributeType.

Table 8 Trailing space handling at the end of each line

Attribute	Description
NODE_TEXT_OPTIMIZE_TRAILING_SPACE	Whether to optimize trailing spaces at the end of each line. This attribute is 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);

Setting the First Line Indent and Punctuation Compression

Sets the first line indent and leading punctuation compression. Since API version 23, the Text component supports setting first line indent and leading punctuation compression. For details, see the enumerated values in ArkUI_NodeAttributeType.

Table 7 First line indent and punctuation compression attributes

Attribute	Description
NODE_TEXT_INDENT	First line indent.
NODE_TEXT_COMPRESS_LEADING_PUNCTUATION	Leading punctuation compression. This attribute is supported since API version 23.

First line indent.

// Set the first line indent.
ArkUI_NumberValue indentVal = {.f32 = VALUE_30};
ArkUI_AttributeItem indentItem = {&indentVal, VALUE_1};
Manager::nodeAPI_->setAttribute(text3, NODE_TEXT_INDENT, &indentItem);

Leading punctuation compression.

// Set leading punctuation compression.
ArkUI_NumberValue value0[] = {{.i32 = true}};
ArkUI_AttributeItem item0 = {value0, sizeof(value0)/ sizeof(ArkUI_NumberValue)};
Manager::nodeAPI_->setAttribute(text11, NODE_TEXT_COMPRESS_LEADING_PUNCTUATION, &item0);

Adding Child Components

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

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(text, 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);

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);
}

Using StyledString

StyledString provides advanced text layout functions and allows you to set different styles for different parts of the text, including the font size, color, and placeholder. For details about StyledString, see Drawing and Displaying Text in Text Components.

Setting Advanced Text Effects

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

Setting the Gradient Effect

Sets the gradient color effect. Since API version 20, the Text component supports setting the color gradient effect. For details, see the enumerated values in ArkUI_NodeAttributeType.

Table 9 Gradient effect attributes

Attribute	Description
NODE_TEXT_LINEAR_GRADIENT	Linear gradient. This attribute is supported since API version 20.
NODE_TEXT_RADIAL_GRADIENT	Radial gradient. This attribute is 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);
linearGradientItem.size = sizeof(linearGradientItem) / sizeof(ArkUI_NumberValue);
Manager::nodeAPI_->setAttribute(text5, NODE_TEXT_LINEAR_GRADIENT, &linearGradientItem);

Setting the Marquee Effect

Since API version 23, the Text component supports setting the marquee effect through NODE_TEXT_MARQUEE_OPTIONS. For details, see the enumerated values in ArkUI_NodeAttributeType.

// 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);

Setting the Text Direction

Since API version 23, the Text component supports setting the text direction through NODE_TEXT_DIRECTION. For details, see the enumerated values in ArkUI_NodeAttributeType.

// 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);