RichText 组件参考

校对：RazgrizHsu

RichText 组件用来显示一段带有不同样式效果的文字，你可以通过一些简单的 BBCode 标签来设置文字的样式。目前支持的样式有：颜色（color）、字体大小（size）、字体描边（outline）、加粗（b）、斜体（i）、下划线（u）、换行（br）、图片（img）和点击事件（on），并且不同的 BBCode 标签是可以支持相互嵌套的。

更多关于 BBCode 标签的内容，请参考本文档下方的 BBCode 标签格式 小节。

richtext

点击 属性检查器 下面的 添加组件 按钮，然后从 渲染组件 中选择 RichText，即可添加 RichText 组件到节点上。

RichText 属性

属性功能说明
String富文本的内容字符串, 你可以在里面使用 BBCode 来指定特定文本的样式
Horizontal Align水平对齐方式
Font Size字体大小, 单位是 point （注意，该字段不会影响 BBCode 里面设置的字体大小）
Font富文本定制字体，所有的 label 片断都会使用这个定制的 TTF 字体
Font Family富文本定制系统字体。
Use System Font是否使用系统字体。
Max Width富文本的最大宽度, 传 0 的话意味着必须手动换行.
Line Height字体行高, 单位是 point
Image Atlas对于 img 标签里面的 src 属性名称，都需要在 imageAtlas 里面找到一个有效的 spriteFrame，否则 img tag 会判定为无效。
Handle Touch Event选中此选项后，RichText 将阻止节点边界框中的所有输入事件（鼠标和触摸），从而防止输入事件穿透到底层节点。

富文本的 API 接口请参考 RichText API。

BBCode 标签格式

基本格式

目前支持的标签类型有：size，color, b, i, u, img 和 on，分别用来定制字体大小，字体颜色, 加粗，斜体，下划线，图片和点击事件。每一个标签都有一个起始标签和一个结束标签，起始标签的名字和属性格式必要符合要求，且全部为小写。结束标签的名字不做任何检查，只需要满足结束标签的定义即可。

下面分别是应用 size 和 color 标签的一个例子：

<color=green>你好</color>，<size=50>Creator</>

支持标签

注意：所有的 tag 名称必须是小写，且属性值是用 = 号赋值

