RichTextLabel

继承： Control < CanvasItem < Node < Object

用于显示文本的控件，文本中能够包含不同的字体样式、图片以及基础格式。

描述

用于显示文本的控件，文本中能够包含自定义字体、图片以及基础格式。RichTextLabel 使用内部标签栈管理这些内容。它还可以适应给定的宽度和高度。

注意：对 text 赋值会将标签栈清空并根据该属性的内容重建。对 text 所做的任何编辑都将擦除之前从 append_text 和 push_* / pop 方法等其他手动来源所做的编辑。

注意：RichTextLabel 不支持纠缠的 BBCode 标签。例如，请不要使用 [b]加粗[i]加粗斜体[/b]斜体[/i]，请改为 [b]加粗[i]加粗斜体[/i][/b][i]斜体[/i]。

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

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

教程

• RichTextLabel 中的 BBCode

• GUI 富文本/BBcode 演示

• 操作系统测试演示

属性

方法

主题属性

信号

finished ( )

当文档完全加载时触发。

meta_clicked ( Variant meta )

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

meta_hover_ended ( Variant meta )

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

meta_hover_started ( Variant meta )

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

枚举

enum ListType:

ListType LIST_NUMBERS = 0

每个列表项都有数字标记。

ListType LIST_LETTERS = 1

每个列表项都有字母标记。

ListType LIST_ROMAN = 2

每个列表项都有罗马数字标记。

ListType LIST_DOTS = 3

每个列表项都有实心圆标记。

enum MenuItems:

MenuItems MENU_COPY = 0

复制选中的文本。

MenuItems MENU_SELECT_ALL = 1

全选 TextEdit 文本。

MenuItems MENU_MAX = 2

代表 MenuItems 枚举的大小。

flags ImageUpdateMask:

ImageUpdateMask UPDATE_TEXTURE = 1

如果设置了该位，update_image 会更改图像纹理。

ImageUpdateMask UPDATE_SIZE = 2

如果设置了该位，update_image 会更改图像大小。

ImageUpdateMask UPDATE_COLOR = 4

如果设置了该位，update_image 会更改图像颜色。

ImageUpdateMask UPDATE_ALIGNMENT = 8

如果设置了该位，update_image 会更改图像内联对齐方式。

ImageUpdateMask UPDATE_REGION = 16

如果设置了该位，update_image 会更改图像纹理区块。

ImageUpdateMask UPDATE_PAD = 32

如果设置了该位，update_image 会更改图像填充。

ImageUpdateMask UPDATE_TOOLTIP = 64

如果设置了该位，update_image 会更改图像工具提示。

ImageUpdateMask UPDATE_WIDTH_IN_PERCENT = 128

如果设置了该位，update_image 会将图像宽度更改自/为百分比。

属性说明

AutowrapMode autowrap_mode = 3

• void set_autowrap_mode ( AutowrapMode value )

• AutowrapMode get_autowrap_mode ( )

如果设置为 TextServer.AUTOWRAP_OFF 以外的值，则文本将在节点的边界矩形内换行。要了解每种模式的行为，请参见 AutowrapMode。

bool bbcode_enabled = false

• void set_use_bbcode ( bool value )

• bool is_using_bbcode ( )

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

bool context_menu_enabled = false

• void set_context_menu_enabled ( bool value )

• bool is_context_menu_enabled ( )

为 true 时右键单击会显示上下文菜单。

Array custom_effects = []

• void set_effects ( Array value )

• Array get_effects ( )

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

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

bool deselect_on_focus_loss_enabled = true

• void set_deselect_on_focus_loss_enabled ( bool value )

• bool is_deselect_on_focus_loss_enabled ( )

如果为 true，则在丢失焦点时会取消选中文本。

bool drag_and_drop_selection_enabled = true

• void set_drag_and_drop_selection_enabled ( bool value )

• bool is_drag_and_drop_selection_enabled ( )

如果为 true，则允许拖放选中的文本。

bool fit_content = false

• void set_fit_content ( bool value )

• bool is_fit_content_enabled ( )

如果为 true，该标签的最小尺寸会自动更新，适应其内容，与 Label 的行为相匹配。

