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

样式表支持属性:

属性 类型 默认值 说明
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" 渐变色底端

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

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

行间距倍数 linespace

<linespace|value=0.5>

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

属性:

  • value:倍数,默认为 0。

换行 br

<br|value=0>

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

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

属性:

  • value:换行距离,在行本身的换行的距离以外,额外的距离。

<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 属性支持的不同的写法,可以自动对应到若干张图片,以组成帧动画。

格式 说明 例子 结果
"path" 加载单张图片 "path/a" 1 张图 ["path/a"]
"path1,path2" 逗号分隔不同图片 "path/a,path/b" 2 张图 ["path/a", "path/b"]
"path{n}" 按序号加载 n 张图 "path/a{2} 2 张图 ["path/a1", "path/a2"]
"path{n,m}" 按序号加载若干张图 "path/a{1,3} 3 张图 ["path/a1", "path/a2", "path/a3"]

富文本越界处理方式

富文本内容大于容器大小时,处理方式,默认为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字符