RichTextLabel中的BBCode

简介

标签节点非常适合显示基本文本,但它们有局限性。如果更改文本的颜色或其对齐方式,则该更改会影响标签节点中的所有文本。不能让一部分文本用一种颜色,或者只有一部分文本居中。要绕过此限制,可以使用 RichTextLabel

RichTextLabel allows the display of complex text markup in a Control. It has a built-in API for generating the markup, but can also parse a BBCode.

大部分BBCode标签也可以用在 XML格式的类参考文档

使用富文本(BBCode)

对于统一格式的文本,可以在“Text”属性中编写,但如果要使用BBCode标签,则应改用“Bb Code”下的“Text”属性( bbcode_text )。设置此属性将解析标签并设置格式。不过在此之前,你需要勾选“Bb Code”下的“Enable”属性( bbcode_enabled )。

../../_images/bbcodeText.png

例如, ``BBCode [color=blue]blue[/color]``将会出现蓝色的单词“blue”。

../../_images/bbcodeDemo.png

你可能注意到,在写入“Bb Code”下的“Text”属性后,常规的“Text”属性现在更新为不带BBCode标签的文本。虽然Text属性将由BBCode属性更新,但你不能编辑Text属性,否则将丢失BBCode标签。对文本的所有更改都必须在BBCode参数中完成。

注解

要使用 [b] (粗体)、 [i] (斜体)或 [code] 等BBCode标签,必须先为RichTextLabel节点设置对应的自定义字体(位于Custom Fonts下)。

目前还没有用于控制文本垂直居中的BBCode标签。

可用标签参考

命令

标签

描述

bold

[b]{text}[/b]

使得 {text} 呈现粗体。

italics

[i]{text}[/i]

使得 {text} 呈现斜体。

underline

[u]{text}[/u]

使得 {text} 呈现下划线。

strikethrough

[s]{text}[/s]

使{text}删除。

code

[code]{text}[/code]

使{text}使用代码字体(通常为等宽字体)。

center

[center]{text}[/center]

使得 {text} 水平居中。

right

[right]{text}[/right]

使得 {text} 右对齐。

fill

[fill]{text}[/fill]

Makes {text} fill the RichTextLabel's width.

indent

[indent]{text}[/indent]

增加 {text} 的缩进级别。

url

[url]{url}[/url]

按原样显示{url},为其加下划线并使其可点击。

url (ref)

[url=<url>]{text}[/url]

使得{text}呈现且点击后相当于点击<url> 。

image

[img]{path}[/img]

插入由资源路径 {path} 所指示的图片。

resized image

[img=<width>]{path}[/img]

插入由资源路径 {path} 所指示的图片,并指定其宽度(保持宽高比)。

resized image

[img=<width>x<height>]{path}[/img]

插入由资源路径 {path} 所指示的图片,指定其宽与高。

font

[font=<path>]{text}[/font]

为 {text} 内容设置自定义字体,字体由 <path> 指定。

color

[color=<code/name>]{text}[/color]

改变 {text} 的颜色, 可以使用颜色名称或十六进制码指定颜色,如 #ff00ff

table

[table=<number>]{cells}[/table]

创建一个包含<number>列数的表。

cell

[cell]{text}[/cell]

将带有{text}的单元格添加到表格中。

内置的颜色名称列表

以下列出[color=<name>]标签所支持的有效颜色名称:

  • aqua

  • black

  • blue

  • fuchsia

  • gray

  • green

  • lime

  • maroon

  • navy

  • purple

  • red

  • silver

  • teal

  • white

  • yellow

十六进制颜色代码

