Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

RichTextLabel

繼承： Control < CanvasItem < Node < Object

用於顯示文字的控制項，文字中能夠包含不同的字形樣式、圖片以及基礎格式。

說明

A control for displaying text that can contain custom fonts, images, and basic formatting. RichTextLabel manages these as an internal tag stack. It also adapts itself to given width/heights.

Note: newline(), push_paragraph(), "\n", "\r\n", p tag, and alignment tags start a new paragraph. Each paragraph is processed independently, in its own BiDi context. If you want to force line wrapping within paragraph, any other line breaking character can be used, for example, Form Feed (U+000C), Next Line (U+0085), Line Separator (U+2028).

Note: Assignments to text clear the tag stack and reconstruct it from the property's contents. Any edits made to text will erase previous edits made from other manual sources such as append_text() and the push_* / pop() methods.

Note: RichTextLabel doesn't support entangled BBCode tags. For example, instead of using [b]bold[i]bold italic[/b]italic[/i], use [b]bold[i]bold italic[/i][/b][i]italic[/i].

Note: push_*/pop_* functions won't affect BBCode.

Note: While bbcode_enabled is enabled, alignment tags such as [center] will take priority over the horizontal_alignment setting which determines the default text alignment.

教學

屬性

AutowrapMode

autowrap_mode

3

BitField[LineBreakFlag]

autowrap_trim_flags

192

bool

bbcode_enabled

false

bool

clip_contents

true (overrides Control)

bool

context_menu_enabled

false

Array

custom_effects

[]

bool

deselect_on_focus_loss_enabled

true

bool

drag_and_drop_selection_enabled

true

bool

fit_content

false

FocusMode

focus_mode

3 (overrides Control)

bool

hint_underlined

true

HorizontalAlignment

horizontal_alignment

0

BitField[JustificationFlag]

justification_flags

163

String

language

""

bool

meta_underlined

true

int

progress_bar_delay

1000

bool

scroll_active

true

bool

scroll_following

false

bool

scroll_following_visible_characters

false

bool

selection_enabled

false

bool

shortcut_keys_enabled

true

StructuredTextParser

structured_text_bidi_override

0

Array

structured_text_bidi_override_options

[]

int

tab_size

4

PackedFloat32Array

tab_stops

PackedFloat32Array()

String

text

""

TextDirection

text_direction

0

bool

threaded

false

VerticalAlignment

vertical_alignment

0

int

visible_characters

-1

VisibleCharactersBehavior

visible_characters_behavior

0

float

visible_ratio

1.0

方法

void

add_hr(width: int = 90, height: int = 2, color: Color = Color(1, 1, 1, 1), alignment: HorizontalAlignment = 1, width_in_percent: bool = true, height_in_percent: bool = false)

void

add_image(image: Texture2D, width: float = 0, height: float = 0, color: Color = Color(1, 1, 1, 1), inline_align: InlineAlignment = 5, region: Rect2 = Rect2(0, 0, 0, 0), key: Variant = null, pad: bool = false, tooltip: String = "", width_unit: ImageUnit = 0, height_unit: ImageUnit = 0, alt_text: String = "")

void

add_text(text: String)

void

append_text(bbcode: String)

void

clear()

void

deselect()

int

get_character_line(character: int)

int

get_character_paragraph(character: int)

int

get_content_height() const

int

get_content_width() const

int

get_line_count() const

int

get_line_height(line: int) const

float

get_line_offset(line: int)

Vector2i

get_line_range(line: int)

int

get_line_width(line: int) const

PopupMenu

get_menu() const

int

get_paragraph_count() const

float

get_paragraph_offset(paragraph: int)

String

get_parsed_text() const

String

get_selected_text() const

int

get_selection_from() const

float

get_selection_line_offset() const

int

get_selection_to() const

int

get_total_character_count() const

VScrollBar

get_v_scroll_bar()

Rect2i

get_visible_content_rect() const

int

get_visible_line_count() const

int

get_visible_paragraph_count() const

void

install_effect(effect: Variant)

bool

invalidate_paragraph(paragraph: int)

bool

is_finished() const

bool

is_menu_visible() const

bool

is_ready() const

void

menu_option(option: int)

void

newline()

void

parse_bbcode(bbcode: String)

