最后同步日期：2026-04-15 | Godot 官方原文 — Label

Label

节点继承关系

继承链：Node → Control → Label

定义

Label 在 2D 场景或 UI 界面中显示纯文本。它是 Godot 中最基础的文字显示节点——给它一段文字，它就原样显示出来。虽然它本质上是 UI 节点（继承自 Control），但在 2D 游戏场景中也经常被用来显示 NPC 对话、物品说明、提示信息等。

一句话理解：Label 就是一张空白便签纸——你写什么字，它就展示什么字，简单直接。

使用频率：★★★★ 维度专用常用——游戏中的文字信息显示无处不在。

节点用途

• 显示静态文字信息（标题、说明、提示）
• 显示 NPC 对话文本
• 显示游戏中的动态数值（分数、生命值）
• 配合容器节点实现复杂的 UI 文字布局

使用场景

场景	说明
NPC 对话	显示 NPC 的对话内容
UI 标签	界面中的标题、按钮文字、说明文字
分数显示	显示游戏分数、金币数量等
提示信息	"按 E 键交互"、"游戏结束"等提示
调试信息	开发时显示调试数据

常用节点搭配

搭配节点	搭配方式	用途
RichTextLabel	替代关系	需要富文本（粗体、颜色、图片）时用 RichTextLabel
MarginContainer	作为父节点	给 Label 添加边距
VBoxContainer	作为父节点	垂直排列多个 Label
PanelContainer	作为父节点	给文字添加背景面板

生效必备素材/资源

资源类型	格式	说明
Font（可选）	.ttf、.otf、.woff2	自定义字体文件。不设置则使用默认字体

节点属性与信号

文本属性

属性	类型	默认值	继承自	说明
Text	String	""	—	要显示的文字内容
TextDirection	TextDirection	Auto	—	文字方向（自动/从左到右/从右到左）
Language	String	""	—	语言代码（用于国际化）
StructuredTextBidiOverride	StructuredTextBidiOverride	Default	—	双向文本覆盖选项

外观属性

属性	类型	默认值	继承自	说明
HorizontalAlignment	HorizontalAlignment	Left	—	水平对齐方式：左对齐/居中/右对齐/填充
VerticalAlignment	VerticalAlignment	Center	—	垂直对齐方式：顶部/居中/底部
AutowrapMode	AutowrapMode	Off	—	自动换行模式。WordSmart 在单词边界换行
Uppercase	bool	false	—	是否全部大写
JustificationFlags	JustificationFlag	None	—	两端对齐选项
VisibleCharacters	int	-1	—	可见字符数（-1 = 全部，配合打字机效果）
VisibleRatio	float	1.0	—	可见比例（0.0~1.0，可做淡入效果）

字体属性

属性	类型	默认值	继承自	说明
Font	Font	null（使用主题默认）	—	自定义字体
FontSize	int	16（使用主题默认）	—	字体大小
FontColor	Color	Color(1, 1, 1, 1)	—	字体颜色

效果属性

属性	类型	默认值	继承自	说明
OutlineColor	Color	Color(0, 0, 0, 1)	—	描边颜色（文字轮廓）
OutlineSize	int	0	—	描边大小。设为 1~3 可让文字更清晰
ShadowColor	Color	Color(0, 0, 0, 0)	—	阴影颜色
ShadowOffset	Vector2	Vector2(1, 1)	—	阴影偏移量
ShadowSize	int	0	—	阴影大小

继承自 Control 的常用属性

属性	类型	默认值	继承自	说明
AnchorPreset	—	TopLeft	Control	锚点预设（定位方式）
Position	Vector2	Vector2(0, 0)	Control	节点位置
Size	Vector2	Vector2(0, 0)	Control	节点大小
MouseFilter	MouseFilter	Stop	Control	鼠标过滤（是否响应鼠标事件）
Modulate	Color	Color(1, 1, 1, 1)	Control	整体颜色调制

信号

信号	参数	触发时机
MetaClicked	meta: Variant	点击超链接元数据时
MetaHoverStarted	meta: Variant	鼠标悬停在超链接上时
MetaHoverEnded	meta: Variant	鼠标离开超链接时

常用方法

方法	返回值	说明
GetText()	String	获取当前文本
SetText(text)	void	设置文本
GetVisibleCharacters()	int	获取可见字符数
SetVisibleCharacters(amount)	void	设置可见字符数（打字机效果）
GetTotalCharacterCount()	int	获取总字符数
GetLineCount()	int	获取行数

代码示例

基础用法：显示文字

C

var label = GetNode<Label>("Label");

// 设置文字
label.Text = "你好，Godot！";

// 设置字体大小和颜色
label.FontSize = 24;
label.FontColor = Colors.Yellow;

// 居中对齐
label.HorizontalAlignment = HorizontalAlignment.Center;

GDScript

var label = $Label

# 设置文字
label.text = "你好，Godot！"

# 设置字体大小和颜色
label.font_size = 24
label.add_theme_color_override("font_color", Color.YELLOW)

# 居中对齐
label.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER

打字机效果

C

public partial class TypewriterLabel : Label
{
    [Export] public string ExFullText = "这是一段打字机效果的文字。";
    [Export] public float ExSpeed = 20f; // 每秒显示 20 个字符

    private double _charIndex = 0;

    public override void _Ready()
    {
        Text = ExFullText;
        VisibleCharacters = 0;
    }

    public override void _Process(double delta)
    {
        if (VisibleCharacters < ExFullText.Length)
        {
            _charIndex += ExSpeed * delta;
            VisibleCharacters = (int)_charIndex;
        }
    }
}

GDScript

extends Label

@export var full_text: String = "这是一段打字机效果的文字。"
@export var speed: float = 20.0  # 每秒显示 20 个字符

var _char_index: float = 0.0

func _ready():
    text = full_text
    visible_characters = 0

func _process(delta):
    if visible_characters < full_text.length():
        _char_index += speed * delta
        visible_characters = int(_char_index)

动态显示分数

C

private int _score = 0;
private Label _scoreLabel;

public override void _Ready()
{
    _scoreLabel = GetNode<Label>("ScoreLabel");
    UpdateScore(0);
}

public void UpdateScore(int amount)
{
    _score += amount;
    _scoreLabel.Text = $"分数: {_score}";
}

GDScript

var _score: int = 0
@onready var _score_label: Label = $ScoreLabel

func _ready():
    update_score(0)

func update_score(amount: int):
    _score += amount
    _score_label.text = "分数: %d" % _score