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

TextureProgressBar

节点继承关系

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

定义

用图片来做进度条——比如一个圆形的 loading 动画，或者用角色头像做血条底色。比 ProgressBar 更好看，但配置稍微复杂一点。

使用频率：★★★ 一般常用（需要精美进度条时使用）

节点用途

• 圆形进度条（loading 圈）
• 自定义外观的血条、蓝条
• 任意形状的进度指示器

使用场景

• 游戏加载时的圆形 loading 动画
• 精美的角色血条（用角色图片做底色）
• 技能冷却环形进度

常用节点搭配

• 搭配 CenterContainer 居中显示
• 搭配 Label 在进度条上叠加数值文字

生效必备素材/资源

• 必需：进度条填充图片（Texture2D）
• 推荐：背景图片和覆盖图片

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
texture_under	Texture2D	null	—	进度条底部图片（背景）
texture_over	Texture2D	null	—	进度条覆盖图片（前景装饰）
texture_progress	Texture2D	null	—	进度条填充图片
fill_mode	枚举	LeftToRight	—	填充方向（从左到右、从右到左、圆形等）
radial_initial_angle	float	0.0	—	圆形填充的起始角度
radial_fill_degrees	float	360.0	—	圆形填充的角度范围

继承自 Range

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

信号

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

常用方法

方法	说明
继承 Range 所有方法	—

代码示例

C

using Godot;

public partial class CoolDownBar : Control
{
    private TextureProgressBar _coolDownBar;

    public override void _Ready()
    {
        _coolDownBar = new TextureProgressBar();
        _coolDownBar.TextureUnder = GD.Load<Texture2D>("res://assets/ui/cooldown_bg.png");
        _coolDownBar.TextureProgress = GD.Load<Texture2D>("res://assets/ui/cooldown_fill.png");
        _coolDownBar.FillMode = TextureProgressBar.FillModeEnum.Clockwise;
        _coolDownBar.MinValue = 0;
        _coolDownBar.MaxValue = 10;
        _coolDownBar.Value = 10;
        _coolDownBar.Position = new Vector2(100, 100);
        _coolDownBar.Size = new Vector2(64, 64);

        AddChild(_coolDownBar);
    }

    // 冷却倒计时
    public void StartCoolDown(float duration)
    {
        var tween = CreateTween();
        _coolDownBar.Value = 0;
        tween.TweenProperty(_coolDownBar, "value", duration, duration);
    }
}

GDScript

extends Control

var cool_down_bar: TextureProgressBar

func _ready():
    cool_down_bar = TextureProgressBar.new()
    cool_down_bar.texture_under = load("res://assets/ui/cooldown_bg.png")
    cool_down_bar.texture_progress = load("res://assets/ui/cooldown_fill.png")
    cool_down_bar.fill_mode = TextureProgressBar.FillMode.FILL_MODE_CLOCKWISE
    cool_down_bar.min_value = 0
    cool_down_bar.max_value = 10
    cool_down_bar.value = 10
    cool_down_bar.position = Vector2(100, 100)
    cool_down_bar.size = Vector2(64, 64)

    add_child(cool_down_bar)

# 冷却倒计时
func start_cool_down(duration: float):
    var tween = create_tween()
    cool_down_bar.value = 0
    tween.tween_property(cool_down_bar, "value", duration, duration)