Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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")

要遍历 Tree 对象中的所有 TreeItem 对象,请在通过 get_root 获得根项目之后,使用 TreeItem.get_nextTreeItem.get_children 方法。你可以对 TreeItem 使用 Object.free 来把它从 Tree 中移除。

增量搜索:ItemListPopupMenu 类似,Tree 也支持在聚焦控件时在列表中进行搜索。按下与某个条目名称首字母一致的按键,就会选中以该字母开头的第一个条目。在此之后,进行增量搜索的办法有两种:1)在超时前再次按下同一个按键,选中以该字母开头的下一个条目。2)在超时前按下剩余字母对应的按键,直接匹配并选中所需的条目。这两个动作都会在最后一次按键超时后重置回列表顶端。你可以通过 ProjectSettings.gui/timers/incremental_search_max_interval_msec 修改超时时长。

属性

bool

allow_reselect

false

bool

allow_rmb_select

false

bool

allow_search

true

bool

clip_contents

true (overrides Control)

bool

column_titles_visible

false

int

columns

1

int

drop_mode_flags

0

bool

enable_recursive_folding

true

FocusMode

focus_mode

2 (overrides Control)

bool

hide_folding

false

bool

hide_root

false

bool

scroll_horizontal_enabled

true

bool

scroll_vertical_enabled

true

SelectMode

select_mode

0

方法

void

clear ( )

TreeItem

create_item ( TreeItem parent=null, int index=-1 )

void

deselect_all ( )

bool

edit_selected ( bool force_edit=false )

void

ensure_cursor_is_visible ( )

int

get_button_id_at_position ( Vector2 position ) const

int

get_column_at_position ( Vector2 position ) const

int

get_column_expand_ratio ( int column ) const

String

get_column_title ( int column ) const

HorizontalAlignment

get_column_title_alignment ( int column ) const

TextDirection

get_column_title_direction ( int column ) const

String

get_column_title_language ( int column ) const

int

get_column_width ( int column ) const

Rect2

get_custom_popup_rect ( ) const

int

get_drop_section_at_position ( Vector2 position ) const

TreeItem

get_edited ( ) const

int

get_edited_column ( ) const

Rect2

get_item_area_rect ( TreeItem item, int column=-1, int button_index=-1 ) const

TreeItem

get_item_at_position ( Vector2 position ) const

TreeItem

get_next_selected ( TreeItem from )

int

get_pressed_button ( ) const

TreeItem

get_root ( ) const

Vector2

get_scroll ( ) const

TreeItem

get_selected ( ) const

int

get_selected_column ( ) const

bool

is_column_clipping_content ( int column ) const

bool

is_column_expanding ( int column ) const

void

scroll_to_item ( TreeItem item, bool center_on_item=false )

void

set_column_clip_content ( int column, bool enable )

void

set_column_custom_minimum_width ( int column, int min_width )

void

set_column_expand ( int column, bool expand )

void

set_column_expand_ratio ( int column, int ratio )

void

set_column_title ( int column, String title )

void

set_column_title_alignment ( int column, HorizontalAlignment title_alignment )

void

set_column_title_direction ( int column, TextDirection direction )

void

set_column_title_language ( int column, String language )

void

set_selected ( TreeItem item, int column )

主题属性

Color

children_hl_line_color

Color(0.27, 0.27, 0.27, 1)

Color

custom_button_font_highlight

Color(0.95, 0.95, 0.95, 1)

Color

drop_position_color

Color(1, 1, 1, 1)

Color

font_color

Color(0.7, 0.7, 0.7, 1)

Color

font_outline_color

Color(1, 1, 1, 1)

Color

font_selected_color

Color(1, 1, 1, 1)

Color

guide_color

Color(0.7, 0.7, 0.7, 0.25)

Color

parent_hl_line_color

Color(0.27, 0.27, 0.27, 1)

Color

relationship_line_color

Color(0.27, 0.27, 0.27, 1)

Color

title_button_color

Color(0.875, 0.875, 0.875, 1)

int

button_margin

4

int

children_hl_line_width

1

int

draw_guides

1

int

draw_relationship_lines

0

int

h_separation

4

int

icon_max_width

0

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

int

parent_hl_line_margin

0

int

parent_hl_line_width

1

int

relationship_line_width

1

int

scroll_border

4

int

scroll_speed

12

int

scrollbar_h_separation

4

int

scrollbar_margin_bottom

-1

int

scrollbar_margin_left

-1

int

scrollbar_margin_right

-1

int

scrollbar_margin_top

-1

int

scrollbar_v_separation

4

int

v_separation

4

Font

font

Font

title_button_font

int

font_size

int

title_button_font_size

Texture2D

arrow

Texture2D

arrow_collapsed

Texture2D

arrow_collapsed_mirrored

Texture2D

checked

Texture2D

indeterminate

Texture2D

select_arrow

Texture2D

unchecked

Texture2D

updown