Dictionary

parse_expressions_for_values(expressions: PackedStringArray)

void

pop()

void

pop_all()

void

pop_context()

void

push_bgcolor(bgcolor: Color)

void

push_bold()

void

push_bold_italics()

void

push_cell()

void

push_color(color: Color)

void

push_context()

void

push_customfx(effect: RichTextEffect, env: Dictionary)

void

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

void

push_fgcolor(fgcolor: Color)

void

push_font(font: Font, font_size: int = 0)

void

push_font_size(font_size: int)

void

push_hint(description: String)

void

push_indent(level: int)

void

push_italics()

void

push_language(language: String)

void

push_list(level: int, type: ListType, capitalize: bool, bullet: String = "•")

void

push_meta(data: Variant, underline_mode: MetaUnderline = 1, tooltip: String = "")

void

push_mono()

void

push_normal()

void

push_outline_color(color: Color)

void

push_outline_size(outline_size: int)

void

push_paragraph(alignment: HorizontalAlignment, base_direction: TextDirection = 0, language: String = "", st_parser: StructuredTextParser = 0, justification_flags: BitField[JustificationFlag] = 163, tab_stops: PackedFloat32Array = PackedFloat32Array())

void

push_strikethrough(color: Color = Color(0, 0, 0, 0))

void

push_table(columns: int, inline_align: InlineAlignment = 0, align_to_row: int = -1, name: String = "")

void

push_underline(color: Color = Color(0, 0, 0, 0))

void

reload_effects()

bool

remove_paragraph(paragraph: int, no_invalidate: bool = false)

void

scroll_to_line(line: int)

void

scroll_to_paragraph(paragraph: int)

void

scroll_to_selection()

void

select_all()

void

set_cell_border_color(color: Color)

void

set_cell_padding(padding: Rect2)

void

set_cell_row_background_color(odd_row_bg: Color, even_row_bg: Color)

void

set_cell_size_override(min_size: Vector2, max_size: Vector2)

void

set_table_column_expand(column: int, expand: bool, ratio: int = 1, shrink: bool = true)

void

set_table_column_name(column: int, name: String)

void

update_image(key: Variant, mask: BitField[ImageUpdateMask], image: Texture2D, width: float = 0, height: float = 0, color: Color = Color(1, 1, 1, 1), inline_align: InlineAlignment = 5, region: Rect2 = Rect2(0, 0, 0, 0), pad: bool = false, tooltip: String = "", width_unit: ImageUnit = 0, height_unit: ImageUnit = 0)

主題屬性

Color

default_color

Color(1, 1, 1, 1)

Color

font_outline_color

Color(0, 0, 0, 1)

Color

font_selected_color

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

int

paragraph_separation

0

int

shadow_offset_x

1

int

shadow_offset_y

1

int

shadow_outline_size

1

int

strikethrough_alpha

50

int

table_h_separation

3

int

table_v_separation

3

int

text_highlight_h_padding

3

int

text_highlight_v_padding

3

int

underline_alpha

50

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

Texture2D

horizontal_rule

StyleBox

focus

StyleBox

normal

訊號

finished() 🔗

Triggered when the document is fully loaded.

Note: This can happen before the text is processed for drawing. Scrolling values may not be valid until the document is drawn for the first time after this signal.

meta_clicked(meta: Variant) 🔗

Triggered when the user clicks on content between meta (URL) tags. If the meta is defined in BBCode, e.g. [url={"key": "value"}]Text[/url], then the parameter for this signal will always be a String type. If a particular type or an object is desired, the push_meta() method must be used to manually insert the data into the tag stack. Alternatively, you can convert the String input to the desired type based on its contents (such as calling JSON.parse() on it).

For example, the following method can be connected to meta_clicked to open clicked URLs using the user's default web browser:

# This assumes RichTextLabel's `meta_clicked` signal was connected to
# the function below using the signal connection dialog.
func _richtextlabel_on_meta_clicked(meta):
    # `meta` is of Variant type, so convert it to a String to avoid script errors at run-time.
    OS.shell_open(str(meta))

meta_hover_ended(meta: Variant) 🔗

當滑鼠退出元標籤時觸發。

meta_hover_started(meta: Variant) 🔗

當滑鼠進入元標籤時觸發。

