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 ( 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
如果为 true，可以再次选择当前选定的单元。
bool allow_rmb_select = false
如果为 true，鼠标右键点击可以选择项目。
bool allow_search = true
如果为 true，允许在 Tree 中以增量搜索的形式使用字母键导航。
bool column_titles_visible = false
如果为 true，列标题可见。
int columns = 1
列数。
int drop_mode_flags = 0
放置模式是标志的按位或（OR）组合。见 DropModeFlags 常量。放置完成后会恢复为 DROP_MODE_DISABLED。建议在 Control._can_drop_data 期间设置。
控制的是放置区，即根据鼠标的位置决定并绘制可能的放置位置。
bool enable_recursive_folding = true
如果为 true，则该 Tree 启用了递归折叠。按住 Shift 键点击折叠箭头会折叠或展开该 TreeItem 及所有子项。
bool hide_folding = false
如果为 true，隐藏折叠箭头。
bool hide_root = false
如果为 true，则隐藏树的根节点。
bool scroll_horizontal_enabled = true
如果为 true，启用水平滚动。
bool scroll_vertical_enabled = true
如果为 true，则启用垂直滚动。
SelectMode select_mode = 0
void set_select_mode ( SelectMode value )
SelectMode get_select_mode ( )
允许单选或多选。见 SelectMode 常量。
方法说明¶
void clear ( )
清除树。这将删除所有项目。
TreeItem create_item ( TreeItem parent=null, int index=-1 )
在树中创建一个项，并将其添加为父项 parent 的子项，该父项可以是一个有效的 TreeItem 或 null。
如果 parent 为 null，则根项将是父项；或者如果该树为空，则该新项将是根本身。
新项将是父项的第 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()) # 该项刚刚被编辑（例如被勾选）。
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 ( 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。
如果 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 ( 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,