Godot 引擎 TreeItem 类完全指南：Tree 树形控件的节点构建、单元格模式与交互 API 详解

• 文档
• 教程
• 游戏开发

本文以 godot-docs 仓库的 TreeItem 类参考文档 为骨架，系统讲解 Godot Engine 中TreeItem的定位、生命周期、层级遍历、五种单元格模式、文本/图标/样式定制、内嵌按钮与自定义绘制等完整能力，并结合 Tree 类文档 中的调用示例与信号联动，帮助你掌握用代码构建多列树形 UI（文件浏览器、属性面板、层级大纲等）的完整方法。

TreeItem是 Godot 引擎Tree控件内部每个条目的数据载体。它不是Node，而是完全由Tree内部控制、以Object为基类的内存对象。理解它的创建方式、层级关系、单元格模式与信号联动，是开发基于Tree的复杂界面的前提。

TreeItem 是什么：Tree 内部的非 Node 树节点

TreeItem继承自Object（见 class_treeitem.rst），是Tree控件中单个条目的内部控件。它可以：

• 包含子TreeItem，从而构成层级结构；
• 携带文本（多列）与按钮；
• 不参与场景树，生命周期完全由代码控制。

它的创建与销毁非常直观：

• 创建：通过Tree.create_item()或TreeItem.create_child()；
• 删除：通过Object.free()。

官方文档特别强调一个容易被忽略的细节：按钮 ID 是 32 位整数，取值范围为-2147483648到2147483647，与始终为 64 位的int类型不同。在设计按钮 ID 时不要使用超出 32 位范围的值。

从 Tree 类文档 的示例可以看出二者协作的基本模式：

func _ready(): var tree = Tree.new() var root = tree.create_item() # 无父参数，创建根 tree.hide_root = true # 隐藏根，模拟"多根"效果 var child1 = tree.create_item(root) var child2 = tree.create_item(root) var subchild1 = tree.create_item(child1) subchild1.set_text(0, "Subchild1")

public override void _Ready() { var tree = new Tree(); TreeItem root = tree.CreateItem(); tree.HideRoot = true; TreeItem child1 = tree.CreateItem(root); TreeItem child2 = tree.CreateItem(root); TreeItem subchild1 = tree.CreateItem(child1); subchild1.SetText(0, "Subchild1"); }

四项核心属性：折叠、可见性与最小高度

TreeItem只有 4 个可配置属性（见 class_treeitem.rst），全部通过对应的 setter/getter 读写：

与visible配套的还有一个派生查询方法：

• is_visible_in_tree()：仅当自身visible为true且所有祖先也都可见时才返回true。

TreeCellMode 枚举：五种单元格显示模式

TreeItem通过set_cell_mode(column, mode)决定每个单元格（列）的显示与编辑方式，模式定义在enum TreeCellMode中（见 class_treeitem.rst）：

CELL_MODE_STRING = 0（默认）

单元格显示文本标签，可附带图标。可编辑时，用LineEdit编辑；如果调用了set_edit_multiline()，则改用TextEdit弹出窗口进行多行编辑。

CELL_MODE_CHECK = 1

单元格显示复选框，可附带文本与图标。复选框支持三种状态：勾选、未勾选、不确定（通过set_indeterminate()设置）。复选框只有在单元格可编辑（set_editable()为 true）时才能被点击。

CELL_MODE_RANGE = 2

单元格显示数值范围。可编辑时用范围滑块编辑：

• 用set_range(column, value)设置当前值；
• 用set_range_config(column, min, max, step, expr)配置取值范围。

该模式还能实现文本下拉效果：用set_text()给单元格赋文本，选项用逗号分隔，例如"Option1,Option2,Option3"，引擎会把它渲染为下拉选择框。

CELL_MODE_ICON = 3

单元格只显示图标，不可编辑、不显示文本，图标始终在单元格内居中。可配合set_icon_overlay()在左下角叠加一个覆盖图标。