列舉

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 列舉的大小。

enum MetaUnderline: 🔗

MetaUnderline META_UNDERLINE_NEVER = 0

Meta tag does not display an underline, even if meta_underlined is true.

MetaUnderline META_UNDERLINE_ALWAYS = 1

If meta_underlined is true, meta tag always display an underline.

MetaUnderline META_UNDERLINE_ON_HOVER = 2

If meta_underlined is true, meta tag display an underline when the mouse cursor is over it.

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_UNIT = 128

If this bit is set, update_image() changes the units used to calculate image size.

enum ImageUnit: 🔗

ImageUnit IMAGE_UNIT_PIXEL = 0

Images drawn with this unit will be in pixels.

ImageUnit IMAGE_UNIT_PERCENT = 1

Images drawn with this unit will be in percentages of the control width.

ImageUnit IMAGE_UNIT_EM = 2

Images drawn with this unit will be in percentages of the surrounding font size.

屬性說明

AutowrapMode autowrap_mode = 3 🔗

If set to something other than TextServer.AUTOWRAP_OFF, the text gets wrapped inside the node's bounding rectangle.

Note: RichTextLabels with autowrapping and fit_content enabled must have a custom maximum width configured to work correctly, either through the RichTextLabel's own Control.custom_maximum_size or as a result of a propagated maximum size from a parent Control with Control.propagate_maximum_size enabled.

BitField[LineBreakFlag] autowrap_trim_flags = 192 🔗

Autowrap space trimming flags. See TextServer.BREAK_TRIM_START_EDGE_SPACES and TextServer.BREAK_TRIM_END_EDGE_SPACES for more info.

bool bbcode_enabled = false 🔗

  • void set_use_bbcode(value: bool)

  • bool is_using_bbcode()

If true, the label uses BBCode formatting.

Note: This only affects the contents of text, not the tag stack.

bool context_menu_enabled = false 🔗

  • void set_context_menu_enabled(value: bool)

  • bool is_context_menu_enabled()

為 true 時按右鍵會顯示本文功能表。

Array custom_effects = [] 🔗

  • void set_effects(value: Array)

  • Array get_effects()

目前配置的自訂效果。這是一個RichTextEffect的陣列。

要新增一個自訂效果，使用install_effect()會更方便。

bool deselect_on_focus_loss_enabled = true 🔗

  • void set_deselect_on_focus_loss_enabled(value: bool)

  • bool is_deselect_on_focus_loss_enabled()

如果為 true，則在丟失焦點時會取消選中文字。

bool drag_and_drop_selection_enabled = true 🔗

  • void set_drag_and_drop_selection_enabled(value: bool)

  • bool is_drag_and_drop_selection_enabled()

如果為 true，則允許拖放選中的文字。

bool fit_content = false 🔗

  • void set_fit_content(value: bool)

  • bool is_fit_content_enabled()

If true, the label's minimum size will be automatically updated to fit its content, matching the behavior of Label.

Note: RichTextLabels with autowrapping and fit_content enabled must have a custom maximum width configured to work correctly, either through the RichTextLabel's own Control.custom_maximum_size or as a result of a propagated maximum size from a parent Control with Control.propagate_maximum_size enabled.

bool hint_underlined = true 🔗

  • void set_hint_underline(value: bool)

  • bool is_hint_underlined()

If true, the label underlines hint tags such as [hint=description]{text}[/hint].

HorizontalAlignment horizontal_alignment = 0 🔗

Controls the text's horizontal alignment. Supports left, center, right, and fill (also known as justify).

BitField[JustificationFlag] justification_flags = 163 🔗

Line fill alignment rules.

String language = "" 🔗

Language code used for line-breaking and text shaping algorithms. If left empty, the current locale is used instead.

bool meta_underlined = true 🔗

  • void set_meta_underline(value: bool)

  • bool is_meta_underlined()

If true, the label underlines meta tags such as [url]{text}[/url]. These tags can call a function when clicked if meta_clicked is connected to a function.

int progress_bar_delay = 1000 🔗

  • void set_progress_bar_delay(value: int)

  • int get_progress_bar_delay()

載入進度條顯示的延遲時間，單位為毫秒。將其設定為 -1 將完全禁用進度條。

注意：僅當 threaded 已啟用時才會顯示進度條。

