# UIRichText Rich Text Component

# Overview

UIRichText inherits UILabel, which can realize the ability to style, mix graphics and text, hyperlink, and bind external nodes.

# Label format

Rich text format is similar to XML. Nodes are opened in <tag> format, and nodes are closed with </tag>. In the component, most of the nodes can be closed automatically, and only a few of them need to be handwritten to close the label.

The node attribute is written as key=value without quotation marks; different attributes are separated by a vertical bar, such as <tag|key1=value1|key2=value2>.

# Style

Style sheet support attributes:

# Set the global style sheet

Similar to CSS, you can set the key-value style sheet before instantiating UIRichText. All UIRichtext share the same global style sheet.

// style sheet
const style = {
  s1: {font: "SimSun", size: 18, color: "#FF0000" },
  s2: ...
};
// Write the style sheet through the style static attribute overwrite
engine.UIRichText.style = style;
// Or use the setStyle() static method to incrementally write the style sheet
engine.UIRichText.setStyle(style);

# Set the instance style sheet

Similar to CSS, after instantiating UIRichText, you can set the key-value style sheet first. The instance UIRichtext uses a separate style sheet, which cascades global styles.

// style sheet
const style = {
  s1: {font: "Arial", size: 20, color: "#FF0000" },
  s2: ...
};
// Write the rich text instance to the local style
richtextComp.style = style;

# Style tags

Set the style. It is best to use </style> to close the label manually, otherwise the component will automatically determine the closing timing, which may produce unexpected effects.

# Use style sheets

<style|value=style name>text</style>

# Use attributes directly

<style||applyGradient=true|gradientTop=#00ff00|gradientBottom=#ff44ff>Colored text</style>

# Layout label

# Align label

<align|horz=right|vert=top>right alignment</align>

Alignment. Need to use </align> to manually close the label.

• align tags cannot be nested.

Under the same layout, Adjacent algins with the same horz in the horizontal direction will be merged into the whole; adjacent aligns with different horz in the horizontal direction will be line-wrapped first, and then the alignment operation will be performed. The vertical alignment of align is vert, which controls the vertical alignment rules of the sub-elements inside align.

# Line spacing multiple linespace

<linespace|value=0.5>

Set the line spacing multiple to the current node. Determine the line spacing inside the current layout.

Attributes:

• value: multiple, the default is 0.

# Newline label

<br|value=0>

Take the initiative to wrap. If you do not bring br, then when the content exceeds the width of the container, it will automatically wrap.

Attributes:

• value: line break distance, extra distance beyond the line break distance of the line itself.

# Hyperlinks

<link｜id=1|style=s2|text=hyperlink|data=someData>hyperlink</link>

Hyperlink element. You need to use </link> to manually close the label, add an externally set click callback to all the elements inside the label, and add a script component with a specific function to the click callback.

export default class RichTextlLink extends engine.Script {
  public onClickRichTextLink(obj: {id: number, data: string}) {
    console.log(obj.id, obj.data);
  }
}

Attributes:

• id: The mark distinguished when the callback is triggered
• style: the name of the style.
• text: text content.
• data: data available after clicking, string format.

# Rendering tags

# Normal text

Hello World

Just use the text directly.

# picture

<img|texture=path/to/texture2d|size=15,20> <img|spriteframe=path/to/spriteframe|size=15,20>

For static pictures, if size is not specified, the default size of the picture will be used.

Attributes:

• texture: The path of the resource Texture2D. Mutually exclusive with the spriteframe attribute.
• spriteframe: The path of the resource SpriteFrame. Mutually exclusive with the texture property.
• size: picture width and height, format width, height.

# Binding external nodes

The <node> tag is used as a layout area. The label is set to the default width and height, and an id is set. The script can be used to bind the id and the external node to synchronize the information of the external node and the layout area. .

<node|id=1|size=96,128>Follow-up text

this._richText.bindNodeWithTransform(1, this._renderSpriteTransform);

The external node must be the first-level child node of the rich text, and the case is a picture frame animation node. After playing, you can dynamically modify the rich text layout to view, and the external nodes are directly synchronized with the rich text layout.

# Instructions

# Code usage

UIRichText is a rendering component, so it needs to be mounted on a non-rendering node.

const xmlText = "<style|value=s1>Text</style>"
const richTextComp = entity.addComponent<UIRichText>(engine.UIRichText);
richTextComp.text = xmlText;
// ...

# Get the actual width and height

Get the size of the layout element, get will trigger the operation and update in the current rich text state.

interface Metrics {
  width: number;
  height: number;
  innerWidth: number;
  innerHeight: number;
  outerWidth: number;
  outerHeight: number;
  rowsNumber: number;
  layoutWidth?: number;
  layouHeight?: number;
}

const metrics = richText.metrics as Metrics;

# Editor use

Right click-UI-New RichText

# Use Cases

Use various rendering elements