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