bool scroll_active = true 🔗

  • void set_scroll_active(value: bool)

  • bool is_scroll_active()

如果為 true，則捲軸可見。將此設定為 false 不會完全阻止滾動。見scroll_to_line()。

bool scroll_following = false 🔗

  • void set_scroll_follow(value: bool)

  • bool is_scroll_following()

如果為 true，則視窗向下滾動以自動顯示新內容。

bool scroll_following_visible_characters = false 🔗

  • void set_scroll_follow_visible_characters(value: bool)

  • bool is_scroll_following_visible_characters()

If true, the window scrolls to display the last visible line when visible_characters or visible_ratio is changed.

bool selection_enabled = false 🔗

  • void set_selection_enabled(value: bool)

  • bool is_selection_enabled()

如果為 true，標籤允許文字選擇。

bool shortcut_keys_enabled = true 🔗

  • void set_shortcut_keys_enabled(value: bool)

  • bool is_shortcut_keys_enabled()

為 true 時，即使本文選單已被禁用，也會啟用該本文選單的快捷鍵。

StructuredTextParser structured_text_bidi_override = 0 🔗

為結構化文字設定 BiDi 演算法覆蓋。

Array structured_text_bidi_override_options = [] 🔗

  • void set_structured_text_bidi_override_options(value: Array)

  • Array get_structured_text_bidi_override_options()

設定 BiDi 覆蓋的附加選項。

int tab_size = 4 🔗

  • void set_tab_size(value: int)

  • int get_tab_size()

與單個定位字元長度關聯的空格數。不影響文字標籤中的 \t，只影響縮進標籤。

PackedFloat32Array tab_stops = PackedFloat32Array() 🔗

將文字與給定的定位停駐點對齊。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedFloat32Array for more details.

String text = "" 🔗

The label's text in BBCode format. Is not representative of manual modifications to the internal tag stack. Erases changes made by other methods when edited.

Note: If bbcode_enabled is true, it is unadvised to use the += operator with text (e.g. text += "some string") as it replaces the whole text and can cause slowdowns. It will also erase all BBCode that was added to stack using push_* methods. Use append_text() for adding text instead, unless you absolutely need to close a tag that was opened in an earlier method call.

TextDirection text_direction = 0 🔗

基礎文字書寫方向。

bool threaded = false 🔗

  • void set_threaded(value: bool)

  • bool is_threaded()

如果為 true，則文字處理在後臺執行緒中完成。

VerticalAlignment vertical_alignment = 0 🔗

Controls the text's vertical alignment. Supports top, center, bottom, and fill.

int visible_characters = -1 🔗

  • void set_visible_characters(value: int)

  • int get_visible_characters()

The number of characters to display. If set to -1, all characters are displayed. This can be useful when animating the text appearing in a dialog box.

Note: Setting this property updates visible_ratio accordingly.

Note: Characters are counted as Unicode codepoints. A single visible grapheme may contain multiple codepoints (e.g. certain emoji use three codepoints). A single codepoint may contain two UTF-16 characters, which are used in C# strings.

VisibleCharactersBehavior visible_characters_behavior = 0 🔗

The clipping behavior when visible_characters or visible_ratio is set.

float visible_ratio = 1.0 🔗

  • void set_visible_ratio(value: float)

  • float get_visible_ratio()

相對於字元總數（參見 get_total_character_count()），要顯示的字元的占比。如果設定為 1.0，則顯示所有字元。如果設定為 0.5，則只顯示一半的字元。這用於在對話方塊中為顯示的文字設定動畫。

注意：設定該屬性會相應地更新 visible_characters。

方法說明

void add_hr(width: int = 90, height: int = 2, color: Color = Color(1, 1, 1, 1), alignment: HorizontalAlignment = 1, width_in_percent: bool = true, height_in_percent: bool = false) 🔗

Adds a horizontal rule that can be used to separate content.

If width_in_percent is set, width values are percentages of the control width instead of pixels.

If height_in_percent is set, height values are percentages of the control width instead of pixels.

void add_image(image: Texture2D, width: float = 0, height: float = 0, color: Color = Color(1, 1, 1, 1), inline_align: InlineAlignment = 5, region: Rect2 = Rect2(0, 0, 0, 0), key: Variant = null, pad: bool = false, tooltip: String = "", width_unit: ImageUnit = 0, height_unit: ImageUnit = 0, alt_text: String = "") 🔗