CELL_MODE_CUSTOM = 4

单元格显示为可点击按钮，外观类似OptionButton的箭头，但没有下拉菜单（需要下拉请用CELL_MODE_RANGE的文本模式）。点击该单元格会发出Tree.item_edited信号。按钮默认是扁平（flat）样式，可用set_custom_as_button()让它以StyleBox边框显示。此模式还支持通过set_custom_draw_callback()进行自定义绘制。

对应查询方法：get_cell_mode(column)返回当前列的模式。

生命周期管理：创建、移除、重挂与释放

TreeItem的增删改查全部在内存中进行：

• create_child(index = -1)：创建子条目并挂接。index指定插入位置，-1表示末尾；若index大于子条目总数，同样追加到末尾。
• add_child(child)：将一个未挂接任何父条目、不属于任何 Tree的TreeItem挂为直接子条目（典型用途：配合remove_child()将条目从一个位置挪到另一个位置）。
• remove_child(child)：从Tree中移除子条目及其全部后代，但不释放内存，之后仍可通过add_child()重新挂回。
• Object.free()：彻底移除并释放条目，这是销毁TreeItem的唯一方式。
• clear_buttons()：移除该条目所有列上的全部按钮。
• clear_custom_color(column)/clear_custom_bg_color(column)：将指定列的自定义颜色/背景色恢复为默认。
• call_recursive(method, ...)：在自身及所有后代上递归调用某个方法（可变参数，用逗号分隔参数列表）。

移动条目的最佳实践：如果想把子条目从一个Tree移到另一个Tree，不要手动 remove 再 add，而应使用move_before(item)或move_after(item)。这两个方法有一个共同限制：不能移动根条目，也不能把条目移动为根。

层级遍历 API：兄弟姐妹与深度优先搜索

构建与遍历层级时，以下方法构成一套完整的导航工具（见 class_treeitem.rst）：

获取父子关系：

• get_parent()：返回父条目，无父时返回null。
• get_first_child()：返回第一个子条目。
• get_child(index)：按索引取子条目；负数索引从末尾倒数。常用于迭代所有子条目。
• get_child_count()：子条目数量。
• get_children()：返回子条目引用数组。
• get_index()：返回该条目在其父条目中的序号（第一个子条目为0）。
• get_tree()：返回拥有该条目的Tree控件。

兄弟遍历：

• get_next()/get_prev()：返回下一个/上一个兄弟条目，没有则返回null。

深度优先遍历（DFS）：

• get_next_in_tree(wrap = false)/get_prev_in_tree(wrap = false)：返回深度优先顺序中的下一个/上一个条目。wrap为true时，在最后一个/第一个条目上调用会回绕到首/尾元素，否则返回null。
• get_next_visible(wrap = false)/get_prev_visible(wrap = false)：同上，但只考虑可见条目（折叠隐藏的后代会被跳过）。

Tree 官方文档给出了一种经典的遍历模式：通过Tree.get_root()拿到根后，用get_next()与get_first_child()组合完成全树迭代。

文本与排版：多列文本的完整定制

每个单元格的文本都有一整套排版控制（见 class_treeitem.rst 与 L1341-L1373、L1707-L1713、L1817-L1847）：

