RichTextLabel

Inherits: Control < CanvasItem < Node < Object

显示富文本的标签。

描述

富文本可以包含自定义文本、字体、图像和一些基本格式。该标签会将这些以内部标签堆栈的形式进行管理。它还可以适应给定的宽度/高度。

注意：为 bbcode_text 设置内容会清除标签堆栈并根据该属性的内容重建。对 bbcode_text 所做的任何编辑都将删除先前从其他手动来源（例如 append_bbcode 和 push_* / pop 方法）所做的编辑。

注意：RichTextLabel 不支持纠缠的 BBCode 标签。例如，不要使用 [b]bold[i]bold italic[/b]italic[/i]，应该使用 [b]bold[i]bold italic[/i][/b][i]italic[/i]。

注意：push_*/pop 函数不会影响 BBCode。

注意：与 Label 不同，RichTextLabel 没有可以将文本水平居中对其的属性。不过你可以启用 bbcode_enabled 并将文本括在 [center] 标签中，类似：[center]例子[/center]。目前也没有垂直对齐文本的内置方法，但这可以通过依赖锚点/容器和 fit_content_height 属性来模拟。

注意：Windows 上不支持 0xffff 之后的 Unicode 字符（例如大多数表情符号）。它们将显示为未知字符。这将在 Godot 4.0 中解决。

教程

• BBCode in RichTextLabel

• GUI Rich Text/BBcode Demo

• OS Test Demo

属性

方法

主题属性

信号

• meta_clicked ( Variant meta )

当用户点击元标记之间的内容时触发。如果元是在文本中定义的，例如[url={"data"="hi"}]hi[/url]，则该信号的参数为String类型。如果需要特定类型或对象，则必须使用 push_meta 方法将数据手动插入标签堆栈。

• meta_hover_ended ( Variant meta )

当鼠标退出元标签时触发。

• meta_hover_started ( Variant meta )

当鼠标进入元标签时触发。

枚举

enum Align:

• ALIGN_LEFT = 0 —- 使文本左对齐。

• ALIGN_CENTER = 1 —- 使文本居中。

• ALIGN_RIGHT = 2 —- 使文本右对齐。

• ALIGN_FILL = 3 —- 使文本填充宽度。

enum ListType:

• LIST_NUMBERS = 0 —- 每个列表项都有一个数字标记。

• LIST_LETTERS = 1 —- 每个列表项都有一个字母标记。

• LIST_DOTS = 2 —- 每个列表项都有一个实心圆圈标记。

enum ItemType:

• ITEM_FRAME = 0

• ITEM_TEXT = 1

• ITEM_IMAGE = 2

• ITEM_NEWLINE = 3

• ITEM_FONT = 4

• ITEM_COLOR = 5

• ITEM_UNDERLINE = 6

• ITEM_STRIKETHROUGH = 7

• ITEM_ALIGN = 8

• ITEM_INDENT = 9

• ITEM_LIST = 10

• ITEM_TABLE = 11

• ITEM_FADE = 12

• ITEM_SHAKE = 13

• ITEM_WAVE = 14

• ITEM_TORNADO = 15

• ITEM_RAINBOW = 16

• ITEM_CUSTOMFX = 18

• ITEM_META = 17

属性说明

• bool bbcode_enabled

如果 true，标签使用 BBCode 格式。

注意： 尝试使用 add_text 更改 RichTextLabel 的文本会将其重置为 false。改用 append_bbcode 来保留 BBCode 格式。

• String bbcode_text

BBCode 格式的标签文本。不代表对内部标签栈的手动修改。编辑时擦除通过其他方法所做的更改。

注意： 不建议将 += 运算符与 bbcode_text 一起使用（例如 bbcode_text += "some string"），因为它会替换整个文本并可能导致速度变慢。使用 append_bbcode 代替添加文本，除非你必须关闭在先前方法调用中打开的标签。

• Array custom_effects

当前配置的自定义效果。这是一个RichTextEffect的数组。

要添加一个自定义效果，使用install_effect会更方便。

• bool fit_content_height

如果 true，标签的高度将自动更新以适应其内容。

注意： 此属性用作解决 Container 中 RichTextLabel 问题的解决方法，但在某些情况下不可靠，将在未来版本中删除。

• bool meta_underlined

如果 true，则会在元标签下划线，例如 [url]{text}[/url]。

• bool override_selected_font_color

如果 true，则标签使用自定义字体颜色。

• float percent_visible

要显示的字符范围，数值为0.0和1.0之间的float。当分配一个超出范围的值时，它和分配1.0是一样的。

注意： 设置这个属性会根据当前的get_total_character_count更新visible_characters。

• bool scroll_active

如果 true，则滚动条可见。将此设置为 false 不会完全阻止滚动。见scroll_to_line。

• bool scroll_following

如果 true，则窗口向下滚动以自动显示新内容。

• bool selection_enabled

如果 true，标签允许文本选择。

• int tab_size

The number of spaces associated with a single tab length. Does not affect \t in text tags, only indent tags.

• String text

标签的原始文本。

设置后，清除标签堆栈并在其顶部添加一个原始文本标签。不解析 BBCode。不修改 bbcode_text。

• int visible_characters

在标签中显示的字符数限制。如果-1，将显示所有字符。

注意： 设置此属性会根据当前的get_total_character_count更新percent_visible。

方法说明

• void add_image ( Texture image, int width=0, int height=0 )