Adds an image's opening and closing tags to the tag stack, optionally providing a width and height to resize the image, a color to tint the image and a region to only use parts of the image.

If width or height is set to 0, the image size will be adjusted in order to keep the original aspect ratio.

If width and height are not set, but region is, the region's rect will be used.

key is an optional identifier, that can be used to modify the image via update_image().

If pad is set, and the image is smaller than the size specified by width and height, the image padding is added to match the size instead of upscaling.

Parameters width_unit and height_unit determine the units used to calculate the image width and height, respectively.

alt_text is used as the image description for assistive apps.

void add_text(text: String) 🔗

將非 BBCode 解析的原始文字新增到標籤堆疊中。

void append_text(bbcode: String) 🔗

解析 bbcode 並根據需要將標籤新增到標籤堆疊中。

注意：使用該方法，無法關閉在之前的 append_text() 呼叫中打開的標簽。這樣做是為了提高性能，尤其是在更新大型 RichTextLabel 時，因為每次都重建整個 BBCode 會比較慢。如果你絕對需要在接下來的方法呼叫中關閉標籤，請追加 text 而不是使用 append_text()。

void clear() 🔗

Clears the tag stack, causing the label to display nothing.

Note: This method does not affect text, and its contents will show again if the label is redrawn. However, setting text to an empty String also clears the stack.

void deselect() 🔗

清除目前選擇。

int get_character_line(character: int) 🔗

Returns the line number of the character position provided. Line and character numbers are both zero-indexed.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

int get_character_paragraph(character: int) 🔗

Returns the paragraph number of the character position provided. Paragraph and character numbers are both zero-indexed.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

int get_content_height() const 🔗

Returns the height of the content.

Note: This method always returns the full content size, and is not affected by visible_ratio and visible_characters. To get the visible content size, use get_visible_content_rect().

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

int get_content_width() const 🔗

Returns the width of the content.

Note: This method always returns the full content size, and is not affected by visible_ratio and visible_characters. To get the visible content size, use get_visible_content_rect().

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

int get_line_count() const 🔗

Returns the total number of lines in the text. Wrapped text is counted as multiple lines.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

int get_line_height(line: int) const 🔗

Returns the height of the line found at the provided index.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether the document is fully loaded.

float get_line_offset(line: int) 🔗

Returns the vertical offset of the line found at the provided index.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

Vector2i get_line_range(line: int) 🔗

Returns the indexes of the first and last visible characters for the given line, as a Vector2i.

Note: If visible_characters_behavior is set to TextServer.VC_CHARS_BEFORE_SHAPING only visible wrapped lines are counted.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

int get_line_width(line: int) const 🔗

Returns the width of the line found at the provided index.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether the document is fully loaded.

PopupMenu get_menu() const 🔗

返回該 RichTextLabel 的 PopupMenu。預設情況下，這個功能表會在按右鍵 RichTextLabel 時顯示。

你可以加入自訂的功能表專案，或者移除標準功能表專案。請確保你的 ID 與標準 ID 不衝突（見 MenuItems）。例如：

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

警告：這是必要的內部節點，將其移除或釋放可能導致當機。如果你想要將其隱藏，或者隱藏其子節點，請使用其 Window.visible 屬性。

int get_paragraph_count() const 🔗

返回段落的總數（分行符號或標記堆疊文字標籤中的 p 標籤）。自動換行的文字視為一個段落。

float get_paragraph_offset(paragraph: int) 🔗

Returns the vertical offset of the paragraph found at the provided index.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

String get_parsed_text() const 🔗

返回沒有 BBCode 標記的文字。

String get_selected_text() const 🔗

返回目前選中的文字。不包括 BBCode。

int get_selection_from() const 🔗

如果選區處於活動狀態，則返回目前選區第一個字元的索引，否則返回 -1。不包括 BBCode。

float get_selection_line_offset() const 🔗

Returns the current selection vertical line offset if a selection is active, -1.0 otherwise.

int get_selection_to() const 🔗

如果選擇處於活動狀態，則返回目前選區最後一個字元的索引，否則返回 -1。不包括 BBCode。

