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

ProgressBar

节点继承关系

继承链：Node → CanvasItem → Control → Range → ProgressBar

定义

进度条——下载文件时看到的那种"慢慢变长"的条。它有一个最小值和一个最大值，当前值在两者之间时，条就填充到对应的比例。

使用频率：★★★★ 维度专用常用（血条、加载进度等几乎必用）

节点用途

• 显示血量/蓝量/体力
• 显示加载进度
• 显示任务完成度

使用场景

• 角色头顶的血条
• 场景加载的进度条
• 任务系统的完成进度

常用节点搭配

• 搭配 TextureRect 做血条背景
• 搭配 Label 显示数值
• 搭配 HBoxContainer 排列血条和数值

生效必备素材/资源

无需特殊资源。样式由主题控制。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
show_percentage	bool	true	—	是否显示百分比文字
show_percentage_label	bool	true	—	是否显示百分比标签

继承自 Range

属性	类型	默认值	继承自	说明
value	float	0.0	Range	当前进度值
min_value	float	0.0	Range	最小值
max_value	float	100.0	Range	最大值
step	float	1.0	Range	步进值

信号

信号	触发时机	参数
value_changed	进度值变化时	float 新值

常用方法

方法	说明
SetValue(float)	设置进度值
GetValue()	获取进度值

代码示例

C

using Godot;

public partial class HealthBar : Control
{
    private ProgressBar _healthBar;

    public override void _Ready()
    {
        _healthBar = new ProgressBar();
        _healthBar.MinValue = 0;
        _healthBar.MaxValue = 100;
        _healthBar.Value = 100;           // 初始满血
        _healthBar.ShowPercentage = true;
        _healthBar.Position = new Vector2(10, 10);
        _healthBar.Size = new Vector2(200, 20);

        AddChild(_healthBar);
    }

    // 受到伤害时调用
    public void TakeDamage(float amount)
    {
        _healthBar.Value = Mathf.Max(_healthBar.MinValue, _healthBar.Value - amount);
        GD.Print($"剩余血量: {_healthBar.Value}");
    }
}

GDScript

extends Control

var health_bar: ProgressBar

func _ready():
    health_bar = ProgressBar.new()
    health_bar.min_value = 0
    health_bar.max_value = 100
    health_bar.value = 100             # 初始满血
    health_bar.show_percentage = true
    health_bar.position = Vector2(10, 10)
    health_bar.size = Vector2(200, 20)

    add_child(health_bar)

# 受到伤害时调用
func take_damage(amount: float):
    health_bar.value = maxf(health_bar.min_value, health_bar.value - amount)
    print("剩余血量: " + str(health_bar.value))