# UIRichText 富文本组件

# 概述

UIRichText 可实现图文混排等复杂的排版能力。

# 目录

• 使用流程
• 富文本格式
• 其他

# 使用流程

# 1. 设置全局样式表

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

样式表支持属性：

# 2. 实例赋值

实例化 UIRichText 并挂载到 entity 后，将指定格式的文本赋予 text 属性即可。

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

其中，xmlText 是一种类似 XML 结构的文本。格式见下文。

# 富文本格式

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

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

# 样式 style

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

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

属性：

• value：样式名。

# 布局定位 layout

默认情况富文本内容已经在一个和富文本容器Transform2D大小一致的默认layout中。

<layout|x=10|y=20|width=200|height=200></layout>

布局元素。需要用 </layout> 手动闭合标签。

定位: 基于上层layout的坐标，如上例是从上层layout的(10,20)的坐标开始绘制。

大小: 若有设置width、height，则使用这两个值，若无设置，则根据坐标与上层layout大小，撑满剩余的距离。内部元素换行依赖该大小。

属性

• x：x轴坐标，默认为0
• y：y轴坐标，默认为0
• width：layout的宽度，作为换行以及对齐的依据，不填写会根据上层layout自动计算。
• height：layout的高度。

# 对齐方式 align

align标签不能嵌套。

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

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

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

# 行间距倍数 linespace

<linespace|value=0.5>

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

属性：

• value：倍数，默认为 0。

# 换行 br

<br|value=0>

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

连续使用多个<br>不会换多行，需要使用<br|value=x>

属性：

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

# 超链接 link

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

超链接元素。需要用 </link> 手动闭合标签，会自动给内部的元素添加超链接特性。 若为在 style 中指定样式，那么超链接文本将自带 1px 下划线，颜色与字色相同。 可通过在自定义 ScriptComponent 中使用 onClickRichTextLink() 方法来监听点击。

class MyScript extends engine.script {
  onClickRichTextLink(event: UIRichTextLinkEvent) {
    console.log(event); // { text: "超链接", data: "someData" }
  }
}

entity.addComponent(MyScript); // 挂载到 UIRichText 所在的 entity

属性：

• style：样式名。
• text：文本内容。
• data：点击后可获得的数据，字符串格式。

# 图片 img

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

静态图片。

属性：

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

# 帧动画 animation

<animation|texture=texId1,texId2|size=15,20|rate=2|loop=1> <animation|spriteframe=texId{3}|size=15,20|rate=3|loop=1> <animation|spriteframe=texId{1,3}|size=15,20|rate=3|loop=1>

帧动画图片。

属性：

• texture：资源 Texture2D 的路径，应为一组图片，支持的写法格式见下表。与 spriteframe 属性互斥。
• spriteframe：资源 SpriteFrame 的路径，应为一组图片，，支持的写法格式见下表。与 texture 属性互斥。
• size：图片宽高，格式 width,height。
• rate：帧率，每秒播放几帧。
• loop：循环，1 为循环播放，非 1 为只播放一次。

texutre 和 spriteframe 属性支持的不同的写法，可以自动对应到若干张图片，以组成帧动画。

# 富文本越界处理方式

富文本内容大于容器大小时，处理方式，默认为Auto，不处理。

// engine.UIRichText.overflowType
enum overflowType {
  Auto,
  Hidden,
}

// 富文本内容大于容器大小时，越界情况不显示。
richText.overflow = engine.UIRichText.overflowType.Hidden; 

# 获取实际宽高

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

interface Metrics {
  width: number; // align情况下，内容所占的宽度
  height: number; // align情况下，内容所占的高度
  layoutWidth: number; // 从容器起点(0,0)算起，内部layout所占的宽度
  layoutHeight: number; // 从容器起点(0,0)算起，内部layout所占的高度
}

const metrics = richText.metrics as Metrics;

# 强制重绘

richText.redraw(); // 将在下一帧重绘

# 支持emoji字符

richText.emoji = true; // 富文本开启支持emoji字符