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

VBoxContainer

节点继承关系

继承链：Node → CanvasItem → Control → Container → BoxContainer → VBoxContainer

继承自 BoxContainer

类型	名称	说明
属性	Vertical	是否垂直排列子节点
方法	AddSpacer()	添加占位空白

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()	获取父节点

定义

VBoxContainer 把子节点垂直排列（从上到下叠好）。和 HBoxContainer 是兄弟关系，只是一个水平排、一个垂直排。就像叠罗汉——一个一个从上到下叠好。

使用频率：★★★★ 维度专用常用（最常用的容器之一）

节点用途

• 垂直排列控件（设置面板、列表）
• 搭建 UI 的主框架
• 垂直方向的按钮组

使用场景

• 设置页面的垂直排列选项
• 聊天消息列表
• 菜单的选项列表

常用节点搭配

• 搭配 HBoxContainer 做"标签 + 输入框"的行
• 搭配 MarginContainer 加外边距

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
theme_override_constants/separation	int	4	BoxContainer	子节点之间的间距

信号

信号	触发时机	参数
（VBoxContainer 没有特有信号）	—	—

常用方法

继承自 Container 的所有方法。

代码示例

C

using Godot;

// 垂直排列的设置选项
public partial class SettingsList : VBoxContainer
{
    public override void _Ready()
    {
        AddThemeConstantOverride("separation", 10);

        // 第一行：音量标签 + 滑动条
        var row1 = new HBoxContainer();
        row1.AddChild(new Label() { Text = "音量:  " });
        var slider = new HSlider() { MinValue = 0, MaxValue = 100, Value = 80, CustomMinimumSize = new Vector2(200, 20) };
        row1.AddChild(slider);
        AddChild(row1);

        // 第二行：画质标签 + 下拉选择
        var row2 = new HBoxContainer();
        row2.AddChild(new Label() { Text = "画质:  " });
        var option = new OptionButton();
        option.AddItem("低", 0);
        option.AddItem("中", 1);
        option.AddItem("高", 2);
        option.Select(1);
        row2.AddChild(option);
        AddChild(row2);

        // 第三行：全屏开关
        var row3 = new HBoxContainer();
        row3.AddChild(new Label() { Text = "全屏:  " });
        var toggle = new CheckButton();
        row3.AddChild(toggle);
        AddChild(row3);
    }
}

GDScript

# 垂直排列的设置选项
extends VBoxContainer

func _ready():
    add_theme_constant_override("separation", 10)

    # 第一行：音量标签 + 滑动条
    var row1 = HBoxContainer.new()
    row1.add_child(Label.new())
    row1.get_child(0).text = "音量:  "
    var slider = HSlider.new()
    slider.min_value = 0
    slider.max_value = 100
    slider.value = 80
    slider.custom_minimum_size = Vector2(200, 20)
    row1.add_child(slider)
    add_child(row1)

    # 第二行：画质标签 + 下拉选择
    var row2 = HBoxContainer.new()
    row2.add_child(Label.new())
    row2.get_child(0).text = "画质:  "
    var option = OptionButton.new()
    option.add_item("低", 0)
    option.add_item("中", 1)
    option.add_item("高", 2)
    option.select(1)
    row2.add_child(option)
    add_child(row2)

    # 第三行：全屏开关
    var row3 = HBoxContainer.new()
    row3.add_child(Label.new())
    row3.get_child(0).text = "全屏:  "
    var toggle = CheckButton.new()
    row3.add_child(toggle)
    add_child(row3)