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(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 結合時，這些放置部分的高度減半，並相應地停留在頂部或底部。
enum ScrollHintMode: 🔗
ScrollHintMode SCROLL_HINT_MODE_DISABLED = 0
Scroll hints will never be shown.
ScrollHintMode SCROLL_HINT_MODE_BOTH = 1
Scroll hints will be shown at the top and bottom.
ScrollHintMode SCROLL_HINT_MODE_TOP = 2
Only the top scroll hint will be shown.
ScrollHintMode SCROLL_HINT_MODE_BOTTOM = 3
Only the bottom scroll hint will be shown.
屬性說明
如果為 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，列標題可見。
The number of columns.
Prints an error and does not allow setting the columns during mouse selection.
放置模式是旗標的按位元或（OR）組合。見 DropModeFlags 常數。放置完成後會恢復為 DROP_MODE_DISABLED。建議在 Control._can_drop_data() 期間設定。
控制的是放置區，即根據滑鼠的位置決定並繪製可能的放置位置。
bool enable_drag_unfolding = true 🔗
If true, tree items will unfold when hovered over during a drag-and-drop. The delay for when this happens is dictated by dragging_unfold_wait_msec.
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，則隱藏樹的根節點。
ScrollHintMode scroll_hint_mode = 0 🔗
void set_scroll_hint_mode(value: ScrollHintMode)
ScrollHintMode get_scroll_hint_mode()
The way which scroll hints (indicators that show that the content can still be scrolled in a certain direction) will be shown.
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 常數。
bool tile_scroll_hint = false 🔗
If true, the scroll hint texture will be tiled instead of stretched. See scroll_hint_mode.
方法說明
void clear() 🔗
Clears the tree. This removes all items.
Prints an error and does not allow clearing the tree if called during mouse selection.
TreeItem create_item(parent: TreeItem = null, index: int = -1) 🔗
Creates an item in the tree and adds it as a child of parent, which can be either a valid TreeItem or null.
If parent is null, the root item will be the parent, or the new item will be the root itself if the tree is empty.
The new item will be the index-th child of parent, or it will be the last child if there are not enough siblings.
Prints an error and returns null if called during mouse selection, or if the parent does not belong to this tree.
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 🔗
返回列標題的語言程式碼。
String get_column_title_tooltip_text(column: int) const 🔗
Returns the column title's tooltip text.
int get_column_width(column: int) const 🔗
返回列的寬度，單位是圖元。
RID get_custom_drawing_canvas_item() const 🔗
Returns the internal canvas item designated for custom drawing. See TreeItem.set_custom_draw_callback().
Note: This canvas item clears automatically on each Tree draw call.
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) 🔗
Sets the language code of the given column's title to language. This is used for line-breaking and text shaping algorithms. If language is empty, the current locale is used.
void set_column_title_tooltip_text(column: int, tooltip_text: String) 🔗
Sets the column title's tooltip text.
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_on_item_color = Color(1, 1, 1, 1) 🔗
Color used to draw the highlight outline when dragging items that can only be dropped "on" other items.
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 scroll_hint_color = Color(0, 0, 0, 1) 🔗
Color used to modulate the scroll_hint texture.
Color title_button_color = Color(0.875, 0.875, 0.875, 1) 🔗
標題按鈕的預設文字 Color 顏色。
儲存格中按鈕之間的水平間距。
The horizontal space between the checkbox and the text in a TreeItem.CELL_MODE_CHECK mode cell.
int children_hl_line_width = 1 🔗
被選中的 TreeItem 與其子項之間的關係線的寬度。
int dragging_unfold_wait_msec = 500 🔗
During a drag-and-drop, this is how many milliseconds to wait over a section before the section unfolds.
如果不為零就繪製輔助線，行為類似於布林值。輔助線是在每個項的底部畫的一條水平線。
int draw_relationship_lines = 0 🔗
如果不為零就繪製關係線，行為類似於布林值。關係線在子項的開始處繪製，以顯示層次結構。
專案單元之間的水平空間。這也用作禁用折疊時專案開頭的邊距。
The horizontal space between the icon and the text in item's cells.
專案儲存格所允許的最大圖示寬度。這是在圖示預設大小的基礎上的限制，在 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()).
The indicator that will be shown when the content can still be scrolled. See scroll_hint_mode.
箭頭圖示，模式為 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。