Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Tree
继承： Control < CanvasItem < Node < Object
用于以层级结构显示一组内部 TreeItem 的控件。
描述
用于以层级结构显示一组内部 TreeItem 的控件。树项目可以选择、展开、折叠。该树可以有多列的自定义控件，如 LineEdit、按钮和弹出窗口。对于结构化显示和互动很有用。
树通过代码建立，使用 TreeItem 对象来构建结构。根项目只有一个，但可以使用 hide_root 来模拟多个根项目。
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");
}
要遍历 Tree 对象中的所有 TreeItem 对象，请在通过 get_root() 获得根项目之后，使用 TreeItem.get_next() 和 TreeItem.get_children() 方法。你可以对 TreeItem 使用 Object.free() 来把它从 Tree 中移除。
增量搜索：与 ItemList 和 PopupMenu 类似，Tree 也支持在聚焦控件时在列表中进行搜索。按下与某个条目名称首字母一致的按键，就会选中以该字母开头的第一个条目。在此之后，进行增量搜索的办法有两种：1）在超时前再次按下同一个按键，选中以该字母开头的下一个条目。2）在超时前按下剩余字母对应的按键，直接匹配并选中所需的条目。这两个动作都会在最后一次按键超时后重置回列表顶端。你可以通过 ProjectSettings.gui/timers/incremental_search_max_interval_msec 修改超时时长。
属性
|
||
|
||
|
||
|
||
clip_contents |
|
|
|
||
|
||
|
||
|
||
focus_mode |
|
|
|
||
|
||
|
||
|
||
|
方法
主题属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
信号
button_clicked(item: TreeItem, column: int, id: int, mouse_button_index: int) 🔗
按下树中的某个按钮时发出（见 TreeItem.add_button()）。
cell_selected() 🔗
选中某个单元格时发出。
check_propagated_to_item(item: TreeItem, column: int) 🔗
调用 TreeItem.propagate_check() 时发出。连接到该信号可以处理在 TreeItem.propagate_check() 被调用时受影响的项。受影响项的处理顺序如下：调用该方法的项，该项的子项，最后是该项的父项。
column_title_clicked(column: int, mouse_button_index: int) 🔗
使用 @GlobalScope.MOUSE_BUTTON_LEFT 使用 @GlobalScope.MOUSE_BUTTON_RIGHT 点击某一列的标题时发出。
custom_item_clicked(mouse_button_index: int) 🔗
使用鼠标按钮点击某一 TreeItem.CELL_MODE_CUSTOM 项时发出。
custom_popup_edited(arrow_clicked: bool) 🔗
点击某一 TreeItem.CELL_MODE_CUSTOM 项进行编辑时发出。
empty_clicked(click_position: Vector2, mouse_button_index: int) 🔗
使用鼠标按钮点击该树中的空白区域时发出。
item_activated() 🔗
双击某一项，或使用 ui_accept 输入事件（例如键盘的回车或空格键）选中某一项时发出。
item_collapsed(item: TreeItem) 🔗
点击折叠箭头折叠某一项时发出。
item_edited() 🔗
编辑某一项时发出。
item_icon_double_clicked() 🔗
双击某一项的图标时发出。双击该项的任意区域所发出的信号见 item_activated。
item_mouse_selected(mouse_position: Vector2, mouse_button_index: int) 🔗
使用鼠标按钮选中某一项时发出。
item_selected() 🔗
选中某一项时发出。
multi_selected(item: TreeItem, column: int, selected: bool) 🔗
如果 select_mode 被设置为 SELECT_MULTI，则代替 item_selected 发出。
nothing_selected() 🔗
鼠标左键未选中任一项时发出。
枚举
enum SelectMode: 🔗
SelectMode SELECT_SINGLE = 0
允许一次选择一个单元格。从项的角度看，只允许选择一个项。而且在所选项中只有一列被选中。
在这种模式下，焦点光标总被隐藏，被定位在当前的选择处，使当前的选择项成为当前的焦点项。
SelectMode SELECT_ROW = 1
允许一次选择单行。从项的角度看，只允许选择单个项。而所有的列都被选择在所选项中。
在这种模式下，焦点光标总被隐藏，被定位在当前选择的第一列，使当前选择项成为当前焦点项。
SelectMode SELECT_MULTI = 2
允许同时选择多个单元格。从项的角度看，允许选择多个项。而且每个被选中的项中可以有多个列被选中。
在这种模式下，焦点光标可见，光标下的项或列不一定被选中。
enum DropModeFlags: 🔗
DropModeFlags DROP_MODE_DISABLED = 0
禁用所有放置部分，但仍然允许通过 get_drop_section_at_position() 检测“项目上”的放置部分。
注意：这是默认的标志，当与其他标志结合时，它没有效果。
DropModeFlags DROP_MODE_ON_ITEM = 1
启用“项目上”的放置部分。这个放置部分覆盖整个项。
当与 DROP_MODE_INBETWEEN 结合使用时，这个放置部分的高度减半，并保持垂直居中。
DropModeFlags DROP_MODE_INBETWEEN = 2
启用“项目上方”和“项目下方”的放置部分。“项目上方”的放置部分覆盖项目的上半部分，“项目下方”的放置部分覆盖下半部分。
当与 DROP_MODE_ON_ITEM 结合时，这些放置部分的高度减半，并相应地停留在顶部或底部。
属性说明
如果为 true，可以再次选择当前选定的单元。
bool allow_rmb_select = false 🔗
如果为 true，鼠标右键点击可以选择项目。
如果为 true，允许在 Tree 中以增量搜索的形式使用字母键导航。
如果为 true，则未分配工具提示的树项目会使用其文本属性作为工具提示。另见 TreeItem.get_tooltip_text() 和 TreeItem.get_button_tooltip_text()。
bool column_titles_visible = false 🔗
如果为 true，列标题可见。
列数。
放置模式是标志的按位或（OR）组合。见 DropModeFlags 常量。放置完成后会恢复为 DROP_MODE_DISABLED。建议在 Control._can_drop_data() 期间设置。
控制的是放置区，即根据鼠标的位置决定并绘制可能的放置位置。
bool enable_recursive_folding = true 🔗
如果为 true，则该 Tree 启用了递归折叠。按住 Shift 键点击折叠箭头或使用快捷键 ui_right/ui_left 会折叠或展开该 TreeItem 及所有子项。
如果为 true，隐藏折叠箭头。
如果为 true，则隐藏树的根节点。
bool scroll_horizontal_enabled = true 🔗
如果为 true，启用水平滚动。
bool scroll_vertical_enabled = true 🔗
如果为 true，则启用垂直滚动。
SelectMode select_mode = 0 🔗
void set_select_mode(value: SelectMode)
SelectMode get_select_mode()
允许单选或多选。见 SelectMode 常量。
方法说明
void clear() 🔗
清除树。这将删除所有项目。
TreeItem create_item(parent: TreeItem = null, index: int = -1) 🔗
在树中创建一个项，并将其添加为父项 parent 的子项，该父项可以是一个有效的 TreeItem 或 null。
如果 parent 为 null，则根项将是父项；或者如果该树为空，则该新项将是根本身。
新项将是父项的第 index 个子项，如果没有足够的同级项，它将是最后一个子项。
void deselect_all() 🔗
取消选中树中的所有项目（行和列）。在 SELECT_MULTI 模式中还会移除选择光标。
bool edit_selected(force_edit: bool = false) 🔗
编辑选中的树项，就像它被点击一样。
该项必须通过 TreeItem.set_editable() 设置为可编辑，否则 force_edit 必须为 true。
如果该项可被编辑，则返回 true。如果没有选中任何项则失败。
void ensure_cursor_is_visible() 🔗
使当前获得焦点的单元可见。
如果有必要，将滚动树。在 SELECT_ROW 模式下，不会做水平滚动，因为所选行中的所有单元都按逻辑获得焦点。
注意：尽管这个方法的名称是这样的，但焦点光标本身只在 SELECT_MULTI 模式下可见。
int get_button_id_at_position(position: Vector2) const 🔗
返回位于 position 的按钮 ID，如果没有按钮则返回 -1。
int get_column_at_position(position: Vector2) const 🔗
返回位于 position 的列索引，如果没有项目则返回 -1。
int get_column_expand_ratio(column: int) const 🔗
返回分配给该列的扩展比例。
String get_column_title(column: int) const 🔗
返回该列的标题。
HorizontalAlignment get_column_title_alignment(column: int) const 🔗
返回该列的标题对齐方式。
TextDirection get_column_title_direction(column: int) const 🔗
返回列标题的基础书写方向。
String get_column_title_language(column: int) const 🔗
返回列标题的语言代码。
int get_column_width(column: int) const 🔗
返回列的宽度，单位是像素。
Rect2 get_custom_popup_rect() const 🔗
返回自定义弹出窗口的矩形。帮助创建显示弹出式的自定义单元格控件。见 TreeItem.set_cell_mode()。
int get_drop_section_at_position(position: Vector2) const 🔗
返回位于 position 的放置部分，如果没有项目，则返回 -100。
在“项目上方”“项目之上”和“项目下方”的放置部分将分别返回 -1、0 或 1 的值。请参阅 DropModeFlags 以了解每个放置部分的描述。
要获得返回的放置部分相对项，请使用 get_item_at_position()。
返回当前编辑的项。可以与 item_edited 一起使用以获取被修改的项。
func _ready():
$Tree.item_edited.connect(on_Tree_item_edited)
func on_Tree_item_edited():
print($Tree.get_edited()) # 该项刚刚被编辑（例如被勾选）。
public override void _Ready()
{
GetNode<Tree>("Tree").ItemEdited += OnTreeItemEdited;
}
public void OnTreeItemEdited()
{
GD.Print(GetNode<Tree>("Tree").GetEdited()); // 该项刚刚被编辑（例如被勾选）。
}
int get_edited_column() const 🔗
返回当前编辑项的列。
Rect2 get_item_area_rect(item: TreeItem, column: int = -1, button_index: int = -1) const 🔗
返回指定 TreeItem 的矩形区域。如果指定了column，则只获取该列的位置和大小，否则获取包含所有列的矩形。如果指定了按钮索引，则将返回该按钮的矩形。
TreeItem get_item_at_position(position: Vector2) const 🔗
返回指定位置，即相对于树的原点位置的树中项。
TreeItem get_next_selected(from: TreeItem) 🔗
返回给定的 TreeItem 之后的下一个选中项，如果到达末尾，则返回 null。
如果 from 为 null，则将返回第一个被选中的项。
int get_pressed_button() const 🔗
返回最后按下的按钮的索引。
返回树的根项，如果树是空的，则返回 null。
返回当前的滚动位置。
TreeItem get_selected() const 🔗
返回当前的焦点项，如果没有焦点项，则返回 null。
在 SELECT_ROW 和 SELECT_SINGLE 模式下，焦点项与选择项相同。在 SELECT_MULTI 模式下，焦点项是焦点光标下的项目，不一定被选中。
要获得当前选中项，请使用 get_next_selected()。
int get_selected_column() const 🔗
返回当前获得焦点的列，如果没有焦点列，则返回 -1。
在 SELECT_SINGLE 模式下，焦点列是被选中的列。在 SELECT_ROW 模式下，如果有任意项被选中，焦点列总是 0。在 SELECT_MULTI 模式下，焦点列是焦点光标下的列，但不一定有列被选中。
要判断一个项的某一列是否被选中，请使用 TreeItem.is_selected()。
bool is_column_clipping_content(column: int) const 🔗
如果该列启用了裁剪，则返回 true（见 set_column_clip_content()）。
bool is_column_expanding(column: int) const 🔗
如果该列启用了扩展，则返回 true（见 set_column_expand()）。
void scroll_to_item(item: TreeItem, center_on_item: bool = false) 🔗
使 Tree 跳转到指定的 TreeItem。
void set_column_clip_content(column: int, enable: bool) 🔗
允许对列的内容进行裁剪，会忽略内容大小。
void set_column_custom_minimum_width(column: int, min_width: int) 🔗
覆盖某一列的计算的最小宽度。它可以被设置为 0 以恢复默认行为。具有“扩展”标志的列将以与 Control.size_flags_stretch_ratio 类似的方式使用它们的最小宽度“min_width”。
void set_column_expand(column: int, expand: bool) 🔗
如果为 true，该列将具有 Control 的“Expand”标志。具有“Expand”标志的列将以与 Control.size_flags_stretch_ratio 类似的方式，使用它们的扩展比率（参见 set_column_expand_ratio()）。
void set_column_expand_ratio(column: int, ratio: int) 🔗
设置列的相对扩展比。见 set_column_expand()。
void set_column_title(column: int, title: String) 🔗
设置某一列的标题。
void set_column_title_alignment(column: int, title_alignment: HorizontalAlignment) 🔗
设置列标题的对齐方式。注意，列标题不支持 @GlobalScope.HORIZONTAL_ALIGNMENT_FILL。
void set_column_title_direction(column: int, direction: TextDirection) 🔗
设置列标题的基础书写方向。
void set_column_title_language(column: int, language: String) 🔗
设置列标题的语言代码，用于断行和文本塑形算法，如果留空则使用当前区域设置。
void set_selected(item: TreeItem, column: int) 🔗
选中指定的 TreeItem 和列。
主题属性说明
Color children_hl_line_color = Color(0.27, 0.27, 0.27, 1) 🔗
被选中的 TreeItem 与其子项之间的关系线的 Color。
Color custom_button_font_highlight = Color(0.95, 0.95, 0.95, 1) 🔗
当 TreeItem.CELL_MODE_CUSTOM 模式的单元格被悬停时的文本 Color 颜色。
Color drop_position_color = Color(1, 1, 1, 1) 🔗
用于绘制可能的放置位置的 Color 颜色。有关放置位置的描述，参阅 DropModeFlags 常量。
Color font_color = Color(0.7, 0.7, 0.7, 1) 🔗
项目的默认文本颜色 Color。
Color font_disabled_color = Color(0.875, 0.875, 0.875, 0.5) 🔗
当不可编辑时，TreeItem.CELL_MODE_CHECK 模式单元格的文本 Color（请参阅 TreeItem.set_editable()）。
Color font_hovered_color = Color(0.95, 0.95, 0.95, 1) 🔗
项目处于悬停状态时使用的文本颜色 Color。
Color font_hovered_dimmed_color = Color(0.875, 0.875, 0.875, 1) 🔗
项目处于悬停状态且该项目的某个按钮也同时处于悬停状态时使用的文本颜色 Color。
Color font_outline_color = Color(0, 0, 0, 1) 🔗
项目文本轮廓的色调。
Color font_selected_color = Color(1, 1, 1, 1) 🔗
选择项目时使用的文本颜色 Color。
Color guide_color = Color(0.7, 0.7, 0.7, 0.25) 🔗
参考线的 Color 颜色。
Color parent_hl_line_color = Color(0.27, 0.27, 0.27, 1) 🔗
被选中的 TreeItem 与其父项之间的关系线的 Color。
Color relationship_line_color = Color(0.27, 0.27, 0.27, 1) 🔗
关系线的默认 Color。
Color title_button_color = Color(0.875, 0.875, 0.875, 1) 🔗
标题按钮的默认文本 Color 颜色。
单元格中按钮之间的水平间距。
int children_hl_line_width = 1 🔗
被选中的 TreeItem 与其子项之间的关系线的宽度。
如果不为零就绘制参考线，行为类似于布尔值。参考线是在每个项的底部画的一条水平线。
int draw_relationship_lines = 0 🔗
如果不为零就绘制关系线，行为类似于布尔值。关系线在子项的开始处绘制，以显示层次结构。
项目单元之间的水平空间。这也用作禁用折叠时项目开头的边距。
项目单元格所允许的最大图标宽度。这是在图标默认大小的基础上的限制，在 TreeItem.set_icon_max_width() 所设置的值之前生效。高度会根据图标的长宽比调整。
int inner_item_margin_bottom = 0 🔗
单元格底部的内边距。
int inner_item_margin_left = 0 🔗
单元格左侧的内边距。
int inner_item_margin_right = 0 🔗
单元格右侧的内边距。
int inner_item_margin_top = 0 🔗
单元格顶部的内边距。
项目开头的水平边距。在项目启用折叠功能时使用。
文字轮廓的大小。
注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。
int parent_hl_line_margin = 0 🔗
被选中的 TreeItem 的父关系线，与其未选中的同级的关系线，两者之间的空间。
int parent_hl_line_width = 1 🔗
被选中的 TreeItem 与其父项之间的关系线的宽度。
int relationship_line_width = 1 🔗
关系线的默认宽度。
拖动时，鼠标指针与控件边框之间触发边框滚动的最大距离。
边框滚动的速度。
int scrollbar_h_separation = 4 🔗
树中内容与滚动条的水平间距。
int scrollbar_margin_bottom = -1 🔗
滚动条的底部边距。为负数时会使用 panel 的底部边距。
int scrollbar_margin_left = -1 🔗
水平滚动条的左侧边距。为负数时会使用 panel 的左侧边距。
int scrollbar_margin_right = -1 🔗
滚动条的右侧边距。为负数时会使用 panel 的右侧边距。
int scrollbar_margin_top = -1 🔗
垂直滚动条的顶部边距。为负数时会使用 panel 的顶部边距。
int scrollbar_v_separation = 4 🔗
树中内容与滚动条的垂直间距。
每个项内的垂直填充，即项内容与上或下边框之间的距离。
项目文本的字体 Font 。
标题按钮文本的 Font 字体。
项目文本的字体大小。
标题按钮文本的字体大小。
箭头图标，可折叠项未折叠时使用。
箭头图标，可折叠项已折叠时使用（用于从左至右布局）。
Texture2D arrow_collapsed_mirrored 🔗
箭头图标，可折叠项已折叠时使用（用于从右至左布局）。
复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于勾选状态并且可编辑时显示（见 TreeItem.set_editable()）。
复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于勾选状态并且不可编辑时显示（见 TreeItem.set_editable()）。
复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于中间状态并且可编辑时显示（见 TreeItem.set_editable()）。
Texture2D indeterminate_disabled 🔗
复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于中间状态并且不可编辑时显示（见 TreeItem.set_editable()）。
箭头图标，模式为 TreeItem.CELL_MODE_RANGE 的单元格显示。
复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于未选中状态并且可编辑时显示（见 TreeItem.set_editable()）。
Texture2D unchecked_disabled 🔗
复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于未选中状态并且不可编辑时显示（见 TreeItem.set_editable()）。
上下箭头图标，模式为 TreeItem.CELL_MODE_RANGE 的单元格显示。
树中的按钮处于悬停状态时使用的 StyleBox。
树中的按钮处于按下状态时使用的 StyleBox。
用作光标的 StyleBox，该 Tree 处于聚焦状态时使用。
用作光标的 StyleBox，该 Tree 处于失焦状态时使用。
当使用 TreeItem.set_custom_as_button() 启用按钮时，TreeItem.CELL_MODE_CUSTOM 模式单元格的默认 StyleBox。
StyleBox custom_button_hover 🔗
模式为 TreeItem.CELL_MODE_CUSTOM 的按钮单元格处于悬停状态时的 StyleBox。
StyleBox custom_button_pressed 🔗
模式为 TreeItem.CELL_MODE_CUSTOM 的按钮单元格处于按下状态时的 StyleBox。
该 Tree 的聚焦样式，绘制在所有东西之上。
项目处于悬停状态时使用的 StyleBox。
项目处于悬停状态且该项目的某个按钮也同时处于悬停状态时使用的 StyleBox。
该 Tree 的背景样式。
所选项目的 StyleBox，在 Tree 没有获得焦点时使用。
所选项目的 StyleBox，在 Tree 获得焦点时使用。
当标题按钮被悬停时使用的 StyleBox。
StyleBox title_button_normal 🔗
标题按钮的默认 StyleBox。
StyleBox title_button_pressed 🔗
当标题按钮被按下时使用的 StyleBox。