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

TabBar

节点继承关系

继承链：Node → CanvasItem → Control → TabBar

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

定义

TabBar 是一个独立的标签栏控件，和 TabContainer 不同的是：TabBar 只负责顶部的标签行，不管理内容面板。你需要自己处理点击标签后显示什么内容。就像浏览器标签栏的"标签部分"——它只管那一排标签，不管下面显示什么页面。

使用频率：★★★ 一般常用（需要自定义标签页内容时使用）

节点用途

• 自定义标签页导航
• 分类切换（不需要容器自动管理内容）

使用场景

• 设置页面的分类标签（手动切换面板）
• 商品分类切换
• 聊天频道的标签切换

常用节点搭配

• 搭配 VBoxContainer 做标签 + 内容的布局
• 搭配多个 Control 做内容面板，根据选中标签显示/隐藏

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
tab_count	int	0	—	标签数量（只读）
current_tab	int	-1	—	当前选中的标签索引
tab_alignment	枚举	Left	—	标签的对齐方式
scrolling_enabled	bool	true	—	标签过多时是否可滚动
drag_forward_stacking	bool	false	—	拖拽标签时的堆叠行为

信号

信号	触发时机	参数
tab_changed	切换标签页时	int 新标签页索引
tab_clicked	点击标签时	int 标签索引
tab_close_pressed	点击标签关闭按钮时	int 标签索引

常用方法

方法	说明
AddTab("名称")	添加一个标签
RemoveTab(index)	移除指定标签
SetTabTitle(index, "新名称")	修改标签名称
SetTabIcon(index, Texture2D)	设置标签图标
GetTabTitle(index)	获取标签名称
ClearTabs()	清空所有标签

代码示例

C

using Godot;

public partial class CustomTabBar : Control
{
    private TabBar _tabBar;
    private Control[] _panels;

    public override void _Ready()
    {
        // 创建标签栏
        _tabBar = new TabBar();
        _tabBar.Position = new Vector2(0, 0);
        _tabBar.Size = new Vector2(400, 40);
        _tabBar.AddTab("概览");
        _tabBar.AddTab("详情");
        _tabBar.AddTab("设置");

        // 创建内容面板
        _panels = new Control[3];
        for (int i = 0; i < 3; i++)
        {
            _panels[i] = new Panel();
            _panels[i].Position = new Vector2(0, 40);
            _panels[i].Size = new Vector2(400, 200);
            _panels[i].AddChild(new Label() { Text = $"面板 {i + 1} 的内容" });
            AddChild(_panels[i]);
        }

        // 监听标签切换
        _tabBar.TabChanged += OnTabChanged;
        OnTabChanged(0); // 初始显示第一个

        AddChild(_tabBar);
    }

    private void OnTabChanged(int tab)
    {
        for (int i = 0; i < _panels.Length; i++)
            _panels[i].Visible = (i == tab);
    }
}

GDScript

extends Control

var tab_bar: TabBar
var panels: Array[Control] = []

func _ready():
    # 创建标签栏
    tab_bar = TabBar.new()
    tab_bar.position = Vector2(0, 0)
    tab_bar.size = Vector2(400, 40)
    tab_bar.add_tab("概览")
    tab_bar.add_tab("详情")
    tab_bar.add_tab("设置")

    # 创建内容面板
    for i in range(3):
        var panel = Panel.new()
        panel.position = Vector2(0, 40)
        panel.size = Vector2(400, 200)
        var label = Label.new()
        label.text = "面板 " + str(i + 1) + " 的内容"
        panel.add_child(label)
        panels.append(panel)
        add_child(panel)

    # 监听标签切换
    tab_bar.tab_changed.connect(_on_tab_changed)
    _on_tab_changed(0)  # 初始显示第一个

    add_child(tab_bar)

func _on_tab_changed(tab: int):
    for i in range(panels.size()):
        panels[i].visible = (i == tab)