对于不透明的 RGB 颜色,支持任何有效的6位十六进制数,例如 [color=#ffffff]white[/color]

对于透明的 RGB 颜色,可以使用任意8位十六进制数,例如 [color=#88ffffff]translucent white[/color] 。在这种情况下,请注意 alpha 通道是颜色代码的 第一个 分量,而不是最后一个。

图像垂直偏移

您可以对图像使用自定义字体,以便将其垂直对齐。

  1. 创建 BitmapFont 字体资源

  2. 将这个位图字体的 ascent 属性设置为正值,即你的高度偏移量

  3. 按下面方式设置BBCode标签:[font=<font-path>][img]{image-path}[/img][/font]

动画特效

BBCode也可以用来创建不同的文字动画特效。内置了五种特效,当然你也可以轻松创建出自已的特效。

波浪

../../_images/wave.png

波浪使文字上下波动,它的标签格式是``[wave amp=50 freq=2][/wave]``。``amp``控制特效高低,``freq``控制文字上下移动的速度。

旋风

../../_images/tornado.png

龙卷风使文字在圆圈内移动,它的标签格式是``[tornado radius=5 freq=2][/tornado]``。``radius``是控制偏移的圆半径,``freq``是文字在圆中移动的速度。

抖动

../../_images/shake.png

抖动使文字摇动,它的标签格式是``[shake rate=5 level=10][/shake]``。``rate``控制文本抖动的速度,``level``控制文本与原点的偏移程度。

渐隐

../../_images/fade.png

渐变在没有动画的文本上创建一个渐变效果,它的标签格式是``[fade start=4 length=14][/fade]``。``start``控制相对于插值淡入命令的起始位置,``length``控制淡出应该发生多少个字符。

彩虹

../../_images/rainbow.png

彩虹让文字呈现出随时间变化的彩虹色,它的标签格式是``[rainbow freq=0.2 sat=10 val=20][/rainbow]``。``freq``是每秒完整的彩虹周期数,``sat``是彩虹的饱和度,``val``是彩虹的数值。

自定义BBCode标签和文本效果

可以扩展 RichTextEffect 资源类型来创建自己的 BBCode 标签,可以从扩展 RichTextEffect 资源类型开始,如果想在编辑器中运行这些自定义效果,请在GDScript文件中添加``tool``前缀,RichTextLabel不需要附加脚本,也不需要在``tool``模式下运行。

只需要扩展一个函数: _process_custom_fx(char_fx),或者可以通过添加成员名称``bbcode``来提供自定义BBCode标识符,该代码将自动检查bbcode属性,或使用文件名来决定BBCode标签应该是什么。

_process_custom_fx

这是每个效果的逻辑生效的地方,在文本渲染绘制阶段,每个字符被调用一次,将传入一个:ref:`class_CharFXTransform`对象,该对象拥有一些变量来控制相关字符的渲染方式:

  • ``identity身份``指定正在处理哪个自定义效果,应该用它来控制代码流程。

  • ``relative_index``告诉你在一个给定的自定义效果区块中的索引有多远。

  • ``absolute_index``告诉你作为索引到整个文本的距离。

  • elapsed_time is the total amount of time the text effect has been running.

  • ``visible可见性``将告诉你这个字符是否可见,也允许你隐藏文本的某个部分。

  • ``offset``是相对于给定字符在正常情况下应该呈现的位置的偏移位置。

  • ``color``是一种预先规定的字符颜色。

  • 最后,``env``是一个指定自定义效果的参数:ref`:class_Dictionary`。如果用户指定,您可以使用:ref:Get()<CLASS_Dictionary_Method_Get>`和可选默认值来检索每个参数。例如,``[custom_fx spread=0.5 color=#FFFF00]test[/custom_fx]``在其``env``字典中将有一个浮动``spread` and Color``color``参数。有关更多的实例用法,请参阅下面的内容。

最后需要注意的关于此函数,必须返回一个布尔值``true``,以验证结果处理正确,这样一来,如果这个预先规定的字符渲染出现问题,它将完全退出自定义渲染的效果,直到用户修复自定义渲染出现的任何错误。

Here are some examples of custom effects:

幽灵

tool
extends RichTextEffect
class_name RichTextGhost

# Syntax: [ghost freq=5.0 span=10.0][/ghost]

# Define the tag name.
var bbcode = "ghost"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var speed = char_fx.env.get("freq", 5.0)
    var span = char_fx.env.get("span", 10.0)

    var alpha = sin(char_fx.elapsed_time * speed + (char_fx.absolute_index / span)) * 0.5 + 0.5
    char_fx.color.a = alpha
    return true

脉冲

tool
extends RichTextEffect
class_name RichTextPulse

# Syntax: [pulse color=#00FFAA height=0.0 freq=2.0][/pulse]

# Define the tag name.
var bbcode = "pulse"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var color = char_fx.env.get("color", char_fx.color)
    var height = char_fx.env.get("height", 0.0)
    var freq = char_fx.env.get("freq", 2.0)

    var sined_time = (sin(char_fx.elapsed_time * freq) + 1.0) / 2.0
    var y_off = sined_time * height
    color.a = 1.0
    char_fx.color = char_fx.color.linear_interpolate(color, sined_time)
    char_fx.offset = Vector2(0, -1) * y_off
    return true

Matrix

tool
extends RichTextEffect
class_name RichTextMatrix

# Syntax: [matrix clean=2.0 dirty=1.0 span=50][/matrix]

# Define the tag name.
var bbcode = "matrix"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var clear_time = char_fx.env.get("clean", 2.0)
    var dirty_time = char_fx.env.get("dirty", 1.0)
    var text_span = char_fx.env.get("span", 50)

    var value = char_fx.character

    var matrix_time = fmod(char_fx.elapsed_time + (char_fx.absolute_index / float(text_span)), \
                           clear_time + dirty_time)

    matrix_time = 0.0 if matrix_time < clear_time else \
                  (matrix_time - clear_time) / dirty_time

    if value >= 65 && value < 126 && matrix_time > 0.0:
        value -= 65
        value = value + int(1 * matrix_time * (126 - 65))
        value %= (126 - 65)
        value += 65
    char_fx.character = value
    return true

This will add a few new BBCode commands, which can be used like so:

[center][ghost]This is a custom [matrix]effect[/matrix][/ghost] made in
[pulse freq=5.0 height=2.0][pulse color=#00FFAA freq=2.0]GDScript[/pulse][/pulse].[/center]