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

HSlider

节点继承关系

继承链：Node → CanvasItem → Control → Range → Slider → HSlider

定义

水平滑动条——就是音量调节那种，左右拖动一个小滑块来选择一个数值。这是最常用的数值调节控件。

使用频率：★★★ 一般常用（音量、亮度等数值调节常用）

节点用途

• 让用户拖动调节数值
• 音量、亮度、灵敏度等连续数值

使用场景

• 游戏设置中的音量调节
• 画面设置中的亮度调节
• 操作设置中的灵敏度调节

常用节点搭配

• 搭配 Label 显示当前数值
• 搭配 HBoxContainer 排列标签和滑动条

生效必备素材/资源

无需特殊资源。

节点属性与信号

继承自 Range

属性	类型	默认值	继承自	说明
value	float	0.0	Range	当前值
min_value	float	0.0	Range	最小值
max_value	float	100.0	Range	最大值
step	float	1.0	Range	每次滑动的步进值
rounded	bool	false	Range	是否取整

信号

信号	触发时机	参数
value_changed	滑块值变化时	float 新值
drag_started	开始拖动时	无
drag_ended	结束拖动时	bool 是否改变值

常用方法

方法	说明
SetValue(float)	设置当前值
GetValue()	获取当前值
继承 Range 所有方法	—

代码示例

C

using Godot;

public partial class VolumeControl : Control
{
    public override void _Ready()
    {
        var label = new Label();
        label.Text = "音量: 50";
        label.Position = new Vector2(100, 80);
        AddChild(label);

        var slider = new HSlider();
        slider.MinValue = 0;
        slider.MaxValue = 100;
        slider.Value = 50;
        slider.Step = 1;
        slider.Position = new Vector2(100, 100);
        slider.Size = new Vector2(200, 20);

        // 滑块值变化时更新文字
        slider.ValueChanged += (val) =>
        {
            label.Text = $"音量: {(int)val}";
        };

        AddChild(slider);
    }
}

GDScript

extends Control

func _ready():
    var label = Label.new()
    label.text = "音量: 50"
    label.position = Vector2(100, 80)
    add_child(label)

    var slider = HSlider.new()
    slider.min_value = 0
    slider.max_value = 100
    slider.value = 50
    slider.step = 1
    slider.position = Vector2(100, 100)
    slider.size = Vector2(200, 20)

    # 滑块值变化时更新文字
    slider.value_changed.connect(func(val: float):
        label.text = "音量: " + str(int(val))
    )

    add_child(slider)