Label

继承： Control < CanvasItem < Node < Object

用于显示纯文本的控件。

描述

A control for displaying plain text. It gives you control over the horizontal and vertical alignment and can wrap the text inside the node's bounding rectangle. It doesn't support bold, italics, or other rich text formatting. For that, use RichTextLabel instead.

Note: A single Label node is not designed to display huge amounts of text. To display large amounts of text in a single node, consider using RichTextLabel instead as it supports features like an integrated scroll bar and threading. RichTextLabel generally performs better when displaying large amounts of text (several pages or more).

教程

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

如果设置为 TextServer.AUTOWRAP_OFF 以外的值，则文本将在节点的边界矩形内自动换行。如果你调整节点大小，就会自动更改其高度，从而显示所有文本。

---

BitField[LineBreakFlag] autowrap_trim_flags = 192 🔗

• void set_autowrap_trim_flags(value: BitField[LineBreakFlag])

• BitField[LineBreakFlag] get_autowrap_trim_flags()

自动换行空格修剪标志。详见 TextServer.BREAK_TRIM_START_EDGE_SPACES 和 TextServer.BREAK_TRIM_END_EDGE_SPACES。

---

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

用于文本裁剪的省略字符。

---

HorizontalAlignment horizontal_alignment = 0 🔗

• void set_horizontal_alignment(value: HorizontalAlignment)

• HorizontalAlignment get_horizontal_alignment()

控制文本的水平对齐方式。支持左对齐、居中对齐、右对齐、填充（即两端对齐）。

---

BitField[JustificationFlag] justification_flags = 163 🔗

• void set_justification_flags(value: BitField[JustificationFlag])

• BitField[JustificationFlag] get_justification_flags()

行填充对齐规则。

---

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

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

---

int lines_skipped = 0 🔗

• void set_lines_skipped(value: int)

• int get_lines_skipped()

从 text 值的开头开始忽略且不显示的行数。

---

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

段落分隔符字符串。段落独立处理，使用自己的 BiDi 上下文。

---

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

设置文本超出节点边界框时的裁剪行为。

---

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

控制文本的垂直对齐方式。支持顶部对齐、居中对齐、底部对齐、填充。

---

int visible_characters = -1 🔗

• void set_visible_characters(value: int)

• int get_visible_characters()

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

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

注意：字符按照 Unicode 码位计算。一个可见的字素可能包含多个码位（例如部分 Emoji 会使用三个码位）。一个码位可能包含两个 UTF-16 字符，C# 字符串中会用到。

---

VisibleCharactersBehavior visible_characters_behavior = 0 🔗

• void set_visible_characters_behavior(value: VisibleCharactersBehavior)

• VisibleCharactersBehavior get_visible_characters_behavior()

设置 visible_characters 或 visible_ratio 被设置时的裁剪行为。

---

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 🔗

返回位置 pos 处字符的边界矩形，使用标签的局部坐标系。如果字符是不可见字符或 pos 超出有效范围，则返回空 Rect2。如果字符是复合字素的一部分，则返回整个字素的边界矩形。

---

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 🔗

行与行之间的额外纵向留白（单位为像素），留白会被添加到行的降部。该值可以为负数。

---

int outline_size = 0 🔗

文字轮廓的大小。

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

注意：不建议使用大于字体大小一半的值，因为这种情况下字体轮廓可能无法完全闭合。

---

int paragraph_spacing = 0 🔗

段落之间的垂直空间。在 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 🔗

Label 处于聚焦状态时使用的 StyleBox（适用于使用辅助应用）。

---

StyleBox normal 🔗

为 Label 设置背景样式盒 StyleBox。