• set_text(column, text)/get_text(column)：读写列文本。
• set_suffix(column, text)/get_suffix(column)：在数值/文本后追加后缀字符串，典型用途是单位缩写（如"px"、"ms"）。
• set_tooltip_text(column, tooltip)/get_tooltip_text(column)：列级悬浮提示。
• set_description(column, description)/get_description(column)：为辅助应用（读屏软件）提供的描述文本，对按钮同样适用。
• set_language(column, language)/get_language(column)：指定文本的语言代码，用于换行与文本塑形（shaping）算法；语言为空时使用当前 locale。
• set_text_alignment(column, alignment)：文本水平对齐（HorizontalAlignment）。
• set_text_direction(column, direction)：文本书写方向（TextDirection），用于 RTL 语言。
• set_text_overrun_behavior(column, behavior)：文本超出单元格边界时的裁剪行为，默认是TextServer.OVERRUN_TRIM_ELLIPSIS（省略号截断）。
• set_autowrap_mode(column, mode)：设置自动换行模式；不为TextServer.AUTOWRAP_OFF时文本在单元格包围盒内自动换行。
• set_autowrap_trim_flags(column, flags)：控制换行行首/行尾空格是否裁剪；默认启用BREAK_TRIM_START_EDGE_SPACES与BREAK_TRIM_END_EDGE_SPACES两项，设为0则完全不裁剪。
• set_auto_translate_mode(column, mode)：列级自动翻译模式，默认Node.AUTO_TRANSLATE_MODE_INHERIT（继承Tree自身的模式）。
• set_structured_text_bidi_override(column, parser)/set_structured_text_bidi_override_options(column, args)：为显示文本的单元格设置结构化文本的 BiDi（双向文本）算法覆盖与附加选项，用于处理混合方向的复杂文本。

图标体系：主图标、覆盖层、着色与区域

TreeItem的图标能力非常灵活（见 class_treeitem.rst 与 L1633-L1687）：

• set_icon(column, texture)/get_icon(column)：设置单元格图标。在CELL_MODE_ICON模式下图标居中显示；其他模式下图标显示在文本之前；CELL_MODE_RANGE不显示图标。
• set_icon_max_width(column, width)/get_icon_max_width(column)：限制图标最大宽度（在图标默认尺寸和Tree.icon_max_width主题常量之上叠加生效），高度按比例缩放。
• set_icon_modulate(column, modulate)/get_icon_modulate(column)：用颜色调制图标（实现高亮、置灰等效果）。
• set_icon_overlay(column, texture)/get_icon_overlay(column)：在图标左下角叠加一个覆盖层图标。要求单元格处于CELL_MODE_ICON模式且已设置主图标。
• set_icon_region(column, region)/get_icon_region(column)：从图集纹理中截取Rect2区域作为显示内容。

颜色与样式：单元格级视觉定制

每个单元格都可以独立定制前景色、背景色与字体样式（见 class_treeitem.rst 与 L1487-L1577）：

• set_custom_color(column, color)/get_custom_color(column)：文本/图标的前景色。
• set_custom_bg_color(column, color, just_outline = false)/get_custom_bg_color(column)：背景色；just_outline为true时仅作为轮廓绘制。注意：若同时设置了自定义StyleBox，背景色会绘制在StyleBox之后（即最底层）。
• set_custom_stylebox(column, stylebox)/get_custom_stylebox(column)：绘制背景的自定义StyleBox。注意：若同时设置了自定义背景色，StyleBox会绘制在背景色之前（即背景色之上）。
• set_custom_font(column, font)/get_custom_font(column)：列文本的自定义字体。
• set_custom_font_size(column, font_size)/get_custom_font_size(column)：列文本的自定义字号。

可编辑性与交互：复选框、范围滑块、选择与元数据

要让树具备编辑能力，需要组合使用以下方法（见 class_treeitem.rst 与 L1317-L1327、L1451-L1457、L1693-L1725、L1757-L1763）：

