Label

繼承： Control < CanvasItem < Node < Object

用於顯示純文字的控制項。

說明

用於顯示純文字的控制項。可以控制水平和垂直對齊方式以及文字在節點包圍框內的換行方式。不支援粗體、斜體等富文字格式。這種需求請改用 RichTextLabel。

教學

• 2D Dodge The Creeps 範例

屬性

AutowrapMode	autowrap_mode	0
BitField[LineBreakFlag]	autowrap_trim_flags	192
bool	clip_text	false
String	ellipsis_char	"…"
HorizontalAlignment	horizontal_alignment	0
BitField[JustificationFlag]	justification_flags	163
LabelSettings	label_settings
String	language	""
int	lines_skipped	0
int	max_lines_visible	-1
MouseFilter	mouse_filter	2 (overrides Control)
String	paragraph_separator	"\\n"
BitField[SizeFlags]	size_flags_vertical	4 (overrides Control)
StructuredTextParser	structured_text_bidi_override	0
Array	structured_text_bidi_override_options	[]
PackedFloat32Array	tab_stops	PackedFloat32Array()
String	text	""
TextDirection	text_direction	0
OverrunBehavior	text_overrun_behavior	0
bool	uppercase	false
VerticalAlignment	vertical_alignment	0
int	visible_characters	-1
VisibleCharactersBehavior	visible_characters_behavior	0
float	visible_ratio	1.0

方法

Rect2	get_character_bounds(pos: int) const
int	get_line_count() const
int	get_line_height(line: int = -1) const
int	get_total_character_count() const
int	get_visible_line_count() const

主題屬性

Color	font_color	Color(1, 1, 1, 1)
Color	font_outline_color	Color(0, 0, 0, 1)
Color	font_shadow_color	Color(0, 0, 0, 0)
int	line_spacing	3
int	outline_size	0
int	paragraph_spacing	0
int	shadow_offset_x	1
int	shadow_offset_y	1
int	shadow_outline_size	1
Font	font
int	font_size
StyleBox	focus
StyleBox	normal

---

屬性說明

AutowrapMode autowrap_mode = 0 🔗

• void set_autowrap_mode(value: AutowrapMode)

• AutowrapMode get_autowrap_mode()

If set to something other than TextServer.AUTOWRAP_OFF, the text gets wrapped inside the node's bounding rectangle. If you resize the node, it will change its height automatically to show all the text.

---

BitField[LineBreakFlag] autowrap_trim_flags = 192 🔗

• void set_autowrap_trim_flags(value: BitField[LineBreakFlag])

• BitField[LineBreakFlag] get_autowrap_trim_flags()

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

---

bool clip_text = false 🔗

• void set_clip_text(value: bool)

• bool is_clipping_text()

如果為 true，Label 將僅顯示位於其邊界矩形內部的文字，並將水平裁剪文字。

---

String ellipsis_char = "…" 🔗

• void set_ellipsis_char(value: String)

• String get_ellipsis_char()

Ellipsis character used for text clipping.

---

HorizontalAlignment horizontal_alignment = 0 🔗

• void set_horizontal_alignment(value: HorizontalAlignment)

• HorizontalAlignment get_horizontal_alignment()

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

---

BitField[JustificationFlag] justification_flags = 163 🔗

• void set_justification_flags(value: BitField[JustificationFlag])

• BitField[JustificationFlag] get_justification_flags()

Line fill alignment rules.

---

LabelSettings label_settings 🔗

• void set_label_settings(value: LabelSettings)

• LabelSettings get_label_settings()

LabelSettings 資源，可以在多個 Label 節點之間共用。優先於主題屬性。

---

String language = "" 🔗

• void set_language(value: String)

• String get_language()

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

---

int lines_skipped = 0 🔗

• void set_lines_skipped(value: int)

• int get_lines_skipped()

The number of the lines ignored and not displayed from the start of the text value.

---

int max_lines_visible = -1 🔗

• void set_max_lines_visible(value: int)

• int get_max_lines_visible()

限制節點在螢幕上顯示的文字行數。

