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...

Label

继承： Control < CanvasItem < Node < Object

用于显示纯文本的控件。

描述

用于显示纯文本的控件。可以控制水平和垂直对齐方式以及文本在节点包围框内的换行方式。不支持粗体、斜体等富文本格式。这种需求请改用 RichTextLabel。

教程

2D Dodge The Creeps 演示

属性

AutowrapMode	autowrap_mode	`0`
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	normal

属性说明

AutowrapMode autowrap_mode = 0 🔗

void set_autowrap_mode(value: AutowrapMode)
AutowrapMode get_autowrap_mode()

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

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

控制文本的水平对齐方式。支持左对齐、居中对齐、右对齐、填充（即两端对齐）。请将其设置为 HorizontalAlignment 常量。

BitField[JustificationFlag] justification_flags = 163 🔗

void set_justification_flags(value: BitField[JustificationFlag])
BitField[JustificationFlag] get_justification_flags()

行两端对齐规则。详见 JustificationFlag。

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

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

设置文本超出节点的边界矩形时的裁剪行为。有关所有模式的描述，请参阅 OverrunBehavior。

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

控制文本的垂直对齐方式。支持顶部对齐、居中对齐、底部对齐和填充。将其设置为 VerticalAlignment 常量之一。

int visible_characters = -1 🔗

void set_visible_characters(value: int)
int get_visible_characters()

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

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

VisibleCharactersBehavior visible_characters_behavior = 0 🔗

void set_visible_characters_behavior(value: VisibleCharactersBehavior)
VisibleCharactersBehavior get_visible_characters_behavior()

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

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 normal 🔗

为 Label 设置背景样式盒 StyleBox。