int get_total_character_count() const 🔗

返回文字標籤的總字元數。不包括 BBCode。

VScrollBar get_v_scroll_bar() 🔗

返回垂直捲動條。

警告：這是一個必需的內部節點，刪除和釋放它可能會導致當機。如果你希望隱藏它或其任何子項，請使用它們的 CanvasItem.visible 屬性。

Rect2i get_visible_content_rect() const 🔗

Returns the bounding rectangle of the visible content.

Note: This method returns a correct value only after the label has been drawn.

extends RichTextLabel

@export var background_panel: Panel

func _ready():
    await draw
    background_panel.position = get_visible_content_rect().position
    background_panel.size = get_visible_content_rect().size

int get_visible_line_count() const 🔗

Returns the number of visible lines.

Note: This method returns a correct value only after the label has been drawn.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

int get_visible_paragraph_count() const 🔗

Returns the number of visible paragraphs. A paragraph is considered visible if at least one of its lines is visible.

Note: This method returns a correct value only after the label has been drawn.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.

void install_effect(effect: Variant) 🔗

Installs a custom effect. This can also be done in the Inspector through the custom_effects property. effect should be a valid RichTextEffect.

Example: With the following script extending from RichTextEffect:

# effect.gd
class_name MyCustomEffect
extends RichTextEffect

var bbcode = "my_custom_effect"

# ...

The above effect can be installed in RichTextLabel from a script:

# rich_text_label.gd
extends RichTextLabel

func _ready():
    install_effect(MyCustomEffect.new())

    # Alternatively, if not using `class_name` in the script that extends RichTextEffect:
    install_effect(preload("res://effect.gd").new())

bool invalidate_paragraph(paragraph: int) 🔗

Invalidates paragraph and all subsequent paragraphs cache.

bool is_finished() const 🔗

如果啟用了 threaded，則在後臺執行緒完成文字處理後，返回 true，否則始終返回 true。

bool is_menu_visible() const 🔗

返回選單是否可見。請使用這個方法來代替 get_menu().visible，可以提高性能（因為避免了選單的建立）。

bool is_ready() const 🔗

已棄用： Use is_finished() instead.

如果啟用了 threaded，則在後臺執行緒完成文字處理後，返回 true，否則始終返回 true。

void menu_option(option: int) 🔗

執行 MenuItems 列舉中定義的給定操作。

void newline() 🔗

在標籤堆疊中新增一個換行標籤。

void parse_bbcode(bbcode: String) 🔗

append_text() 的賦值版本。清空標籤堆疊並插入新內容。

Dictionary parse_expressions_for_values(expressions: PackedStringArray) 🔗

將 BBCode 參數 expressions 解析為字典。

void pop() 🔗

終止目前標籤。使用 push_* 方法之後手動關閉 BBCodes。不需要遵循 add_* 方法。

void pop_all() 🔗

結束由 compute_* 方法建立的計算命令列表。

void pop_context() 🔗

終止上次push_context() 呼叫後開啟的標籤（包括本文標記），或者如果堆疊上沒有本文標記，則終止所有標籤。

void push_bgcolor(bgcolor: Color) 🔗

Adds a [bgcolor] tag to the tag stack.

Note: The background color has padding applied by default, which is controlled using text_highlight_h_padding and text_highlight_v_padding. This can lead to overlapping highlights if background colors are placed on neighboring lines/columns, so consider setting those theme items to 0 if you want to avoid this.

void push_bold() 🔗

Adds a [font] tag with a bold font to the tag stack. This is the same as adding a [b] tag if not currently in a [i] tag.

void push_bold_italics() 🔗

Adds a [font] tag with a bold italics font to the tag stack.

void push_cell() 🔗

Adds a [cell] tag to the tag stack. Must be inside a [table] tag. See push_table() for details. Use set_table_column_expand() to set column expansion ratio, set_cell_border_color() to set cell border, set_cell_row_background_color() to set cell background, set_cell_size_override() to override cell size, and set_cell_padding() to set padding.

void push_color(color: Color) 🔗

Adds a [color] tag to the tag stack.

void push_context() 🔗

將本文標記新增至標記堆疊。請參閱pop_context()。

void push_customfx(effect: RichTextEffect, env: Dictionary) 🔗