bool hint_underlined = true

• void set_hint_underline ( bool value )

• bool is_hint_underlined ( )

如果为 true，则该标签节点会在 hint 标记下，加下划线，例如 [hint=description]{text}[/hint]。

String language = ""

• void set_language ( String value )

• String get_language ( )

语言代码，用于断行和文本塑形算法，如果留空则使用当前区域设置。

bool meta_underlined = true

• void set_meta_underline ( bool value )

• bool is_meta_underlined ( )

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

int progress_bar_delay = 1000

• void set_progress_bar_delay ( int value )

• int get_progress_bar_delay ( )

加载进度条显示的延迟时间，单位为毫秒。将其设置为 -1 将完全禁用进度条。

注意：仅当 threaded 已启用时才会显示进度条。

bool scroll_active = true

• void set_scroll_active ( bool value )

• bool is_scroll_active ( )

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

bool scroll_following = false

• void set_scroll_follow ( bool value )

• bool is_scroll_following ( )

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

bool selection_enabled = false

• void set_selection_enabled ( bool value )

• bool is_selection_enabled ( )

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

bool shortcut_keys_enabled = true

• void set_shortcut_keys_enabled ( bool value )

• bool is_shortcut_keys_enabled ( )

为 true 时，即使上下文菜单已被禁用，也会启用该上下文菜单的快捷键。

StructuredTextParser structured_text_bidi_override = 0

• void set_structured_text_bidi_override ( StructuredTextParser value )

• StructuredTextParser get_structured_text_bidi_override ( )

为结构化文本设置 BiDi 算法覆盖。

Array structured_text_bidi_override_options = []

• void set_structured_text_bidi_override_options ( Array value )

• Array get_structured_text_bidi_override_options ( )

设置 BiDi 覆盖的附加选项。

int tab_size = 4

• void set_tab_size ( int value )

• int get_tab_size ( )

与单个制表符长度关联的空格数。不影响文本标签中的 \t，只影响缩进标签。

String text = ""

• void set_text ( String value )

• String get_text ( )

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

注意：如果 bbcode_enabled 为 true，则不建议将 += 运算符与 text 一起使用（例如 text += "some string"）因为它会替换整个文本并可能导致速度变慢。它还将擦除使用 push_* 方法添加到堆栈中的所有 BBCode。请改用 append_text 添加文本，除非你绝对需要关闭在之前的方法调用中打开的标签。

TextDirection text_direction = 0

• void set_text_direction ( TextDirection value )

• TextDirection get_text_direction ( )

基础文本书写方向。

bool threaded = false

• void set_threaded ( bool value )

• bool is_threaded ( )

如果为 true，则文本处理在后台线程中完成。

int visible_characters = -1

• void set_visible_characters ( int value )

• int get_visible_characters ( )

要显示的字符数。如果设置为 -1，则显示所有字符。这用于在对话框中为显示的文本设置动画。

注意：设置该属性会相应地更新 visible_ratio。

VisibleCharactersBehavior visible_characters_behavior = 0

• void set_visible_characters_behavior ( VisibleCharactersBehavior value )

• VisibleCharactersBehavior get_visible_characters_behavior ( )

设置 visible_characters 或 visible_ratio 被设置时的裁剪行为。有关详细信息，请参阅 VisibleCharactersBehavior。

float visible_ratio = 1.0

• void set_visible_ratio ( float value )

• float get_visible_ratio ( )

相对于字符总数（参见 get_total_character_count），要显示的字符的占比。如果设置为 1.0，则显示所有字符。如果设置为 0.5，则只显示一半的字符。这用于在对话框中为显示的文本设置动画。

注意：设置该属性会相应地更新 visible_characters。

方法说明

void add_image ( Texture2D image, int width=0, int height=0, Color color=Color(1, 1, 1, 1), InlineAlignment inline_align=5, Rect2 region=Rect2(0, 0, 0, 0), Variant key=null, bool pad=false, String tooltip=””, bool size_in_percent=false )

将图像的开始和结束标签添加到标签栈中，可选择提供 width 和 height 来调整图像大小，提供 color 来给图像混色， region 只使用图像的一部分。

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

