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) 🔗
Emitted when an item is expanded or collapsed by clicking on the folding arrow or through code.
Note: Despite its name, this signal is also emitted when an item is expanded.
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) 🔗
Emitted instead of item_selected if select_mode is set to SELECT_MULTI.
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 中以差異量搜索的形式使用字母鍵導覽。
If true, tree items with no tooltip assigned display their text as their tooltip. See also TreeItem.get_tooltip_text() and 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 🔗
If true, recursive folding is enabled for this Tree. Holding down Shift while clicking the fold arrow or using ui_right/ui_left shortcuts collapses or uncollapses the TreeItem and all its descendants.
如果為 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) 🔗
Text Color for a TreeItem.CELL_MODE_CHECK mode cell when it's non-editable (see 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) 🔗
Text Color used when the item is hovered, while a button of the same item is hovered as the same time.
Color font_hovered_selected_color = Color(1, 1, 1, 1) 🔗
Text Color used when the item is hovered and selected.
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 🔗
The inner bottom margin of a cell.
int inner_item_margin_left = 0 🔗
The inner left margin of a cell.
int inner_item_margin_right = 0 🔗
The inner right margin of a cell.
int inner_item_margin_top = 0 🔗
The inner top margin of a cell.
專案開頭的水平邊距。在專案啟用折疊功能時使用。
文字輪廓的大小。
注意：如果使用啟用了 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 字形。
專案文字的字形大小。
標題按鈕文字的 Font 字形。
箭頭圖示，可折疊項未折疊時使用。
箭頭圖示，可折疊項已折疊時使用（用於從左至右佈局）。
Texture2D arrow_collapsed_mirrored 🔗
箭頭圖示，可折疊項已折疊時使用（用於從右至左佈局）。
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is checked and editable (see TreeItem.set_editable()).
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is checked and non-editable (see TreeItem.set_editable()).
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is indeterminate and editable (see TreeItem.set_editable()).
Texture2D indeterminate_disabled 🔗
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is indeterminate and non-editable (see TreeItem.set_editable()).
箭頭圖示，模式為 TreeItem.CELL_MODE_RANGE 的儲存格顯示。
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is unchecked and editable (see TreeItem.set_editable()).
Texture2D unchecked_disabled 🔗
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is unchecked and non-editable (see TreeItem.set_editable()).
上下箭頭圖示，模式為 TreeItem.CELL_MODE_RANGE 的儲存格顯示。
StyleBox used when a button in the tree is hovered.
樹中的按鈕處於按下狀態時使用的 StyleBox。
用作游標的 StyleBox，該 Tree 處於聚焦狀態時使用。
用作游標的 StyleBox，該 Tree 處於失焦狀態時使用。
Default StyleBox for a TreeItem.CELL_MODE_CUSTOM mode cell when button is enabled with TreeItem.set_custom_as_button().
StyleBox custom_button_hover 🔗
StyleBox for a TreeItem.CELL_MODE_CUSTOM mode button cell when it's hovered.
StyleBox custom_button_pressed 🔗
StyleBox for a TreeItem.CELL_MODE_CUSTOM mode button cell when it's pressed.
該 Tree 的聚焦樣式，繪製在所有東西之上。
StyleBox for the item being hovered, but not selected.
StyleBox for the item being hovered, while a button of the same item is hovered as the same time.
StyleBox for the hovered and selected items, used when the Tree is not being focused.
StyleBox hovered_selected_focus 🔗
StyleBox for the hovered and selected items, used when the Tree is being focused.
該 Tree 的背景樣式。
所選專案的 StyleBox，在 Tree 沒有獲得焦點時使用。
所選專案的 StyleBox，在 Tree 獲得焦點時使用。
當標題按鈕被懸停時使用的 StyleBox。
StyleBox title_button_normal 🔗
標題按鈕的預設 StyleBox。
StyleBox title_button_pressed 🔗
當標題按鈕被按下時使用的 StyleBox。