將一個自訂效果標籤新增到標籤堆疊。效果不需要在 custom_effects 中。環境被直接傳入給效果。

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

Adds a [dropcap] tag to the tag stack. Drop cap (dropped capital) is a decorative element at the beginning of a paragraph that is larger than the rest of the text.

void push_fgcolor(fgcolor: Color) 🔗

Adds a [fgcolor] tag to the tag stack.

Note: The foreground color has padding applied by default, which is controlled using text_highlight_h_padding and text_highlight_v_padding. This can lead to overlapping highlights if foreground colors are placed on neighboring lines/columns, so consider setting those theme items to 0 if you want to avoid this.

void push_font(font: Font, font_size: int = 0) 🔗

Adds a [font] tag to the tag stack. Overrides default fonts for its duration.

Passing 0 to font_size will use the existing default font size.

void push_font_size(font_size: int) 🔗

Adds a [font_size] tag to the tag stack. Overrides default font size for its duration.

void push_hint(description: String) 🔗

Adds a [hint] tag to the tag stack. Same as BBCode [hint=something]{text}[/hint].

void push_indent(level: int) 🔗

Adds an [indent] tag to the tag stack. Multiplies level by current tab_size to determine new margin length.

void push_italics() 🔗

Adds a [font] tag with an italics font to the tag stack. This is the same as adding an [i] tag if not currently in a [b] tag.

void push_language(language: String) 🔗

語言程式碼，用於文字塑形演算法，如果留空則使用目前區域設定。

void push_list(level: int, type: ListType, capitalize: bool, bullet: String = "•") 🔗

Adds [ol] or [ul] tag to the tag stack. Multiplies level by current tab_size to determine new margin length.

void push_meta(data: Variant, underline_mode: MetaUnderline = 1, tooltip: String = "") 🔗

Adds a meta tag to the tag stack. Similar to the BBCode [url=something]{text}[/url], but supports non-String metadata types.

If meta_underlined is true, meta tags display an underline. This behavior can be customized with underline_mode.

Note: Meta tags do nothing by default when clicked. To assign behavior when clicked, connect meta_clicked to a function that is called when the meta tag is clicked.

void push_mono() 🔗

Adds a [font] tag with a monospace font to the tag stack.

void push_normal() 🔗

Adds a [font] tag with a normal font to the tag stack.

void push_outline_color(color: Color) 🔗

Adds a [outline_color] tag to the tag stack. Adds text outline for its duration.

void push_outline_size(outline_size: int) 🔗

Adds a [outline_size] tag to the tag stack. Overrides default text outline size for its duration.

void push_paragraph(alignment: HorizontalAlignment, base_direction: TextDirection = 0, language: String = "", st_parser: StructuredTextParser = 0, justification_flags: BitField[JustificationFlag] = 163, tab_stops: PackedFloat32Array = PackedFloat32Array()) 🔗

Adds a [p] tag to the tag stack.

void push_strikethrough(color: Color = Color(0, 0, 0, 0)) 🔗

Adds a [s] tag to the tag stack. If color's alpha value is 0.0, the current font's color with its alpha multiplied by strikethrough_alpha is used.

void push_table(columns: int, inline_align: InlineAlignment = 0, align_to_row: int = -1, name: String = "") 🔗

Adds a [table=columns,inline_align] tag to the tag stack. Use set_table_column_expand() to set column expansion ratio. Use push_cell() to add cells. name is used as the table name for assistive apps.

void push_underline(color: Color = Color(0, 0, 0, 0)) 🔗

Adds a [u] tag to the tag stack. If color's alpha value is 0.0, the current font's color with its alpha multiplied by underline_alpha is used.

void reload_effects() 🔗

Reloads custom effects. Useful when custom_effects is modified manually.

bool remove_paragraph(paragraph: int, no_invalidate: bool = false) 🔗

Removes a paragraph of content from the label. Returns true if the paragraph exists.

The paragraph argument is the index of the paragraph to remove, it can take values in the interval [0, get_paragraph_count() - 1].

If no_invalidate is set to true, cache for the subsequent paragraphs is not invalidated. Use it for faster updates if deleted paragraph is fully self-contained (have no unclosed tags), or this call is part of the complex edit operation and invalidate_paragraph() will be called at the end of operation.