StyleBox

button_pressed

StyleBox

cursor

StyleBox

cursor_unfocused

StyleBox

custom_button

StyleBox

custom_button_hover

StyleBox

custom_button_pressed

StyleBox

focus

StyleBox

panel

StyleBox

selected

StyleBox

selected_focus

StyleBox

title_button_hover

StyleBox

title_button_normal

StyleBox

title_button_pressed


信号

button_clicked ( TreeItem item, int column, int id, int mouse_button_index )

按下树中的某个按钮时发出(见 TreeItem.add_button)。


cell_selected ( )

选中某个单元格时发出。


check_propagated_to_item ( TreeItem item, int column )

调用 TreeItem.propagate_check 时发出。连接到该信号可以处理在 TreeItem.propagate_check 被调用时受影响的项。受影响项的处理顺序如下:调用该方法的项,该项的子项,最后是该项的父项。


column_title_clicked ( int column, int mouse_button_index )

使用 @GlobalScope.MOUSE_BUTTON_LEFT 使用 @GlobalScope.MOUSE_BUTTON_RIGHT 点击某一列的标题时发出。


custom_item_clicked ( int mouse_button_index )

使用鼠标按钮点击某一 TreeItem.CELL_MODE_CUSTOM 项时发出。


custom_popup_edited ( bool arrow_clicked )

点击某一 TreeItem.CELL_MODE_CUSTOM 项进行编辑时发出。


empty_clicked ( Vector2 position, int mouse_button_index )

使用鼠标按钮点击该树中的空白区域时发出。


item_activated ( )

双击某一项,或使用 ui_accept 输入事件(例如键盘的回车空格键)选中某一项时发出。


item_collapsed ( TreeItem item )

点击折叠箭头折叠某一项时发出。


item_edited ( )

编辑某一项时发出。


item_icon_double_clicked ( )

双击某一项的图标时发出。双击该项的任意区域所发出的信号见 item_activated


item_mouse_selected ( Vector2 position, int mouse_button_index )

使用鼠标按钮选中某一项时发出。


item_selected ( )

选中某一项时发出。


multi_selected ( TreeItem item, int column, bool selected )

如果 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 ( bool value )

  • bool get_allow_reselect ( )

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


bool allow_rmb_select = false

  • void set_allow_rmb_select ( bool value )

  • bool get_allow_rmb_select ( )

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


  • void set_allow_search ( bool value )

  • bool get_allow_search ( )

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


bool column_titles_visible = false

  • void set_column_titles_visible ( bool value )

  • bool are_column_titles_visible ( )

如果为 true,列标题可见。


int columns = 1

  • void set_columns ( int value )

  • int get_columns ( )

列数。


int drop_mode_flags = 0

  • void set_drop_mode_flags ( int value )

  • int get_drop_mode_flags ( )

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

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


bool enable_recursive_folding = true

  • void set_enable_recursive_folding ( bool value )

  • bool is_recursive_folding_enabled ( )

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


bool hide_folding = false

  • void set_hide_folding ( bool value )

  • bool is_folding_hidden ( )

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


bool hide_root = false

  • void set_hide_root ( bool value )

  • bool is_root_hidden ( )

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


bool scroll_horizontal_enabled = true

  • void set_h_scroll_enabled ( bool value )

  • bool is_h_scroll_enabled ( )

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


bool scroll_vertical_enabled = true

  • void set_v_scroll_enabled ( bool value )

  • bool is_v_scroll_enabled ( )

如果为 true,则启用垂直滚动。


SelectMode select_mode = 0

允许单选或多选。见 SelectMode 常量。


方法说明

void clear ( )

清除树。这将删除所有项目。


TreeItem create_item ( TreeItem parent=null, int index=-1 )

在树中创建一个项,并将其添加为父项 parent 的子项,该父项可以是一个有效的 TreeItemnull

如果 parentnull,则根项将是父项;或者如果该树为空,则该新项将是根本身。

新项将是父项的第 index 个子项,如果没有足够的同级项,它将是最后一个子项。


void deselect_all ( )

取消选中树中的所有项目(行和列)。在 SELECT_MULTI 模式中还会移除选择光标。


bool edit_selected ( bool force_edit=false )

编辑选中的树项,就像它被点击一样。

该项必须通过 TreeItem.set_editable 设置为可编辑,否则 force_edit 必须为 true

如果该项可被编辑,则返回 true。如果没有选中任何项则失败。


void ensure_cursor_is_visible ( )

使当前获得焦点的单元可见。

如果有必要,将滚动树。在 SELECT_ROW 模式下,不会做水平滚动,因为所选行中的所有单元都按逻辑获得焦点。

注意:尽管这个方法的名称是这样的,但焦点光标本身只在 SELECT_MULTI 模式下可见。


int get_button_id_at_position ( Vector2 position ) const

返回位于 position 的按钮 ID,如果没有按钮则返回 -1。