• set_editable(column, enabled)/is_editable(column)：列是否可编辑。注意：CELL_MODE_CHECK复选框只有在可编辑时才能点击。
• set_edit_multiline(column, multiline)/is_edit_multiline(column)：编辑时使用TextEdit弹出窗口而非LineEdit。该选项只影响编辑控件类型；即使列不可多行编辑，也可以通过set_text()设置多行文本。
• set_selectable(column, selectable)/is_selectable(column)：列是否可被选中。
• select(column, set_as_cursor = true)/deselect(column)/is_selected(column)：编程式选中/取消选中。set_as_cursor为true时，把Tree的光标移到该条目（仅在Tree.select_mode为SELECT_MULTI时才有意义）。
• set_checked(column, checked)/is_checked(column)：勾选状态；设置为勾选会清除列的不确定状态。
• set_indeterminate(column, indeterminate)/is_indeterminate(column)：不确定状态；从 false 改为 true 时会清除列的勾选状态。
• set_range(column, value)/get_range(column)：CELL_MODE_RANGE列的数值。
• set_range_config(column, min, max, step, expr = false)/get_range_config(column)：配置取值范围；expr为true时滑块使用指数刻度（类似Range.exp_edit）。get_range_config()返回的字典键为"min"、"max"、"step"、"expr"。
• set_metadata(column, meta)/get_metadata(column)：为列绑定任意Variant元数据，典型用途是保存原始数据引用（如数据库 ID、对象引用）。
• set_expand_right(column, enable)/get_expand_right(column)：让该列向右撑满剩余宽度。
• set_accept_children(allowed)/is_accepting_children()：是否允许该条目接收子条目（影响拖放等行为的判定）。

编辑完成的联动：Tree会在单元格被修改后发出item_edited信号，配合Tree.get_edited()与Tree.get_edited_column()即可定位被修改的条目与列。Tree 官方文档提供了完整示例（见 class_tree.rst）：

func _ready(): $Tree.item_edited.connect(on_Tree_item_edited) func on_Tree_item_edited(): print($Tree.get_edited()) # 刚刚被编辑（如被勾选）的条目

复选框的级联传播：propagate_check

propagate_check(column, emit_signal = true)把条目的勾选状态同时传播给子条目与父条目（见 class_treeitem.rst）。处理受影响条目的方式有两种：

1. 连接Tree.check_propagated_to_item信号，它会在propagate_check()被调用时对每个受影响的条目依次发出；
2. 处理顺序固定为：调用该方法的条目本身 → 它的子条目 → 它的父条目。

若emit_signal为false，则不发出check_propagated_to_item信号（见 class_tree.rst）。这非常适合实现"全选/全不选"式三级联动复选框。

折叠控制与递归操作

折叠是树形 UI 的核心交互之一，TreeItem提供了批量操作手段（见 class_treeitem.rst 与 L1141-L1149、L1463-L1469、L1865-L1871）：

• collapsed属性 /set_collapsed()/is_collapsed()：单条目折叠。
• set_collapsed_recursive(enable)：折叠/展开该条目及其全部后代。
• uncollapse_tree()：展开所有祖先条目，使当前条目在树中可见（类似"定位到该节点并展开路径"）。
• is_any_collapsed(only_visible = false)：该条目或其任一后代是否处于折叠状态；only_visible为true时忽略不可见条目。

单元格内嵌按钮：add_button 与信号联动

TreeItem可以在单元格内嵌入任意数量的按钮（见 class_treeitem.rst）：

• add_button(column, button, id = -1, disabled = false, tooltip_text = "", description = "")：把Texture2D按钮追加到列末尾。id用于在Tree.button_clicked信号中识别按钮，可以不同于按钮索引；不指定时使用下一个可用索引（可在调用前用get_button_count()查询）。description为辅助应用提供按钮描述。
• set_button(column, button_index, button)/get_button(column, button_index)：替换/获取指定索引的按钮纹理。
• set_button_color(column, button_index, color)/get_button_color(column, id)：按钮着色；注意查询接口按 ID 而非索引，按钮不存在时返回Color.BLACK。
• set_button_disabled(column, button_index, disabled)/is_button_disabled(column, button_index)：禁用/启用按钮。
• set_button_tooltip_text(column, button_index, tooltip)/get_button_tooltip_text(column, button_index)：按钮悬浮提示。
• set_button_description(column, button_index, description)：按钮的辅助描述。
• get_button_count(column)：列中的按钮数量。
• get_button_id(column, button_index)：按索引取 ID；get_button_by_id(column, id)：按 ID 反查索引，不存在时返回-1。
• erase_button(column, button_index)：移除指定按钮；clear_buttons()：清空所有按钮。