如果未设置 width 和 height，但设置了 region，则将使用该区域的矩形。

key 是一个可选标识符，可用于通过 update_image 修改图像。

如果设置了 pad，并且该图像小于 width 和 height 指定的大小，则添加图像填充以匹配大小而不是放大图像。

如果设置了 size_in_percent，则 width 和 height 值是控件宽度的百分比而不是像素。

void add_text ( String text )

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

void append_text ( String bbcode )

解析 bbcode 并根据需要将标签添加到标签栈中。

注意：使用该方法，无法关闭在之前的 append_text 调用中打开的标签。这样做是为了提高性能，尤其是在更新大型 RichTextLabel 时，因为每次都重建整个 BBCode 会比较慢。如果你绝对需要在接下来的方法调用中关闭标签，请追加 text 而不是使用 append_text。

void clear ( )

清空标签栈。

注意：这个方法不会修改 text，但将 text 设置为空字符串也能清空标签栈。

void deselect ( )

清除当前选择。

int get_character_line ( int character )

返回提供的字符位置的行号。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

int get_character_paragraph ( int character )

返回提供的字符位置的段号。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

int get_content_height ( ) const

返回内容的高度。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

int get_content_width ( ) const

返回内容的宽度。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

int get_line_count ( ) const

返回文本中的总行数。自动换行的文本计为多行。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

float get_line_offset ( int line )

返回位于提供的索引处的行的垂直偏移量。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

PopupMenu get_menu ( ) const

返回该 RichTextLabel 的 PopupMenu。默认情况下，这个菜单会在右键单击 RichTextLabel 时显示。

你可以加入自定义的菜单项，或者移除标准菜单项。请确保你的 ID 与标准 ID 不冲突（见 MenuItems）。例如：

GDScriptC#

func _ready():
    var menu = get_menu()
    # 移除“全选”菜单项。
    menu.remove_item(MENU_SELECT_ALL)
    # 添加自定义菜单项。
    menu.add_separator()
    menu.add_item("制作文本副本", MENU_MAX + 1)
    # 连接回调。
    menu.id_pressed.connect(_on_item_pressed)
func _on_item_pressed(id):
    if id == MENU_MAX + 1:
        add_text("\n" + get_parsed_text())

public override void _Ready()
{
    var menu = GetMenu();
    // 移除“全选”菜单项。
    menu.RemoveItem(RichTextLabel.MenuItems.SelectAll);
    // 添加自定义菜单项。
    menu.AddSeparator();
    menu.AddItem("制作文本副本", RichTextLabel.MenuItems.Max + 1);
    // 添加事件处理器。
    menu.IdPressed += OnItemPressed;
}
public void OnItemPressed(int id)
{
    if (id == TextEdit.MenuItems.Max + 1)
    {
        AddText("\n" + GetParsedText());
    }
}

警告：这是必要的内部节点，将其移除或释放可能导致崩溃。如果你想要将其隐藏，或者隐藏其子节点，请使用其 Window.visible 属性。

int get_paragraph_count ( ) const

返回段落的总数（换行符或标记栈文本标签中的 p 标签）。自动换行的文本视为一个段落。

float get_paragraph_offset ( int paragraph )

返回位于提供的索引处的段落的垂直偏移量。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

String get_parsed_text ( ) const

返回没有 BBCode 标记的文本。

String get_selected_text ( ) const

返回当前选中的文本。不包括 BBCode。

int get_selection_from ( ) const

如果选区处于活动状态，则返回当前选区第一个字符的索引，否则返回 -1。不包括 BBCode。

int get_selection_to ( ) const

如果选择处于活动状态，则返回当前选区最后一个字符的索引，否则返回 -1。不包括 BBCode。

int get_total_character_count ( ) const

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

VScrollBar get_v_scroll_bar ( )

返回垂直滚动条。

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

int get_visible_line_count ( ) const

返回可见行数。

注意：如果启用了 threaded，则此方法返回的是文档已加载部分的值。请使用 is_ready 或 finished 来确定文档是否已完全加载。

int get_visible_paragraph_count ( ) const

返回可见段落的数量。如果段落中至少有一行是可见的，则该段落被认为是可见的。

