# UIRichText 富文本组件

# 概述

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

# 标签格式

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

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

# 目录

# 样式

样式表支持属性:

属性 类型 默认值 说明
font string "Arial" 字体名
size number 12 字号
color string "#000000" 字体颜色
bold boolean false 是否粗体
italic boolean false 是否斜体
spacing number 0 字间距
stroke number 0 描边粗细,0 为不描边
strokeColor string "#000000" 描边颜色
underline number 0 下划线粗细,0 为没下划线
underlineColor string "#000000" 下划线颜色
shadow string "" 阴影 offset,如 "1,2" 为偏移 x=1,y=2,设空串 "" 为无阴影
shadowColor string "#000000" 阴影颜色
applyGradient boolen false 是否开启渐变色
gradientTop string "#000000" 渐变色顶端
gradientBottom string "#000000" 渐变色底端

# 设置全局样式表

类似 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 内部,子元素垂直方向的对齐规则。

属性 含义 可选值
horz 水平对齐,依据当前 Layout 容器宽度来对齐 left 居左(默认)、center 居中、right 居右
vert 垂直对齐,依据所在的行高对齐 top 顶部(默认)、center 中部、bottom 底部

# 行间距倍数 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

# 使用案例

使用各类渲染元素