按钮被点击时，Tree发出button_clicked(item, column, id, mouse_button_index)信号（见 class_tree.rst），你可以用它实现"行内操作按钮"（删除、重命名、收藏等）：

func _ready(): $Tree.button_clicked.connect(_on_button_clicked) func _on_button_clicked(item: TreeItem, column: int, id: int, mouse_button_index: int): if id == 1: # 自定义的按钮 ID item.set_text(column, "已点击")

自定义绘制：CELL_MODE_CUSTOM 与 Callable 回调

CELL_MODE_CUSTOM模式配合自定义绘制，可以做出高度定制化的单元格（见 class_treeitem.rst）：

• set_custom_draw_callback(column, callback)/get_custom_draw_callback(column)：设置列的自定义绘制回调。回调接收两个参数：被绘制的TreeItem和它的位置与尺寸（Rect2）。用空Callable()清除回调。必须把单元格设为CELL_MODE_CUSTOM才能使用此功能。
• set_custom_draw(column, object, callback)：旧版 API，已标记为Deprecated，请改用set_custom_draw_callback()。
• set_custom_as_button(column, enable)/is_custom_set_as_button(column)：让CELL_MODE_CUSTOM单元格以带StyleBox的非扁平按钮外观显示。
• 若要在原生样式之上叠加绘制内容，请使用Tree.get_custom_drawing_canvas_item()返回的画布项（该画布项会在每次 Tree 重绘时自动清空，见 class_tree.rst）。

与该模式配套的Tree信号还包括：点击自定义单元格时发出的custom_item_clicked(mouse_button_index)、进入编辑时发出的custom_popup_edited(arrow_clicked)，以及配合Tree.get_custom_popup_rect()实现自定义弹出控件（见 class_tree.rst）。

实战组合：一个带按钮、复选框与下拉的多列文件树

把上述 API 组合起来，可以快速构建一个实用的多列树形界面：

extends Control func _ready(): var tree := Tree.new() tree.columns = 3 tree.set_column_titles_visible(true) tree.set_column_title(0, "名称") tree.set_column_title(1, "大小") tree.set_column_title(2, "类型") add_child(tree) var root := tree.create_item() tree.hide_root = true var dir := tree.create_item(root) dir.set_text(0, "assets") dir.set_icon(0, preload("res://icon_folder.png")) dir.set_cell_mode(0, TreeItem.CELL_MODE_CHECK) dir.set_editable(0, true) var file := tree.create_item(dir) file.set_text(0, "player.gd") file.set_icon(0, preload("res://icon_script.png")) file.set_cell_mode(1, TreeItem.CELL_MODE_RANGE) file.set_range_config(1, 0.0, 100.0, 0.1) file.set_range(1, 24.5) file.set_suffix(1, " KB") file.set_cell_mode(2, TreeItem.CELL_MODE_CUSTOM) file.add_button(2, preload("res://icon_menu.png"), 1, false, "打开菜单") file.set_metadata(0, {"path": "res://player.gd"}) # 响应按钮点击 tree.button_clicked.connect(func(item, column, id, mouse): if id == 1: print(item.get_metadata(0)) )

小结

TreeItem是 GodotTree控件的"细胞"：通过create_item()/create_child()构建层级，用TreeCellMode五种模式决定单元格形态（文本、复选框、范围/下拉、图标、自定义按钮），再叠加图标、颜色、字体、按钮与自定义绘制能力，即可实现从简单列表到复杂属性编辑器的各类树形界面。完整的方法与属性清单、默认值与注意事项，均可查阅 class_treeitem.rst，与之配套的信号、光标、拖放与增量搜索行为见 class_tree.rst。

• 文档
• 教程
• 游戏开发