Tree

继承： Control < CanvasItem < Node < Object

用于以层级结构显示一组内部 TreeItem 的控件。

描述

用于以层级结构显示一组内部 TreeItem 的控件。树项目可以选择、展开、折叠。该树可以有多列的自定义控件，如 LineEdit、按钮和弹出窗口。对于结构化显示和互动很有用。

树通过代码建立，使用 TreeItem 对象来构建结构。根项目只有一个，但可以使用 hide_root 来模拟多个根项目。

GDScriptC#

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 修改超时时长。

属性

方法

主题属性

信号

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 结合时，这些放置部分的高度减半，并相应地停留在顶部或底部。

属性说明

bool allow_reselect = false 🔗

• void set_allow_reselect(value: bool)

• bool get_allow_reselect()

如果为 true，可以再次选择当前选定的单元。

bool allow_rmb_select = false 🔗

• void set_allow_rmb_select(value: bool)

• bool get_allow_rmb_select()

如果为 true，鼠标右键点击可以选择项目。

bool allow_search = true 🔗

• void set_allow_search(value: bool)

• bool get_allow_search()

如果为 true，允许在 Tree 中以增量搜索的形式使用字母键导航。

bool column_titles_visible = false 🔗

• void set_column_titles_visible(value: bool)

• bool are_column_titles_visible()

如果为 true，列标题可见。

int columns = 1 🔗

• void set_columns(value: int)

• int get_columns()

列数。

int drop_mode_flags = 0 🔗

• void set_drop_mode_flags(value: int)

• int get_drop_mode_flags()

放置模式是标志的按位或（OR）组合。见 DropModeFlags 常量。放置完成后会恢复为 DROP_MODE_DISABLED。建议在 Control._can_drop_data 期间设置。

控制的是放置区，即根据鼠标的位置决定并绘制可能的放置位置。

bool enable_recursive_folding = true 🔗

• void set_enable_recursive_folding(value: bool)

• bool is_recursive_folding_enabled()

如果为 true，则该 Tree 启用了递归折叠。按住 Shift 键点击折叠箭头或使用快捷键 ui_right/ui_left 会折叠或展开该 TreeItem 及所有子项。

bool hide_folding = false 🔗

• void set_hide_folding(value: bool)

• bool is_folding_hidden()

如果为 true，隐藏折叠箭头。

bool hide_root = false 🔗

• void set_hide_root(value: bool)

• bool is_root_hidden()

如果为 true，则隐藏树的根节点。

bool scroll_horizontal_enabled = true 🔗

• void set_h_scroll_enabled(value: bool)

• bool is_h_scroll_enabled()

如果为 true，启用水平滚动。

bool scroll_vertical_enabled = true 🔗

• void set_v_scroll_enabled(value: bool)

• bool is_v_scroll_enabled()

如果为 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。

TreeItem get_edited() const 🔗

返回当前编辑的项。可以与 item_edited 一起使用以获取被修改的项。

GDScriptC#

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 🔗

返回最后按下的按钮的索引。

TreeItem get_root() const 🔗

返回树的根项，如果树是空的，则返回 null。

Vector2 get_scroll() const 🔗

返回当前的滚动位置。

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_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 button_margin = 4 🔗

单元格中按钮之间的水平间距。

int children_hl_line_width = 1 🔗

被选中的 TreeItem 与其子项之间的关系线的宽度。

int draw_guides = 1 🔗

如果不为零就绘制参考线，行为类似于布尔值。参考线是在每个项的底部画的一条水平线。

int draw_relationship_lines = 0 🔗

如果不为零就绘制关系线，行为类似于布尔值。关系线在子项的开始处绘制，以显示层次结构。

int h_separation = 4 🔗

项目单元之间的水平空间。这也用作禁用折叠时项目开头的边距。

int icon_max_width = 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 🔗

单元格顶部的内边距。

int item_margin = 16 🔗

项目开头的水平边距。在项目启用折叠功能时使用。

int outline_size = 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 scroll_border = 4 🔗

拖动时，鼠标指针与控件边框之间触发边框滚动的最大距离。

int scroll_speed = 12 🔗

边框滚动的速度。

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 🔗

树中内容与滚动条的垂直间距。

int v_separation = 4 🔗

每个项内的垂直填充，即项内容与上或下边框之间的距离。

Font font 🔗

项目文本的字体 Font 。

Font title_button_font 🔗

标题按钮文本的 Font 字体。

int font_size 🔗

项目文本的字体大小。

int title_button_font_size 🔗

标题按钮文本的字体大小。

Texture2D arrow 🔗

箭头图标，可折叠项未折叠时使用。

Texture2D arrow_collapsed 🔗

箭头图标，可折叠项已折叠时使用（用于从左至右布局）。

Texture2D arrow_collapsed_mirrored 🔗

箭头图标，可折叠项已折叠时使用（用于从右至左布局）。

Texture2D checked 🔗

复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于勾选状态并且可编辑时显示（见 TreeItem.set_editable）。

Texture2D checked_disabled 🔗

复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于勾选状态并且不可编辑时显示（见 TreeItem.set_editable）。

Texture2D indeterminate 🔗

复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于中间状态并且可编辑时显示（见 TreeItem.set_editable）。

Texture2D indeterminate_disabled 🔗

复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于中间状态并且不可编辑时显示（见 TreeItem.set_editable）。

Texture2D select_arrow 🔗

箭头图标，模式为 TreeItem.CELL_MODE_RANGE 的单元格显示。

Texture2D unchecked 🔗

复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于未选中状态并且可编辑时显示（见 TreeItem.set_editable）。

Texture2D unchecked_disabled 🔗

复选图标，模式为 TreeItem.CELL_MODE_CHECK 的单元格处于未选中状态并且不可编辑时显示（见 TreeItem.set_editable）。

Texture2D updown 🔗

上下箭头图标，模式为 TreeItem.CELL_MODE_RANGE 的单元格显示。

StyleBox button_pressed 🔗

树中的按钮处于按下状态时使用的 StyleBox。

StyleBox cursor 🔗

用作光标的 StyleBox，该 Tree 处于聚焦状态时使用。

StyleBox cursor_unfocused 🔗

用作光标的 StyleBox，该 Tree 处于失焦状态时使用。

StyleBox custom_button 🔗

当使用 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。

StyleBox focus 🔗

该 Tree 的聚焦样式，绘制在所有东西之上。

StyleBox panel 🔗

该 Tree 的背景样式。

StyleBox selected 🔗

所选项目的 StyleBox，在 Tree 没有获得焦点时使用。

StyleBox selected_focus 🔗

所选项目的 StyleBox，在 Tree 获得焦点时使用。

StyleBox title_button_hover 🔗

当标题按钮被悬停时使用的 StyleBox。

StyleBox title_button_normal 🔗

标题按钮的默认 StyleBox。

StyleBox title_button_pressed 🔗

当标题按钮被按下时使用的 StyleBox。