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

Tree

节点继承关系

继承链：Node → CanvasItem → Control → Tree

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

定义

Tree 控件以树形结构展示数据——就像文件管理器左边的目录树，可以展开/折叠。每个条目叫 TreeItem，通过"父子关系"组织成树形结构。

使用频率：★★★ 一般常用（技能树、文件浏览器等）

节点用途

• 展示层级数据
• 技能树系统
• 文件浏览器

使用场景

• 角色技能树
• 游戏内文件浏览器
• 任务系统分类

常用节点搭配

• 搭配 ScrollContainer 支持大量条目滚动
• 搭配 VBoxContainer 做布局

生效必备素材/资源

无需特殊资源。可选：图标图片用于条目图标。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
hide_root	bool	true	—	是否隐藏根节点
columns	int	1	—	列数
allow_reselect	bool	false	—	是否允许重复选中同一项

关键概念

概念	说明
TreeItem	树中的一个条目（节点）
Root	树的根节点（隐藏的，不显示）
CreateItem(parent)	在某个父节点下创建子条目

信号

信号	触发时机	参数
item_selected	选中一个条目时	无
item_activated	双击一个条目时	无
item_collapsed	展开/折叠一个条目时	TreeItem 条目对象
cell_selected	选中一个单元格时	无

常用方法

方法	说明
CreateItem(parent)	创建子条目
GetRoot()	获取根条目
GetSelected()	获取当前选中的条目
Clear()	清空所有条目

代码示例

C

using Godot;

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

        // 创建根节点
        TreeItem root = CreateItem();
        // 第一层：分类
        TreeItem combat = CreateItem(root);
        combat.SetText(0, "战斗技能");
        TreeItem magic = CreateItem(root);
        magic.SetText(0, "魔法技能");

        // 第二层：具体技能
        TreeItem slash = CreateItem(combat);
        slash.SetText(0, "  斩击");
        TreeItem shield = CreateItem(combat);
        shield.SetText(0, "  格挡");

        TreeItem fireball = CreateItem(magic);
        fireball.SetText(0, "  火球术");
        TreeItem heal = CreateItem(magic);
        heal.SetText(0, "  治疗术");
    }
}

GDScript

extends Tree

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

    # 创建根节点
    var root = create_item()
    # 第一层：分类
    var combat = create_item(root)
    combat.set_text(0, "战斗技能")
    var magic = create_item(root)
    magic.set_text(0, "魔法技能")

    # 第二层：具体技能
    var slash = create_item(combat)
    slash.set_text(0, "  斩击")
    var shield = create_item(combat)
    shield.set_text(0, "  格挡")

    var fireball = create_item(magic)
    fireball.set_text(0, "  火球术")
    var heal = create_item(magic)
    heal.set_text(0, "  治疗术")