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...
ItemList
繼承： Control < CanvasItem < Node < Object
可選專案的垂直列表，可以有一列或多列。
說明
該控制項提供了可選專案的垂直列表，這些專案可能位於單列或多列中，每個專案都有文本和圖示選項。支援工具提示，並且列表中的每個專案可能會有所不同。
可以選擇或取消選擇列表中的可選專案，並且可以啟用多項選擇。也可以啟用用滑鼠右鍵進行選擇，以允許使用彈出本文功能表。專案也可以通過按兩下它們，或按 Enter 來“啟動”。
專案文字只支援單行字串。字串中的分行符號（例如 \n）不會產生換行。在 ICON_MODE_TOP 模式下會啟用文字換行，但預設情況下會調整列的寬度以完全適合其內容。需要將 fixed_column_width 設定得大於零，才能換行文字。
所有 set_* 方法都允許負的專案索引，例如 -1 存取的是最後一個專案，-2 選擇的是倒數第二個專案，以此類推。
差異量搜索：與 PopupMenu 和 Tree 一樣，ItemList 支援在控制項獲得焦點時在列表內進行搜索。按下與專案名稱的第一個字母配對的鍵，以選擇以給定字母開頭的第一個專案。在該點之後，有兩種方法可以執行差異量搜索： 1) 在超時持續時間之前再次按下相同的鍵，以選擇下一個以相同字母開頭的專案。 2) 在超時時間前，按配對單詞剩餘部分的字母鍵，將直接選擇問題項。如果自上次擊鍵被註冊後，超時持續時間已過，則這兩個動作都將被重設為列表的開頭。可以通過更改 ProjectSettings.gui/timers/incremental_search_max_interval_msec 來調整超時持續時間。
屬性
|
||
|
||
|
||
|
||
|
||
clip_contents |
|
|
|
||
|
||
focus_mode |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
主題屬性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
訊號
empty_clicked(at_position: Vector2, mouse_button_index: int) 🔗
Emitted when any mouse click is issued within the rect of the list but on empty space.
at_position is the click position in this control's local coordinate system.
Emitted when specified list item is activated via double-clicking or by pressing Enter.
item_clicked(index: int, at_position: Vector2, mouse_button_index: int) 🔗
Emitted when specified list item has been clicked with any mouse button.
at_position is the click position in this control's local coordinate system.
Emitted when specified item has been selected. Only applicable in single selection mode.
allow_reselect must be enabled to reselect an item.
multi_selected(index: int, selected: bool) 🔗
Emitted when a multiple selection is altered on a list allowing multiple selection.
列舉
enum IconMode: 🔗
IconMode ICON_MODE_TOP = 0
圖示繪製在文字上方。
IconMode ICON_MODE_LEFT = 1
圖示繪製在文字的左側。
enum SelectMode: 🔗
SelectMode SELECT_SINGLE = 0
僅允許選擇單個專案。
SelectMode SELECT_MULTI = 1
允許通過按住 Ctrl 或 Shift 來選擇多個專案。
SelectMode SELECT_TOGGLE = 2
Allows selecting multiple items by toggling them on and off.
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，則允許用字母鍵通過差異量搜索導覽 ItemList。
如果為 true，控制項將自動調整高度以適合其內容。
If true, the control will automatically resize the width to fit its content.
所有列的寬度將調整為。
零值禁用調整，每個專案的寬度將等於其內容的寬度，列的寬度將不均勻。
Vector2i fixed_icon_size = Vector2i(0, 0) 🔗
所有圖示將被調整到的尺寸。
如果 X 或 Y 分量不大於 0，圖示的大小將不會受到影響。
圖示的位置，是在文字的上方還是在文字的左邊。參閱 IconMode 常數。
在 fixed_icon_size 和轉置生效後套用的圖示比例。
目前列表中的專案數。
bool item_{index}/disabled = false 🔗
If true, the item at index is disabled.
Note: index is a value in the 0 .. item_count - 1 range.
The icon of the item at index.
Note: index is a value in the 0 .. item_count - 1 range.
bool item_{index}/selectable = true 🔗
If true, the item at index is selectable.
Note: index is a value in the 0 .. item_count - 1 range.
String item_{index}/text = "" 🔗
The text of the item at index.
Note: index is a value in the 0 .. item_count - 1 range.
列表將具有的最大列。
如果大於零，內容將被拆分為指定列。
零值意味著無限列，即所有專案將放在同一行中。
每個子項中允許的最大文字行數。即使沒有足夠的文字行數來顯示，也會保留空間。
注意：這個屬性只有在 icon_mode 是 ICON_MODE_TOP 時才會生效。要使文字自動換行，fixed_column_width應大於零。
bool same_column_width = false 🔗
是否所有列的寬度相同。
如果為 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.
SelectMode select_mode = 0 🔗
void set_select_mode(value: SelectMode)
SelectMode get_select_mode()
允許單選或多選。參閱SelectMode常數。
OverrunBehavior text_overrun_behavior = 3 🔗
void set_text_overrun_behavior(value: OverrunBehavior)
OverrunBehavior get_text_overrun_behavior()
The clipping behavior when the text exceeds an item's bounding rectangle.
bool tile_scroll_hint = false 🔗
If true, the scroll hint texture will be tiled instead of stretched. See scroll_hint_mode.
bool wraparound_items = true 🔗
If true, the control will automatically move items into a new row to fit its content. See also HFlowContainer for this behavior.
If false, the control will add a horizontal scrollbar to make all items visible.
方法說明
int add_icon_item(icon: Texture2D, selectable: bool = true) 🔗
將一個專案新增到專案列表中，沒有文字，只有一個圖示。返回新增的項的索引。
int add_item(text: String, icon: Texture2D = null, selectable: bool = true) 🔗
Adds an item to the item list with specified text. Returns the index of an added item.
Specify an icon, or use null as the icon for a list item with no icon.
If selectable is true, the list item will be selectable.
void center_on_current(center_verically: bool = true, center_horizontally: bool = true) 🔗
Ensures the currently selected item (the first selected item if multiple selection is enabled) is visible, adjusting the scroll position as necessary to place the item at the center of the list if possible. See also ensure_current_is_visible().
Fails and prints an error if both arguments are false.
void clear() 🔗
移除列表中的所有專案。
確保與指定索引相關的專案不被選中。
void deselect_all() 🔗
確保沒有選擇任何專案。
void ensure_current_is_visible() 🔗
Ensures the currently selected item (the first selected item if multiple selection is enabled) is visible, adjusting the scroll position as necessary. See also center_on_current().
void force_update_list_size() 🔗
根據其專案強制更新列表大小。只要專案的大小或其他相關設定（例如 auto_height）發生更改，這種情況就會自動發生。該方法可用於在下方一次繪圖前觸發更新。
HScrollBar get_h_scroll_bar() 🔗
Returns the horizontal scrollbar.
Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their CanvasItem.visible property.
int get_item_at_position(position: Vector2, exact: bool = false) const 🔗
返回位於給定位置 position 的專案的索引。
這個位置沒有專案時，如果 exact 為 true 則會返回 -1，否則會返回距離最近的專案的索引。
注意：如果修改 ItemList 後立即呼叫，尚未在下一影格中重繪，則返回值不可靠。
AutoTranslateMode get_item_auto_translate_mode(idx: int) const 🔗
Returns item's auto translate mode.
Color get_item_custom_bg_color(idx: int) const 🔗
返回專案的自訂背景色，專案由索引 idx 指定。
Color get_item_custom_fg_color(idx: int) const 🔗
返回專案的自訂前景色，專案由索引 idx 指定。
Texture2D get_item_icon(idx: int) const 🔗
返回與指定索引相關的圖示。
Color get_item_icon_modulate(idx: int) const 🔗
返回指定索引處的 Color 顏色調變項的圖示。
Rect2 get_item_icon_region(idx: int) const 🔗
返回專案圖示的使用區域。如果該區域大小為 0，整個圖示將被使用。
String get_item_language(idx: int) const 🔗
返回專案文字的語言程式碼。
Variant get_item_metadata(idx: int) const 🔗
返回指定索引的中繼資料值。
Rect2 get_item_rect(idx: int, expand: bool = true) const 🔗
返回具有給定索引的專案的位置和大小，使用 ItemList 節點的坐標系。如果 expand 為 true，則會將最後一列進行擴充，充滿該行剩餘的大小。
注意：如果修改 ItemList 後立即呼叫，尚未在下一影格中重繪，則返回值不可靠。
String get_item_text(idx: int) const 🔗
返回與指定索引關聯的文字。
TextDirection get_item_text_direction(idx: int) const 🔗
返回專案文字的基礎書寫方向。
String get_item_tooltip(idx: int) const 🔗
返回與指定索引關聯的工具提示。
PackedInt32Array get_selected_items() 🔗
返回一個包含所選專案索引的陣列。
VScrollBar get_v_scroll_bar() 🔗
返回垂直捲動條。
警告：這是一個必需的內部節點，刪除和釋放它可能會導致當機。如果你希望隱藏它或其任何子項，請使用它們的 CanvasItem.visible 屬性。
選中了一個或多個專案時，返回 true。
bool is_item_disabled(idx: int) const 🔗
索引所對應的專案被禁用時，返回 true。
bool is_item_icon_transposed(idx: int) const 🔗
專案圖示被轉置繪製，即 X 和 Y 軸互換時，返回 true。
bool is_item_selectable(idx: int) const 🔗
索引所對應的專案可以被選中時，返回 true。
bool is_item_tooltip_enabled(idx: int) const 🔗
索引所對應的專案已啟用工具提示時，返回 true。
bool is_selected(idx: int) const 🔗
索引所對應的專案被選中時，返回 true。
void move_item(from_idx: int, to_idx: int) 🔗
將專案從索引 from_idx 移到 to_idx。
從列表中刪除索引 idx 指定的專案。
void select(idx: int, single: bool = true) 🔗
Selects the item at the specified index.
Note: This method does not trigger the item selection signal.
void set_item_auto_translate_mode(idx: int, mode: AutoTranslateMode) 🔗
Sets the auto translate mode of the item associated with the specified index.
Items use Node.AUTO_TRANSLATE_MODE_INHERIT by default, which uses the same auto translate mode as the ItemList itself.
void set_item_custom_bg_color(idx: int, custom_bg_color: Color) 🔗
將索引 idx 指定的專案的背景色設定為指定的 Color。
void set_item_custom_fg_color(idx: int, custom_fg_color: Color) 🔗
將索引 idx 指定的專案的前景色設定為指定的 Color。
void set_item_disabled(idx: int, disabled: bool) 🔗
禁用（或啟用）指定索引處的專案。
禁用的專案不能被選中，也不會觸發（按兩下或按 Enter 時的）啟動訊號。
void set_item_icon(idx: int, icon: Texture2D) 🔗
設定（或替換）與指定索引關聯的圖示 Texture2D。
void set_item_icon_modulate(idx: int, modulate: Color) 🔗
設定與指定索引相關的專案的調變顏色 Color。
void set_item_icon_region(idx: int, rect: Rect2) 🔗
設定專案圖示的使用區域。如果該區域大小為 0，將使用整個圖示。
void set_item_icon_transposed(idx: int, transposed: bool) 🔗
設定專案圖示是否將被轉置繪製。
void set_item_language(idx: int, language: String) 🔗
Sets the language code of the text for the item at the given index to language. This is used for line-breaking and text shaping algorithms. If language is empty, the current locale is used.
void set_item_metadata(idx: int, metadata: Variant) 🔗
設定與指定索引相關的專案儲存的值（任何型別的值）。
void set_item_selectable(idx: int, selectable: bool) 🔗
允許或禁止選擇與指定索引關聯的專案。
void set_item_text(idx: int, text: String) 🔗
設定與指定索引相關的專案的文字。
void set_item_text_direction(idx: int, direction: TextDirection) 🔗
設定專案文字的基礎書寫方向。
void set_item_tooltip(idx: int, tooltip: String) 🔗
設定與指定索引相關的專案的工具提示。
void set_item_tooltip_enabled(idx: int, enable: bool) 🔗
設定是否為指定的專案索引啟用工具提示。
void sort_items_by_text() 🔗
按文字對列表中的專案進行排序。
主題屬性說明
Color font_color = Color(0.65, 0.65, 0.65, 1) 🔗
專案的預設文字顏色 Color。
Color font_hovered_color = Color(0.95, 0.95, 0.95, 1) 🔗
專案處於懸停但未選中狀態時使用的文字 Color。
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) 🔗
Text Color used when the item is selected, but not hovered.
Color guide_color = Color(0.7, 0.7, 0.7, 0.25) 🔗
輔助線的顏色 Color。輔助線是在每行專案之間畫的一條線。
Color scroll_hint_color = Color(0, 0, 0, 1) 🔗
Color used to modulate the scroll_hint texture.
專案之間的水平間距。
專案的圖示和文字之間的間距。
每行文字之間的行距。
專案文字輪廓的大小。
注意：如果使用啟用了 FontFile.multichannel_signed_distance_field 的字形，其 FontFile.msdf_pixel_range 必須至少設定為 outline_size 的兩倍，輪廓算繪才能看起來正確。否則，輪廓可能會比預期的更早被切斷。
專案選單之間的垂直間距。
專案文字的字形 Font 。
專案文字的字形大小。
The indicator that will be shown when the content can still be scrolled. See scroll_hint_mode.
當該 ItemList 獲得焦點時，用作游標的樣式盒 StyleBox。
當該 ItemList 未獲得焦點時，用作游標的樣式盒 StyleBox。
The focused style for the ItemList, drawn on top of everything.
懸停但未被選中的專案的 StyleBox。
StyleBox for the hovered and selected items, used when the ItemList is not being focused.
StyleBox hovered_selected_focus 🔗
StyleBox for the hovered and selected items, used when the ItemList is being focused.
該 ItemList 的預設背景。
所選項的樣式盒 StyleBox，當該 ItemList 未獲得焦點時使用。
所選項的樣式盒 StyleBox，當該 ItemList 獲得焦點時使用。