注意：如果启用了 threaded，则此方法返回文档已加载部分的值。使用 is_ready 或 finished 来确定文档是否已完全加载。

void install_effect ( Variant effect )

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

bool is_menu_visible ( ) const

返回菜单是否可见。请使用这个方法来代替 get_menu().visible，可以提高性能（因为避免了菜单的创建）。

bool is_ready ( ) const

如果启用了 threaded，则在后台线程完成文本处理后，返回 true，否则始终返回 true。

void menu_option ( int option )

执行 MenuItems 枚举中定义的给定操作。

void newline ( )

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

void parse_bbcode ( String bbcode )

append_text 的赋值版本。清空标签栈并插入新内容。

Dictionary parse_expressions_for_values ( PackedStringArray expressions )

将 BBCode 参数 expressions 解析为字典。

void pop ( )

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

void pop_all ( )

终止由 push_* 方法打开的所有标签。

void pop_context ( )

终止上一次 push_context 调用后打开的标签（包括上下文标记）；或者如果堆栈上没有上下文标记，则终止所有标签。

void push_bgcolor ( Color bgcolor )

向标签栈中添加 [bgcolor] 标签。

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_context ( )

将上下文标记添加到标记堆栈。请参阅 pop_context。

void push_customfx ( RichTextEffect effect, Dictionary env )

将一个自定义效果标签添加到标签栈。效果不需要在 custom_effects 中。环境被直接传入给效果。

void push_dropcap ( String string, Font font, int size, Rect2 dropcap_margins=Rect2(0, 0, 0, 0), Color color=Color(1, 1, 1, 1), int outline_size=0, Color outline_color=Color(0, 0, 0, 0) )

将 [dropcap] 标签添加到标签堆栈中。首字下沉是一种装饰性元素，位于段落开头，比其余文本要大。

void push_fgcolor ( Color fgcolor )

向标签栈中添加 [fgcolor] 标签。

void push_font ( Font font, int font_size=0 )

在标签栈中添加 [font] 标签。在其有效期内覆盖默认字体。

将 font_size 设置为 0 会使用默认字体大小。

void push_font_size ( int font_size )

在标签栈中添加 [font_size] 标签。在其有效期内覆盖默认字体大小。

void push_hint ( String description )

向标签栈中添加 [hint] 标签。类似于 BBCode 的 [hint=something]{text}[/hint]。

void push_indent ( int level )

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

void push_italics ( )

在标签栈中添加 [font] 标签，字体为斜体。如果当前不在 [b] 标签中，则与添加 [i] 标签相同。

void push_language ( String language )

添加用于文本塑形算法和 Open-Type 字体功能的语言代码。

void push_list ( int level, ListType type, bool capitalize, String bullet=”•” )

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

void push_meta ( Variant data )

在标签栈中添加元标签。类似于 BBCode 的 [url=something]{text}[/url]，但支持非 String 元数据类型。

void push_mono ( )

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

void push_normal ( )

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

void push_outline_color ( Color color )

在标签栈中添加 [outline_color] 标签。在其有效期内为文本添加轮廓。

void push_outline_size ( int outline_size )

在标签栈中添加 [outline_size] 标签。在其有效期内覆盖默认的文本轮廓大小。

void push_paragraph ( HorizontalAlignment alignment, TextDirection base_direction=0, String language=””, StructuredTextParser st_parser=0, BitField<JustificationFlag> justification_flags=163, PackedFloat32Array tab_stops=PackedFloat32Array() )

向标签栈中添加 [p] 标签。

void push_strikethrough ( )

向标签栈中添加 [s] 标签。

void push_table ( int columns, InlineAlignment inline_align=0, int align_to_row=-1 )

向标签栈中添加 [table=columns,inline_align] 标签。

void push_underline ( )

向标签栈中添加 [u] 标签。

bool remove_paragraph ( int paragraph )

从标签中移除一段内容。如果该段落存在，则返回 true。

paragraph 参数是要移除的段落的索引，它可以在 [0, get_paragraph_count() - 1] 区间内取值。

void scroll_to_line ( int line )

滚动窗口，让第一行与 line 匹配。