名称描述示例注意事项
color指定字体渲染颜色，颜色值可以是内置颜色，比如 white，black 等，也可以使用 16 进制颜色值，比如#ff0000 表示红色<color=#ff0000>Red Text</color>内置颜色值参考 cc.Color
size指定字体渲染大小，大小值必须是一个整数<size=30>enlarge me</size>Size 值必须使用等号赋值
outline设置文本的描边颜色和描边宽度<outline color=red width=4>A label with outline</outline>如果你没有指定描边的颜色或者宽度的话，那么默认的颜色是白色(#ffffff),默认的宽度是 1
b指定使用粗体来渲染<b>This text will be rendered as bold</b>名字必须是小写，且不能写成 bold
i指定使用斜体来渲染<i>This text will be rendered as italic</i>名字必须是小写，且不能写成 italic
u给文本添加下划线<u>This text will have a underline</u>名字必须是小写，且不能写成 underline
on指定一个点击事件处理函数，当点击该 Tag 所在文本内容时，会调用该事件响应函数<on click="handler"> click me! </on>除了 on 标签可以添加 click 属性，color 和 size 标签也可以添加，比如 <size=10 click="handler2">click me</size>
param当点击事件触发时，可以在回调函数的第二个参数获取该数值<on click="handler" param="test"> click me! </on>依赖 click 事件
br插入一个空行<br/>注意：<br></br> 和 <br> 都是不支持的。
img给富文本添加图文混排功能，img 的 src 属性必须是 ImageAtlas 图集里面的一个有效的 spriteframe 名称<img src='emoji1' click='handler' />注意: 只有 <img src='foo' click='bar' /> 这种写法是有效的。如果你指定一张很大的图片，那么该图片创建出来的精灵会被等比缩放，缩放的值等于富文本的行高除以精灵的高度。

img 标签的可选属性

为了更好地排版，我们为 img 标签类型提供了可选属性，你可以使用 width 及 height 来指定 SpriteFrame 的大小，这将允许该图片可以大于或是小于行高（但此设定不会改变行高）。

当你改变了 SpriteFrame 的高度或宽度后，或许会需要使用 align 来调整该图片在行中的对齐方式。

属性描述示例注意事项
height指定 SpriteFrame 的渲染高度，大小值必须为整数<img src='foo' height=50 />如果你只使用了高度属性，该 SpriteFrame 会自动计算宽度以保持图片比例
width指定 SpriteFrame 的渲染宽度，大小值必须为整数<img src='foo' width=50 />你可以同时使用高度及宽度属性 <img src='foo' width=20 height=30 />
align指定 SpriteFrame 在行中的对齐方式，值必需为 bottom、top 或 center<img src='foo' align=center />预设对齐方式为 bottom

为了支持定制图片排版，我们还提供了 offset 属性，用于微调 SpriteFrame 在 RichText 中的位置。设置 offset 时需注意属性值必须为整数，并且如设置不当将导致图片与文字重叠。

offset 属性示例描述注意事项
Y<img src='foo' offset=5 />指定 SpriteFrame 的 y 轴加上 5当 offset 只设定一个值的时候，它代表 y 轴的偏移
Y<img src='foo' offset=-5 />指定 SpriteFrame 的 y 轴减少 5你可以设定负整数来减少 y 轴
X, Y<img src='foo' offset=6,-5 />指定 SpriteFrame 的 x 轴加上 6，y 轴减少 5偏移属性的值只能包含 0-9、- 和 , 字符

标签嵌套

标签与标签是支持嵌套的，且嵌套规则跟 HTML 是一样的。比如下面的嵌套标签设置一个文本的渲染大小为 30，且颜色为绿色。

<size=30><color=green>I'm green</color></size>

也可以实现为:

<color=green><size=30>I'm green</size></color>

有以下两种方式可以设置 RichText 的颜色：

  • 选中节点，在 属性检查器 的 Node -> Color 中设置 RichText 的整体颜色
  • 使用 bbcode 对 RichText 内部分别设置颜色 注意：两者不可混用，如果混用了，将以第一种方式设置的颜色为准。

文本缓存类型（Cache Mode）

由于富文本组件是由多个 Label 节点拼装而成，所以对于复杂的富文本，drawcall 数量也会比较高，因此引擎为富文本组件提供了 Label 组件的文本缓存类型设置，来适当减少 drawcall 的增加。对于每种缓存类型的具体说明，参照 Label 组件的文本缓存类型

属性功能说明
NONE默认值，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 NONE 类型，即将每个 Label 的整段文本生成一张位图并单独进行渲染。
BITMAP选择后，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 BITMAP 类型，即将每个 Label 的整段文本生成一张位图，并将该位图添加到动态图集中，再依据动态图集进行合并渲染。
CHAR选择后，对富文本所拆分创建的每个 Label 节点，设置其 CacheMode 为 CHAR 类型，即将每个 Label 的文本以“字”为单位缓存到全局共享的位图中，相同字体样式和字号的每个字符将在全局共享一份缓存。

注意：使用文本缓存类型时不能剔除 项目 -> 项目设置 -> 模块设置 面板中的 RenderTexture 模块。

详细说明

富文本组件全部由 JS 层实现，采用底层的 Label 节点拼装而成，并且在上层做排版逻辑。这意味着，你新建一个复杂的富文本，底层可能有十几个 label 节点，而这些 label 节点都是采用系统字体渲染的。所以一般情况下，你不应该在游戏的主循环里面频繁地修改富文本的文本内容, 这可能会导致性能比较低。另外，如果能不使用富文本组件，就尽量使用普通的文本组件，并且 BMFont 的效率是最高的。