将图像的开头和结尾标签添加到标签堆中，可以选择提供 width 和 height 来调整图像的大小。

如果 width 或 height 被设置为 0，图像的大小被调整为保持原始长宽比。

• void add_text ( String text )

将非 BBCode 解析的原始文本添加到标签栈中。

• Error append_bbcode ( String bbcode )

解析 bbcode 并根据需要将标签添加到标签堆栈中。返回解析结果，成功则返回 @GlobalScope.OK。

注意： 使用此方法，您无法关闭在之前的 append_bbcode 调用中打开的标签。这样做是为了提高性能，特别是在更新大型 RichTextLabel 时，因为每次重建整个 BBCode 会更慢。如果您绝对需要在将来的方法调用中关闭标签，请附加 bbcode_text 而不是使用 append_bbcode。

• void clear ( )

清除标记堆栈并将 bbcode_text 设置为空字符串。

• int get_content_height ( ) const

返回内容的高度。

• int get_line_count ( ) const

返回标签栈中文本标签的换行总数。将被包裹的文本视为一行。

• int get_total_character_count ( ) const

返回文本标签的总字符数。不包括 BBCode。

• VScrollBar get_v_scroll ( )

返回垂直滚动条。

警告： 这是一个必需的内部节点，删除和释放它可能会导致崩溃。如果您希望隐藏它或其任何子项，请使用它们的 CanvasItem.visible 属性。

• int get_visible_line_count ( ) const

返回可见行数。

• void install_effect ( Variant effect )

安装自定义效果。 effect 应该是一个有效的 RichTextEffect。

• void newline ( )

在标签堆中添加一个换行标签。

• Error parse_bbcode ( String bbcode )

append_bbcode 的指定版本。清除标记堆栈并插入新内容。如果成功解析 bbcode，则返回 @GlobalScope.OK。

• Dictionary parse_expressions_for_values ( PoolStringArray expressions )

将 BBCode 参数 expressions 解析为字典。

• void pop ( )

终止当前标签。使用 push_* 方法之后手动关闭 BBCodes。不需要遵循 add_* 方法。

• void push_align ( Align align )

根据给定的[align]值，添加一个align标签。可能的值见Align。

• void push_bold ( )

在标签堆中添加一个[font]标签，字体为黑体。如果当前没有[i]标签，这与添加一个[b]标签相同。

• void push_bold_italics ( )

在标签堆中添加一个[font]标签，字体为粗斜体。

• void push_cell ( )

将一个[cell]标签添加到标签堆中。必须在一个[table]标签内。详情见push_table。

• void push_color ( Color color )

将一个[color]标签添加到标签堆。

• void push_font ( Font font )

将一个[font]标签添加到标签堆中。在其有效期内覆盖默认字体。

• void push_indent ( int level )

将 [indent] 标签添加到标签堆栈。将 level 乘以当前 tab_size 以确定新的边距长度。

• void push_italics ( )

在标签堆中添加一个[font]标签，字体为斜体。如果当前没有[b]标签，这与添加[i]标签相同。

• void push_list ( ListType type )

在标签栈中添加一个[list]标签。类似于BBCodes [ol] 或 [ul] ，但支持更多的列表类型。未完全实现!

• void push_meta ( Variant data )

添加一个[meta]标签到标签堆中。类似于BBCode [url=something]{text}[/url]，但支持非String元数据类型。

• void push_mono ( )

在标签堆中添加一个[font]标签，该标签为等宽字体。

• void push_normal ( )

在标签堆中添加一个具有正常字体的[font]标签。

• void push_strikethrough ( )

将一个[s]标签添加到标签堆中。

• void push_table ( int columns )

将一个[table=columns]标签添加到标签栈。

• void push_underline ( )

将一个[u]标签添加到标签堆中。

• bool remove_line ( int line )

删除标签中的一行内容。如果该行存在，则返回 true。

参数 line 是要删除的行的索引，可以在 [0, get_line_count() - 1] 的区间内取值。

• void scroll_to_line ( int line )

滚动窗口的顶行以匹配line。

• void set_table_column_expand ( int column, bool expand, int ratio )

编辑选中的列的扩展选项。如果expand是true，该列会按其扩展比例与其他列的比例进行扩展。

例如，2个比率为3和4的列加上70像素的可用宽度将分别扩展30和40像素。

如果expand是false，该列将不会对总的比例产生影响。

Theme Property Descriptions

• Color default_color

默认文本颜色。

• Color font_color_selected

选定文本的颜色(当selection_enabled为true时使用)。

• Color font_color_shadow

字体阴影的颜色。

• Color selection_color

选择框的颜色。

• int line_separation

行之间的垂直空间。

• int shadow_as_outline

布尔值。如果是1（true），阴影将以轮廓的形式围绕整个文本显示。

• int shadow_offset_x

字体阴影的水平偏移量。

• int shadow_offset_y

字体阴影的垂直偏移。

• int table_hseparation

表中元素的水平间距。

• int table_vseparation

表中元素的垂直间距。

• Font bold_font

用于粗体字的字体。

• Font bold_italics_font

用于粗斜体文字的字体。

• Font italics_font

用于斜体字的字体。

• Font mono_font

用于等宽文本的字体。

• Font normal_font

默认的文本字体。

• StyleBox focus

RichTextLabel 获得焦点时使用的背景。

• StyleBox normal

RichTextLabel 的正常背景。