---

String paragraph_separator = "\\n" 🔗

• void set_paragraph_separator(value: String)

• String get_paragraph_separator()

String used as a paragraph separator. Each paragraph is processed independently, in its own BiDi context.

---

StructuredTextParser structured_text_bidi_override = 0 🔗

• void set_structured_text_bidi_override(value: StructuredTextParser)

• StructuredTextParser get_structured_text_bidi_override()

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

---

Array structured_text_bidi_override_options = [] 🔗

• void set_structured_text_bidi_override_options(value: Array)

• Array get_structured_text_bidi_override_options()

設定 BiDi 覆蓋的附加選項。

---

PackedFloat32Array tab_stops = PackedFloat32Array() 🔗

• void set_tab_stops(value: PackedFloat32Array)

• PackedFloat32Array get_tab_stops()

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

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 = "" 🔗

• void set_text(value: String)

• String get_text()

要在螢幕上顯示的文字。

---

TextDirection text_direction = 0 🔗

• void set_text_direction(value: TextDirection)

• TextDirection get_text_direction()

基礎文字書寫方向。

---

OverrunBehavior text_overrun_behavior = 0 🔗

• void set_text_overrun_behavior(value: OverrunBehavior)

• OverrunBehavior get_text_overrun_behavior()

The clipping behavior when the text exceeds the node's bounding rectangle.

---

bool uppercase = false 🔗

• void set_uppercase(value: bool)

• bool is_uppercase()

如果為 true，所有文字都將顯示為大寫。

---

VerticalAlignment vertical_alignment = 0 🔗

• void set_vertical_alignment(value: VerticalAlignment)

• VerticalAlignment get_vertical_alignment()

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 🔗

• void set_visible_characters_behavior(value: VisibleCharactersBehavior)

• VisibleCharactersBehavior get_visible_characters_behavior()

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。

---

方法說明

Rect2 get_character_bounds(pos: int) const 🔗

Returns the bounding rectangle of the character at position pos in the label's local coordinate system. If the character is a non-visual character or pos is outside the valid range, an empty Rect2 is returned. If the character is a part of a composite grapheme, the bounding rectangle of the whole grapheme is returned.

---

int get_line_count() const 🔗

返回該 Label 的文字行數。

---

int get_line_height(line: int = -1) const 🔗

返回行 line 的高度。

如果 line 被設定為 -1 ，則返回最大的行高。

如果沒有行，則返回字形大小，單位是圖元。

---

int get_total_character_count() const 🔗

返回文字中可列印的字元總數，不包括空格和分行符號。

---

int get_visible_line_count() const 🔗

返回顯示的行數。如果 Label 的高度目前無法顯示所有的行數，將會有用。

---

主題屬性說明

Color font_color = Color(1, 1, 1, 1) 🔗

Label 標籤的預設文字顏色 Color。

---

Color font_outline_color = Color(0, 0, 0, 1) 🔗

文字輪廓的顏色。

---

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

文字陰影效果的顏色 Color。

---

int line_spacing = 3 🔗

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

---

int outline_size = 0 🔗

Text outline size.

Note: If using a font with FontFile.multichannel_signed_distance_field enabled, its FontFile.msdf_pixel_range must be set to at least twice the value of outline_size for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.

Note: Using a value that is larger than half the font size is not recommended, as the font outline may fail to be fully closed in this case.

---

int paragraph_spacing = 0 🔗

Vertical space between paragraphs. Added on top of line_spacing.

---

int shadow_offset_x = 1 🔗

文字陰影的水平偏移。

---

int shadow_offset_y = 1 🔗

文字陰影的垂直偏移。

---

int shadow_outline_size = 1 🔗

陰影輪廓的大小。

---

Font font 🔗

用於標籤 Label 文字的字形 Font。

---

int font_size 🔗

該 Label 文字的字形大小。

---

StyleBox focus 🔗

StyleBox used when the Label is focused (when used with assistive apps).

---

StyleBox normal 🔗

為 Label 設定背景樣式盒 StyleBox。