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

VScrollBar

节点继承关系

继承链：Node → CanvasItem → Control → Range → ScrollBar → VScrollBar

定义

垂直滚动条——就是那种竖着的、可以上下拖动的长条，你在网页右侧看到的那种。和 HScrollBar 是兄弟关系，只是一个水平、一个垂直。通常由 ScrollContainer 自动管理。

使用频率：★★★ 一般常用（通常由 ScrollContainer 自动管理）

节点用途

• 垂直方向的滚动控制
• 自定义垂直滚动条

使用场景

• 高内容区域的垂直滚动
• 自定义 ScrollContainer 的滚动条

常用节点搭配

• 搭配 ScrollContainer 使用

生效必备素材/资源

无需特殊资源。

节点属性与信号

继承自 ScrollBar

属性	类型	默认值	继承自	说明
custom_step	float	0.0	ScrollBar	自定义步进值

继承自 Range

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

信号

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

常用方法

继承自 Range 的所有方法。

代码示例

C

using Godot;

public partial class CustomVScrollBar : Control
{
    public override void _Ready()
    {
        var scrollBar = new VScrollBar();
        scrollBar.MinValue = 0;
        scrollBar.MaxValue = 1000;
        scrollBar.Value = 0;
        scrollBar.Step = 1;
        scrollBar.CustomMinimumSize = new Vector2(20, 400);
        scrollBar.Position = new Vector2(280, 0);

        scrollBar.ValueChanged += (val) =>
        {
            GD.Print($"垂直滚动位置: {val}");
        };

        AddChild(scrollBar);
    }
}

GDScript

extends Control

func _ready():
    var scroll_bar = VScrollBar.new()
    scroll_bar.min_value = 0
    scroll_bar.max_value = 1000
    scroll_bar.value = 0
    scroll_bar.step = 1
    scroll_bar.custom_minimum_size = Vector2(20, 400)
    scroll_bar.position = Vector2(280, 0)

    scroll_bar.value_changed.connect(func(val: float):
        print("垂直滚动位置: " + str(val))
    )

    add_child(scroll_bar)