int get_column_at_position ( Vector2 position ) const

返回位于 position 的列索引,如果没有项目则返回 -1。


int get_column_expand_ratio ( int column ) const

返回分配给该列的扩展比例。


String get_column_title ( int column ) const

返回该列的标题。


HorizontalAlignment get_column_title_alignment ( int column ) const

返回该列的标题对齐方式。


TextDirection get_column_title_direction ( int column ) const

返回列标题的基础书写方向。


String get_column_title_language ( int column ) const

返回列标题的语言代码。


int get_column_width ( int column ) const

返回列的宽度,单位是像素。


Rect2 get_custom_popup_rect ( ) const

返回自定义弹出窗口的矩形。帮助创建显示弹出式的自定义单元格控件。见 TreeItem.set_cell_mode


int get_drop_section_at_position ( Vector2 position ) const

返回位于 position 的放置部分,如果没有项目,则返回 -100。

在“项目上方”“项目之上”和“项目下方”的放置部分将分别返回 -1、0 或 1 的值。请参阅 DropModeFlags 以了解每个放置部分的描述。

要获得返回的放置部分相对项,请使用 get_item_at_position


TreeItem get_edited ( ) const

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

func _ready():
    $Tree.item_edited.connect(on_Tree_item_edited)

func on_Tree_item_edited():
    print($Tree.get_edited()) # 该项刚刚被编辑(例如被勾选)。

int get_edited_column ( ) const

返回当前编辑项的列。


Rect2 get_item_area_rect ( TreeItem item, int column=-1, int button_index=-1 ) const

返回指定 TreeItem 的矩形区域。如果指定了column,则只获取该列的位置和大小,否则获取包含所有列的矩形。如果指定了按钮索引,则将返回该按钮的矩形。


TreeItem get_item_at_position ( Vector2 position ) const

返回指定位置,即相对于树的原点位置的树中项。


TreeItem get_next_selected ( TreeItem from )

返回给定的 TreeItem 之后的下一个选中项,如果到达末尾,则返回 null

如果 fromnull,则将返回第一个被选中的项。


int get_pressed_button ( ) const

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


TreeItem get_root ( ) const

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


Vector2 get_scroll ( ) const

返回当前的滚动位置。


TreeItem get_selected ( ) const

返回当前的焦点项,如果没有焦点项,则返回 null

SELECT_ROWSELECT_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 ( int column ) const

如果该列启用了裁剪,则返回 true(见 set_column_clip_content)。


bool is_column_expanding ( int column ) const

如果该列启用了扩展,则返回 true(见 set_column_expand)。


void scroll_to_item ( TreeItem item, bool center_on_item=false )

使 Tree 跳转到指定的 TreeItem


void set_column_clip_content ( int column, bool enable )

允许对列的内容进行裁剪,会忽略内容大小。


void set_column_custom_minimum_width ( int column, int min_width )

覆盖某一列的计算的最小宽度。它可以被设置为 0 以恢复默认行为。具有“扩展”标志的列将以与 Control.size_flags_stretch_ratio 类似的方式使用它们的最小宽度“min_width”。


void set_column_expand ( int column, bool expand )

如果为 true,该列将具有 Control 的“Expand”标志。具有“Expand”标志的列将以与 Control.size_flags_stretch_ratio 类似的方式,使用它们的扩展比率(参见 set_column_expand_ratio)。


void set_column_expand_ratio ( int column, int ratio )

设置列的相对扩展比。见 set_column_expand


void set_column_title ( int column, String title )

设置某一列的标题。


void set_column_title_alignment ( int column, HorizontalAlignment title_alignment )

设置列标题的对齐方式。注意,列标题不支持 @GlobalScope.HORIZONTAL_ALIGNMENT_FILL


void set_column_title_direction ( int column, TextDirection direction )

设置列标题的基础书写方向。


void set_column_title_language ( int column, String language )

设置列标题的语言代码,用于断行和文本塑形算法,如果留空则使用当前区域设置。


void set_selected ( TreeItem item, int column )

选中指定的 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_outline_color = Color(1, 1, 1, 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 的单元格处于勾选状态时显示。


Texture2D indeterminate

复选图标,模式为 TreeItem.CELL_MODE_CHECK 的单元格处于中间状态时显示。


Texture2D select_arrow

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


Texture2D unchecked

复选图标,模式为 TreeItem.CELL_MODE_CHECK 的单元格处于未选状态时显示。


Texture2D updown

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


StyleBox button_pressed

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


StyleBox cursor

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


StyleBox cursor_unfocused

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


StyleBox custom_button

模式为 TreeItem.CELL_MODE_RANGE 的单元格的默认 StyleBox


StyleBox custom_button_hover

模式为 TreeItem.CELL_MODE_RANGE 的单元格处于悬停状态时的 StyleBox


StyleBox custom_button_pressed

模式为 TreeItem.CELL_MODE_RANGE 的单元格处于按下状态时的 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