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

Label.set_text

定义

Label.set_text 就是给标签（Label）设置显示的文字内容。Label 是 Godot 中最基础的文字显示控件，就像一块"告示牌"，你往上面写什么，玩家就能看到什么。

打个比方：Label 就像一个电子显示屏，set_text 就是在显示屏上打出一行字。游戏里的血量数字、分数显示、对话文字、提示信息，都是 Label 在干活。

在实际游戏开发中，Label 是用来向玩家展示文字信息最常用的方式。你可以用它来显示分数、倒计时、角色名称、任务提示等等。

函数签名

C#

// 通过属性设置
public string Text { get; set; }

// 使用示例
label.Text = "Hello World";

GDScript

func set_text(text: String) -> void
# 也可以直接用属性赋值：
# label.text = "Hello World"

参数说明

参数	类型	必需	说明
text	String	是	标签要显示的文字内容，支持多行文本（用 \n 换行）

返回值

无返回值（void）。这是一个纯粹的"设置"操作。

代码示例

基础用法：设置标签文字

C#

var scoreLabel = GetNode<Label>("ScoreLabel");
scoreLabel.Text = "得分：0";
// 运行结果: 标签显示"得分：0"

var infoLabel = GetNode<Label>("InfoLabel");
infoLabel.Text = "第一行\n第二行\n第三行";
// 运行结果: 标签分三行显示文字

GDScript

var score_label = $ScoreLabel as Label
score_label.text = "得分：0"
# 运行结果: 标签显示"得分：0"

var info_label = $InfoLabel as Label
info_label.text = "第一行\n第二行\n第三行"
# 运行结果: 标签分三行显示文字

实际场景：实时更新分数和血量显示

C#

using Godot;

public partial class GameHUD : Control
{
    private Label _scoreLabel;
    private Label _healthLabel;
    private int _score = 0;
    private float _health = 100.0f;

    public override void _Ready()
    {
        _scoreLabel = GetNode<Label>("ScoreLabel");
        _healthLabel = GetNode<Label>("HealthLabel");
        UpdateHUD();
    }

    public void AddScore(int points)
    {
        _score += points;
        UpdateHUD();
        // 运行结果: 每次调用后分数标签更新，如 "得分：150"
    }

    public void TakeDamage(float damage)
    {
        _health = Mathf.Max(0, _health - damage);
        UpdateHUD();
        // 运行结果: 血量标签更新，如 "HP：75.0"
    }

    private void UpdateHUD()
    {
        _scoreLabel.Text = $"得分：{_score}";
        _healthLabel.Text = $"HP：{_health}";
    }
}

GDScript

extends Control

@onready var _score_label: Label = $ScoreLabel
@onready var _health_label: Label = $HealthLabel
var _score: int = 0
var _health: float = 100.0

func _ready():
    update_hud()

func add_score(points: int):
    _score += points
    update_hud()
    # 运行结果: 每次调用后分数标签更新，如 "得分：150"

func take_damage(damage: float):
    _health = max(0, _health - damage)
    update_hud()
    # 运行结果: 血量标签更新，如 "HP：75.0"

func update_hud():
    _score_label.text = "得分：%d" % _score
    _health_label.text = "HP：%s" % _health

进阶用法：带格式的倒计时器

C#

using Godot;

public partial class CountdownTimer : Label
{
    private float _timeLeft = 60.0f;

    public override void _Process(double delta)
    {
        _timeLeft -= (float)delta;

        if (_timeLeft <= 0.0f)
        {
            _timeLeft = 0.0f;
            Text = "时间到！";
            // 运行结果: 倒计时结束后显示"时间到！"
        }
        else
        {
            int minutes = (int)(_timeLeft / 60.0f);
            int seconds = (int)(_timeLeft % 60.0f);
            Text = $"{minutes:D2}:{seconds:D2}";
            // 运行结果: 显示格式如 "01:30"、"00:05"
        }
    }
}

GDScript

extends Label

var _time_left: float = 60.0

func _process(delta):
    _time_left -= delta

    if _time_left <= 0.0:
        _time_left = 0.0
        text = "时间到！"
        # 运行结果: 倒计时结束后显示"时间到！"
    else:
        var minutes = int(_time_left / 60.0)
        var seconds = int(_time_left) % 60
        text = "%02d:%02d" % [minutes, seconds]
        # 运行结果: 显示格式如 "01:30"、"00:05"

注意事项

• 频繁更新文字不会自动调整尺寸：默认情况下 Label 不会随内容变化自动调整大小。如果文字变长了可能被截断。可以配合 autosize_mode 属性来自动调整。
• 性能提示：在 _Process 中每帧更新 Label 文字是常见做法，但如果文字没变化，建议用 if 判断一下，避免每帧都重新渲染。
• 支持转义字符：可以用 \n 换行、\t 制表符等标准转义字符。
• C# 中推荐直接用属性：label.Text = "xxx" 比 label.SetText("xxx") 更符合 C# 命名习惯。GDScript 中两种写法等价。
• 空字符串也是合法值：设置 Text = "" 会让标签不显示任何内容，但节点仍然存在。