RichText component
The RichText component is a rich text control. It is actually assembled from multiple Label nodes. It is used to display a piece of text with different style effects. The style of the text is set through the BBCode tag.
Currently supported styles are: color (color), font size (size), font stroke (outline), bold (b), italic (i), underline (u), line break (br), image (img) and click event(on).
1. RichText attribute
| Attributes | Function Description |
|---|---|
| String | Rich text content string, where you can use BBCode to specify the style of specific text |
| Horizontal Align | horizontal alignment |
| Vertical Align | vertical alignment |
| Font Size | Font size, unit is point ( note : this field will not affect the font size set in BBCode) |
| Font | Rich text custom font, all label fragments will use this customized TTF font |
| Font Family | Rich text custom system fonts |
| Use System Font | Whether to use system fonts |
| Max Width | The maximum width of rich text. Passing 0 means that you must manually wrap the line. |
| Line Height | Font line height, unit is point |
| Image Atlas | For the src attribute name in the img tag, you need to find a valid spriteFrame in imageAtlas, otherwise the img tag will be judged as invalid. |
| Handle Touch Event | When this option is checked, RichText will block all input events (mouse and touch) within the node's bounding box, preventing input events from penetrating to the underlying node |
2. BBCode tag format
(1), basic format
Currently supported tag types are: size, color, b, i, u, img and on, which are used to customize font size, font color, bold, italics, underline, pictures and click events respectively.
Each tag has a start tag and an end tag. The name and attribute format of the start tag must meet the requirements and must be all lowercase.
The name of the end tag is not checked in any way, it only needs to meet the definition of the end tag.
Note : All tag names must be in lowercase, and attribute values are assigned using the = sign, as follows:
<color=green>test</color>，<size=50>test1</>
(2) Tags supported by BBCode
| name | describe | Example | Precautions |
|---|---|---|---|
| color | Specify the font rendering color. The color value can be a built-in color, such as white, black, etc., or you can use a hexadecimal color value, such as #ff0000red. |
<color=#ff0000>Red Text</color> |
|
| size | Specifies the font rendering size, the size value must be an integer | <size=30>enlarge me</size> |
Size value must be assigned using the equal sign |
| outline | Set the stroke color and stroke width of text | <outline color=red width=4>A label with outline</outline> |
If you do not specify a stroke color or width, the default color is white (#ffffff) and the default width is 1 |
| b | Specifies to use bold font for rendering | <b>This text will be rendered as bold</b> |
The name must be lowercase and cannot be written as bold |
| i | Specifies to use italics for rendering | <i>This text will be rendered as italic</i> |
The name must be lowercase and cannot be written italic |
| u | Underline text | <u>This text will have a underline</u> |
The name must be lowercase and cannot be written underline |
| on | Specify a click event handler function. When the text content of the Tag is clicked, the event response function will be called. | <on click="handler"> click me! </on> |
In addition to the click attribute that can be added to the on tag, the color and size tags can also be added, such as<size=10 click="handler2">click me</size> |
| param | When the click event is triggered, you can get the value in the second parameter of the callback function. | <on click="handler" param="test"> click me! </on> |
Depends on click event |
| br | insert a blank line | <br/> |
Note : <br></br>and <br>are not supported. |
| img | To add image and text mixing function to rich text, the src attribute of img must be a valid spriteframe name in the ImageAtlas atlas. | <img src='emoji1' click='handler' /> |
Note : Only <img src='foo' click='bar' />this way of writing is valid. If you specify a large image, the sprite created by the image will be scaled proportionally, with the scaling value equal to the line height of the rich text divided by the height of the sprite. |
(3) Optional attributes of img tag
The img tag type provides optional attributes. You can use widthand heightto specify the size of the SpriteFrame, allowing the image to be larger or smaller than the row height (but this setting will not change the row height).
After changing the height or width of the SpriteFrame, you may need to use alignto adjust the alignment of the image in the row.
| Attributes | describe | Example | Precautions |
|---|---|---|---|
| height | Specify the rendering height of SpriteFrame, the size value must be an integer | <img src='foo' height=50 /> |
If you only use the height attribute, the SpriteFrame will automatically calculate the width to maintain the image proportions |
| width | Specify the rendering width of SpriteFrame. The size value must be an integer. | <img src='foo' width=50 /> |
You can use both height and width attributes at the same time<img src='foo' width=20 height=30 /> |
| align | Specifies the alignment of the SpriteFrame in the line. The value must be bottom, toporcenter |
<img src='foo' align=center /> |
The default alignment is bottom |
In order to support customized image layout, properties are also provided offsetto fine-tune the position of SpriteFrame in RichText.
When setting, offsetplease note that the attribute value must be an integer.
| offset property | Example | describe | Precautions |
|---|---|---|---|
| Y | <img src='foo' offset=5 /> |
Specify the y-axis of the SpriteFrame plus 5 | When offset only sets one value, it represents the offset of the y-axis |
| Y | <img src='foo' offset=-5 /> |
Specifies that the y-axis of the SpriteFrame is reduced by 5 | You can set negative integers to reduce the y-axis |
| X, Y | <img src='foo' offset=6,-5 /> |
Specify that the x-axis of the SpriteFrame is added to 6 and the y-axis is reduced to 5 | The value of the offset attribute can only contain 0-9, -and ,characters |
(4) Label nesting
标签与标签是支持嵌套的，且嵌套规则跟 HTML 是一样的。比如下面的嵌套标签设置一个文本的渲染大小为 30，且颜色为绿色。
<size=30><color=green>I'm green</color></size>
也可以实现为:
<color=green><size=30>I'm green</size></color>
（5）、文本缓存
对于复杂的富文本，底层可能有十几个 label 节点，drawcall 数量会比较高，引擎为富文本组件提供了 Label 组件的文本缓存类型设置，来适当减少 drawcall 的增加。
一般情况下，不应该在游戏的主循环里面频繁地修改富文本的文本内容，这可能会导致性能比较低。
如果能不使用富文本组件，就尽量使用普通的文本组件，推荐使用 BMFont，因为 BMFont的效率是最高的。
| 类型 | 功能说明 |
|---|---|
| NONE | 默认值，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 NONE 类型，即将每个 Label 的整段文本生成一张位图并单独进行渲染。 |
| BITMAP | 选择后，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 BITMAP 类型，即将每个 Label 的整段文本生成一张位图，并将该位图添加到动态图集中，再依据动态图集进行合并渲染。 |
| CHAR | 选择后，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 CHAR 类型，即将每个 Label 的文本以“字”为单位缓存到全局共享的位图中，相同字体样式和字号的每个字符将在全局共享一份缓存。 |
二、RichText 组件的使用
这里以添加事件为例，进行演示：
1、新建任意一个带有 RichText 组件的节点。并创建一个自定义脚本，挂载在 RichText 组件上
这里新建了一个自定义脚本TestRichText.ts。
2、将如下的代码复制到 RichText 的 String 属性内
<on click="onClicked" param="你好，这是点击事件">Click</on>
3、复制下面的代码到TestRichText.ts中：
import { _decorator, Component, EventTouch } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('TestRictText')
export class TestRictText extends Component {
start() {
}
update(deltaTime: number) {
}
onClicked(eventTouch:EventTouch, param:string){
console.log("onClicked", param);
}
}
4、编译运行
使用鼠标点击Click文本，可以查看到控制台的输出：