void scroll_to_paragraph ( int paragraph )

滚动窗口，让第一行与 paragraph 的第一行匹配。

void scroll_to_selection ( )

滚动到当前选区的开头。

void select_all ( )

全选文本。

如果 selection_enabled 为 false，则不会进行选择。

void set_cell_border_color ( Color color )

设置表格的单元格边框颜色。

void set_cell_padding ( Rect2 padding )

设置表格的单元格内边距。

void set_cell_row_background_color ( Color odd_row_bg, Color even_row_bg )

设置某个表格单元格的颜色。可以为交替行指定单独的颜色。

void set_cell_size_override ( Vector2 min_size, Vector2 max_size )

设置某个表格单元格的最小和最大尺寸覆盖。

void set_table_column_expand ( int column, bool expand, int ratio=1 )

编辑选定列的扩展选项。如果 expand 为 true，则该列按其扩展比率相对于其他列的比率进行扩展。

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

如果 expand 为 false，则该列将不会对总比率产生影响。

void update_image ( Variant key, BitField<ImageUpdateMask> mask, Texture2D image, int width=0, int height=0, Color color=Color(1, 1, 1, 1), InlineAlignment inline_align=5, Rect2 region=Rect2(0, 0, 0, 0), bool pad=false, String tooltip=””, bool size_in_percent=false )

使用键 key 更新已有图像。仅更新 mask 位指定的属性。请参阅 add_image。

主题属性说明

Color default_color = Color(1, 1, 1, 1)

默认文本颜色。

Color font_outline_color = Color(1, 1, 1, 1)

文本轮廓的默认色调。

Color font_selected_color = Color(0, 0, 0, 0)

选中文本的颜色，当 selection_enabled 为 true 时使用。如果等于 Color(0, 0, 0, 0)，则它将被忽略。

Color font_shadow_color = Color(0, 0, 0, 0)

字体阴影的颜色。

Color selection_color = Color(0.1, 0.1, 1, 0.8)

选择框的颜色。

Color table_border = Color(0, 0, 0, 0)

默认单元格边框颜色。

Color table_even_row_bg = Color(0, 0, 0, 0)

偶数行的默认背景色。

Color table_odd_row_bg = Color(0, 0, 0, 0)

奇数行的默认背景色。

int line_separation = 0

行之间的垂直空间。

int outline_size = 0

文字轮廓的大小。

注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。

int shadow_offset_x = 1

字体阴影的水平偏移量。

int shadow_offset_y = 1

字体阴影的垂直偏移。

int shadow_outline_size = 1

阴影轮廓的大小。

int table_h_separation = 3

表中元素的水平间距。

int table_v_separation = 3

表中元素的垂直间距。

int text_highlight_h_padding = 3

由 [fgcolor] 和 [bgcolor] 标记绘制的框周围的水平填充。这不会影响文本选择的外观。

int text_highlight_v_padding = 3

由 [fgcolor] 和 [bgcolor] 标记绘制的框周围的垂直填充。这不会影响文本选择的外观。

Font bold_font

用于粗体字的字体。

Font bold_italics_font

用于粗斜体文字的字体。

Font italics_font

用于斜体字的字体。

Font mono_font

用于等宽文本的字体。

Font normal_font

默认的文本字体。

int bold_font_size

用于粗体文本的字体大小。

int bold_italics_font_size

用于粗斜体文本的字体大小。

int italics_font_size

用于斜体文本的字体大小。

int mono_font_size

用于等宽文本的字体大小。

int normal_font_size

默认文本字体大小。

StyleBox focus

该 RichTextLabel 处于聚焦状态时使用的背景。focus StyleBox 显示在基础 StyleBox 之上，所以应该使用部分透明的 StyleBox，确保基础 StyleBox 仍然可见。代表轮廓或下划线的 StyleBox 可以很好地实现这个目的。要禁用聚焦的视觉效果，请指定 StyleBoxEmpty 资源。请注意，禁用聚焦的视觉效果会影响使用键盘/手柄进行导航的可用性，所以出于可访问性的原因，不建议这样做。

StyleBox normal

RichTextLabel 的正常背景。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.