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

ScrollContainer

节点继承关系

继承链：Node → CanvasItem → Control → Container → ScrollContainer

Container

类型	名称	说明
信号	sort_children	子节点排列发生变化
方法	FitChildInRect()	调整子节点到指定矩形内

Control

类型	名称	说明
属性	Size	控件尺寸
属性	Position	控件位置
属性	AnchorsPreset	锚点预设
属性	GrowDirection	超出容器时的扩展方向
属性	MouseFilter	鼠标事件过滤（停止 / 通过 / 忽略）
属性	FocusMode	焦点模式（无 / 单击 / 全部）
信号	gui_input	接收到 GUI 输入事件
信号	mouse_entered	鼠标进入控件区域
信号	mouse_exited	鼠标离开控件区域
信号	focus_entered	获得焦点
信号	focus_exited	失去焦点
信号	resized	尺寸变化
方法	GrabFocus()	获取焦点
方法	ReleaseFocus()	释放焦点
方法	SetAnchorsPreset()	设置锚点预设
方法	GetMinimumSize()	获取最小尺寸

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

当内容太多、超出容器大小时，ScrollContainer 会自动出现滚动条，让用户可以滚动查看。就像手机上浏览很长的网页一样。

使用频率：★★★ 一般常用（长列表、长文本常用）

节点用途

• 可滚动的长列表
• 可滚动的大面板
• 超出显示区域的内容

使用场景

• 背包物品列表（物品太多时滚动）
• 聊天记录列表
• 设置面板（选项太多时滚动）

常用节点搭配

• 里面通常放 VBoxContainer 或 HBoxContainer 来排列子控件
• 搭配 VScrollBar / HScrollBar 控制滚动条外观

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
horizontal_scroll_mode	枚举	Auto	—	水平滚动条模式：Auto（自动）、ShowAlways（始终显示）、ShowNever（禁用）、Disabled
vertical_scroll_mode	枚举	Auto	—	垂直滚动条模式
scroll_horizontal	int	0	—	水平滚动位置
scroll_vertical	int	0	—	垂直滚动位置
scroll_deadzone	int	0	—	滚动死区（触屏设备用）

信号

信号	触发时机	参数
scroll_started	开始滚动时	无
scroll_ended	停止滚动时	无

常用方法

方法	说明
SetScrollH(int)	设置水平滚动位置
SetScrollV(int)	设置垂直滚动位置
GetScrollH()	获取水平滚动位置
GetScrollV()	获取垂直滚动位置

代码示例

C

using Godot;

// 一个可滚动的长列表
public partial class ScrollableList : ScrollContainer
{
    public override void _Ready()
    {
        Size = new Vector2(300, 400);
        VerticalScrollMode = ScrollContainer.ScrollMode.ShowAlways;

        var vbox = new VBoxContainer();
        vbox.AddThemeConstantOverride("separation", 5);

        // 创建 50 个按钮，会超出容器高度，自动出现滚动条
        for (int i = 0; i < 50; i++)
        {
            var btn = new Button();
            btn.Text = $"选项 {i + 1}";
            btn.CustomMinimumSize = new Vector2(250, 40);
            vbox.AddChild(btn);
        }

        AddChild(vbox);
    }
}

GDScript

# 一个可滚动的长列表
extends ScrollContainer

func _ready():
    size = Vector2(300, 400)
    vertical_scroll_mode = ScrollContainer.ScrollMode.SCROLL_MODE_SHOW_ALWAYS

    var vbox = VBoxContainer.new()
    vbox.add_theme_constant_override("separation", 5)

    # 创建 50 个按钮，会超出容器高度，自动出现滚动条
    for i in range(50):
        var btn = Button.new()
        btn.text = "选项 " + str(i + 1)
        btn.custom_minimum_size = Vector2(250, 40)
        vbox.add_child(btn)

    add_child(vbox)