# UIRichText 富文本组件

# 概述

UIRichText 继承 UILabel，可实现样式，图文混排，超链接，绑定外部节点等能力。

# 标签格式

富文本格式类似于 XML，以 <tag> 格式开启节点，以 </tag> 闭合节点。在组件中，大部分节点可自动闭合，只有少部分需要手写闭合标签。

节点属性写法为 key=value，不需要带引号；不同属性之间以 | 竖线分隔，如 <tag|key1=value1|key2=value2>。

# 目录

• 样式
• 对齐标签
• 渲染标签
• 超链接
• 绑定外部节点
• 使用方法

# 样式

样式表支持属性：

# 设置全局样式表

类似 CSS，实例化 UIRichText 前，可先设置 key-value 样式表。所有UIRichtext共享同一份全局样式表。

// 样式表
const style = {
  s1: { font: "SimSun", size: 18, color: "#FF0000" },
  s2: ...
};
// 通过 style 静态属性覆盖式写入样式表
engine.UIRichText.style = style;
// 或者通过 setStyle() 静态方法增量式写入样式表
engine.UIRichText.setStyle(style);

# 设置实例样式表

类似 CSS，实例化 UIRichText 后，可先设置 key-value 样式表。实例 UIRichtext 使用独立的样式表，会层叠全局样式。

// 样式表
const style = {
  s1: { font: "Arial", size: 20, color: "#FF0000" },
  s2: ...
};
// 富文本实例写入本地样式
richtextComp.style = style;

# 样式标签

设置样式。最好用 </style> 手动闭合标签，否则组件将自动判断闭合时机，可能产生预期之外的效果。

# 使用样式表

<style|value=样式名>文本</style>

# 直接使用属性

<style||applyGradient=true|gradientTop=#00ff00|gradientBottom=#ff44ff>彩色文本</style>

# 布局标签

# 对齐标签

<align|horz=right|vert=top>右对齐</align>

对齐方式。需要用 </align> 手动闭合标签。

• align标签不能嵌套。

同一layout下， 水平方向 horz一致 的相邻algin会合并为整体；水平方向horz不同的相邻align会先进行换行，再进行对齐操作。 align的垂直方向对齐 vert，控制align内部，子元素垂直方向的对齐规则。

# 行间距倍数 linespace

<linespace|value=0.5>

设置行间距倍数到当前节点。决定当前layout内部的行间距。

属性：

• value：倍数，默认为 0。

# 换行标签

<br|value=0>

主动换行。如果不带 br，那么当内容超出容器宽度时，也会自动换行。

属性：

• value：换行距离，在行本身的换行的距离以外，额外的距离。

# 超链接

<link｜id=1|style=s2|text=超链接|data=someData>超链接</link>

超链接元素。需要用 </link> 手动闭合标签，标签内部的所有元素添加一个外部设定的点击回调，点击回调需添加带有特定函数的脚本组件出发

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

属性：

• id: 回调触发时区分的标记
• style：样式名。
• text：文本内容。
• data：点击后可获得的数据，字符串格式。

# 渲染标签

# 普通文本

Hello World

直接使用文字即可。

# 图片

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

静态图片，若未指定size，则使用图片默认大小。

属性：

• texture：资源 Texture2D 的路径。与 spriteframe 属性互斥。
• spriteframe：资源 SpriteFrame 的路径。与 texture 属性互斥。
• size：图片宽高，格式 width,height。

# 绑定外部节点

<node> 标签，用作一个布局占位区域，标签设置了默认的宽高用作，并设置一个id，可使用脚本绑定id与外部节点，同步外部节点与布局占位区域的信息。

<node|id=1|size=96,128>后续文本

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

外部节点必须为富文本一级子节点，案例为一个图片帧动画节点。 播放后，可以动态修改富文本布局查看，外部节点与富文本直接的布局同步。

# 使用方法

# 代码使用

UIRichText 是渲染组件，因此需要挂载到非渲染节点上。

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

# 获取实际宽高

获取布局元素的大小，获取会触发当前富文本状态下的运算和更新。

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;

# 编辑器使用

右键 - UI - 新建RichText

# 使用案例

使用各类渲染元素