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

TabContainer

节点继承关系

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

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

定义

TabContainer 顶部有一排标签，点击不同标签切换不同的面板内容。就像浏览器标签页一样——点不同标签看不同页面。每个子节点自动成为一个标签页，子节点的 Name 属性就是标签名。

使用频率：★★★ 一般常用（设置页面等常见）

节点用途

• 设置面板的多分类切换
• 多面板信息展示
• 浏览器式的标签页导航

使用场景

• 游戏设置页面（音频/画面/操作等多个标签）
• 物品详情的多标签展示
• 编辑器的多面板切换

常用节点搭配

• 搭配 VBoxContainer 做每个标签页的内部布局

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
tab_count	int	0	—	标签页数量（只读）
current_tab	int	0	—	当前选中的标签页索引
tab_alignment	枚举	Left	—	标签的对齐方式
tab_titles_visible	bool	true	—	是否显示标签标题
scrolling_enabled	bool	true	—	标签过多时是否可滚动

信号

信号	触发时机	参数
tab_changed	切换标签页时	int 新标签页索引
tab_clicked	点击标签时	int 标签页索引
tab_selected	标签被选中时	int 标签页索引

常用方法

方法	说明
SetTabTitle(index, "名称")	修改标签名称
GetTabTitle(index)	获取标签名称
SetTabIcon(index, Texture2D)	设置标签图标
GetTabControl(index)	获取指定标签页的子节点

代码示例

C

using Godot;

public partial class SettingsPanel : TabContainer
{
    public override void _Ready()
    {
        Size = new Vector2(400, 300);

        // 第一个标签页：音频设置
        var audioTab = new VBoxContainer();
        audioTab.Name = "音频";
        audioTab.AddChild(new Label() { Text = "音量设置" });
        AddChild(audioTab);

        // 第二个标签页：画面设置
        var videoTab = new VBoxContainer();
        videoTab.Name = "画面";
        videoTab.AddChild(new Label() { Text = "画质设置" });
        AddChild(videoTab);

        // 第三个标签页：操作设置
        var controlTab = new VBoxContainer();
        controlTab.Name = "操作";
        controlTab.AddChild(new Label() { Text = "按键设置" });
        AddChild(controlTab);

        // 监听标签切换
        TabChanged += (tab) =>
        {
            GD.Print($"切换到了标签页: {tab}");
        };
    }
}

GDScript

extends TabContainer

func _ready():
    size = Vector2(400, 300)

    # 第一个标签页：音频设置
    var audio_tab = VBoxContainer.new()
    audio_tab.name = "音频"
    audio_tab.add_child(Label.new())
    audio_tab.get_child(0).text = "音量设置"
    add_child(audio_tab)

    # 第二个标签页：画面设置
    var video_tab = VBoxContainer.new()
    video_tab.name = "画面"
    video_tab.add_child(Label.new())
    video_tab.get_child(0).text = "画质设置"
    add_child(video_tab)

    # 第三个标签页：操作设置
    var control_tab = VBoxContainer.new()
    control_tab.name = "操作"
    control_tab.add_child(Label.new())
    control_tab.get_child(0).text = "按键设置"
    add_child(control_tab)

    # 监听标签切换
    tab_changed.connect(func(tab: int):
        print("切换到了标签页: " + str(tab))
    )