void scroll_to_line(line: int) 🔗

滾動視窗，讓第一行與 line 配對。

void scroll_to_paragraph(paragraph: int) 🔗

滾動視窗，讓第一行與 paragraph 的第一行配對。

void scroll_to_selection() 🔗

滾動到目前選區的開頭。

void select_all() 🔗

全選文字。

如果 selection_enabled 為 false，則不會進行選擇。

void set_cell_border_color(color: Color) 🔗

設定表格的儲存格邊框顏色。

void set_cell_padding(padding: Rect2) 🔗

設定表格的儲存格內邊距。

void set_cell_row_background_color(odd_row_bg: Color, even_row_bg: Color) 🔗

設定某個表格儲存格的顏色。可以為交替行指定單獨的顏色。

void set_cell_size_override(min_size: Vector2, max_size: Vector2) 🔗

設定某個表格儲存格的最小和最大尺寸覆蓋。

void set_table_column_expand(column: int, expand: bool, ratio: int = 1, shrink: bool = true) 🔗

編輯選定列的擴充選項。如果 expand 為 true，則該列按其擴展比率相對於其他列的比率進行擴充。

例如，比率為 3 和 4 的兩列，加上 70 圖元的可用寬度，將分別擴充 30 和 40 像素。

如果 expand 為 false，則該列將不會對總比率產生影響。

void set_table_column_name(column: int, name: String) 🔗

Sets table column name for assistive apps.

void update_image(key: Variant, mask: BitField[ImageUpdateMask], image: Texture2D, width: float = 0, height: float = 0, color: Color = Color(1, 1, 1, 1), inline_align: InlineAlignment = 5, region: Rect2 = Rect2(0, 0, 0, 0), pad: bool = false, tooltip: String = "", width_unit: ImageUnit = 0, height_unit: ImageUnit = 0) 🔗

使用鍵key 更新現有映像。僅更多mask 位元指定的屬性。請參閱add_image()。

主題屬性說明

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

預設文字顏色。

Color font_outline_color = Color(0, 0, 0, 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 🔗

Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative.

int outline_size = 0 🔗

文字輪廓的大小。

注意：如果使用啟用了 FontFile.multichannel_signed_distance_field 的字形，其 FontFile.msdf_pixel_range 必須至少設定為 outline_size 的兩倍，輪廓算繪才能看起來正確。否則，輪廓可能會比預期的更早被切斷。

int paragraph_separation = 0 🔗

Additional vertical spacing between paragraphs (in pixels). Spacing is added after the last line. This value can be negative.

int shadow_offset_x = 1 🔗

字形陰影的水平偏移量。

int shadow_offset_y = 1 🔗

字形陰影的垂直偏移。

int shadow_outline_size = 1 🔗

陰影輪廓的大小。

int strikethrough_alpha = 50 🔗

The default strikethrough color transparency (percent). For strikethroughs with a custom color, this theme item is only used if the custom color's alpha is 0.0 (fully transparent).

int table_h_separation = 3 🔗

表中元素的水平間距。

int table_v_separation = 3 🔗

表中元素的垂直間距。

int text_highlight_h_padding = 3 🔗

The horizontal padding around boxes drawn by the [fgcolor] and [bgcolor] tags. This does not affect the appearance of text selection. To avoid any risk of neighboring highlights overlapping each other, set this to 0 to disable padding.

int text_highlight_v_padding = 3 🔗

The vertical padding around boxes drawn by the [fgcolor] and [bgcolor] tags. This does not affect the appearance of text selection. To avoid any risk of neighboring highlights overlapping each other, set this to 0 to disable padding.

int underline_alpha = 50 🔗

The default underline color transparency (percent). For underlines with a custom color, this theme item is only used if the custom color's alpha is 0.0 (fully transparent).

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 🔗

預設文字字形大小。

Texture2D horizontal_rule 🔗

The horizontal rule texture.

StyleBox focus 🔗

The background used when the RichTextLabel is focused. The focus StyleBox is displayed over the base StyleBox, so a partially transparent StyleBox should be used to ensure the base StyleBox remains visible. A StyleBox that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a StyleBoxEmpty resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.

StyleBox normal 🔗

RichTextLabel 的正常背景。