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 来调整超时持续时间。

属性

方法

主题属性

信号

empty_clicked(at_position: Vector2, mouse_button_index: int) 🔗

在列表矩形内的非空白区域点击鼠标时触发。

item_activated(index: int) 🔗

通过双击或按回车键激活指定的列表项时触发。

item_clicked(index: int, at_position: Vector2, mouse_button_index: int) 🔗

鼠标按键单击指定的列表项时触发。

还提供了单击的位置，这样就能够在正确位置弹出相应的上下文菜单。

item_selected(index: int) 🔗

选择指定项目时触发。

allow_reselect 必须启用才能重新选择项目。

multi_selected(index: int, selected: bool) 🔗

在允许多选的列表上更改多选时触发。

枚举

enum IconMode: 🔗

IconMode ICON_MODE_TOP = 0

图标绘制在文本上方。

IconMode ICON_MODE_LEFT = 1

图标绘制在文本的左侧。

enum SelectMode: 🔗

SelectMode SELECT_SINGLE = 0

仅允许选择单个项目。

SelectMode SELECT_MULTI = 1

允许通过按住 Ctrl 或 Shift 来选择多个项目。

属性说明

bool allow_reselect = false 🔗

• void set_allow_reselect(value: bool)

• bool get_allow_reselect()

如果为 true，则可以再次选择当前选中的项目。

bool allow_rmb_select = false 🔗

• void set_allow_rmb_select(value: bool)

• bool get_allow_rmb_select()

如果为 true，点击鼠标右键可以选中项目。

bool allow_search = true 🔗

• void set_allow_search(value: bool)

• bool get_allow_search()

如果为 true，则允许用字母键通过增量搜索导航 ItemList。

bool auto_height = false 🔗

• void set_auto_height(value: bool)

• bool has_auto_height()

如果为 true，控件将自动调整高度以适合其内容。

int fixed_column_width = 0 🔗

• void set_fixed_column_width(value: int)

• int get_fixed_column_width()

所有列的宽度将调整为。

零值禁用调整，每个项目的宽度将等于其内容的宽度，列的宽度将不均匀。

Vector2i fixed_icon_size = Vector2i(0, 0) 🔗

• void set_fixed_icon_size(value: Vector2i)

• Vector2i get_fixed_icon_size()

所有图标将被调整到的尺寸。

如果 X 或 Y 分量不大于 0，图标的大小将不会受到影响。

IconMode icon_mode = 1 🔗

• void set_icon_mode(value: IconMode)

• IconMode get_icon_mode()

图标的位置，是在文本的上方还是在文本的左边。参阅 IconMode 常量。

float icon_scale = 1.0 🔗

• void set_icon_scale(value: float)

• float get_icon_scale()

在 fixed_icon_size 和转置生效后应用的图标比例。

int item_count = 0 🔗

• void set_item_count(value: int)

• int get_item_count()

当前列表中的项目数。

int max_columns = 1 🔗

• void set_max_columns(value: int)

• int get_max_columns()

列表将具有的最大列。

如果大于零，内容将被拆分为指定列。

零值意味着无限列，即所有项目将放在同一行中。

int max_text_lines = 1 🔗

• void set_max_text_lines(value: int)

• int get_max_text_lines()

每个子项中允许的最大文本行数。即使没有足够的文本行数来显示，也会保留空间。

注意：这个属性只有在 icon_mode 是 ICON_MODE_TOP 时才会生效。要使文本自动换行，fixed_column_width应大于零。

bool same_column_width = false 🔗

• void set_same_column_width(value: bool)

• bool is_same_column_width()

是否所有列的宽度相同。

如果为 true，则宽度等于所有列的最大列宽度。

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

设置文本超出项目的边界矩形时的裁剪行为。所有模式的说明见 OverrunBehavior。

方法说明

int add_icon_item(icon: Texture2D, selectable: bool = true) 🔗

将一个项目添加到项目列表中，没有文本，只有一个图标。返回添加的项的索引。

int add_item(text: String, icon: Texture2D = null, selectable: bool = true) 🔗

将一个项目添加到项目列表中，并指定文本。返回添加的项目的索引。

指定一个 icon，或列表项没有图标时使用 null 作为 icon。

如果 selectable 为 true，则列表项将是可选择的。

void clear() 🔗

移除列表中的所有项目。

void deselect(idx: int) 🔗

确保与指定索引相关的项目不被选中。

void deselect_all() 🔗

确保没有选择任何项目。

void ensure_current_is_visible() 🔗

确保当前选择可见，根据需要调整滚动位置。

void force_update_list_size() 🔗

根据列表项强制更新该列表大小。每当项目的大小或其他相关设置（例如 auto_height）发生变化时，这种情况就会自动发生。该方法可被用于在下一次绘制阶段之前触发更新。

int get_item_at_position(position: Vector2, exact: bool = false) const 🔗

返回位于给定位置 position 的项目的索引。

这个位置没有项目时，如果 exact 为 true 则会返回 -1，否则会返回距离最近的项目的索引。

注意：如果修改 ItemList 后立即调用，尚未在下一帧中重绘，则返回值不可靠。

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 属性。

bool is_anything_selected() 🔗

选中了一个或多个项目时，返回 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。

void remove_item(idx: int) 🔗

从列表中删除索引 idx 指定的项目。

void select(idx: int, single: bool = true) 🔗

选择指定索引处的项目。

注意：此方法不触发项目选择信号。

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

设置项目文本的语言代码，用于断行和文本塑形算法，如果留空则使用当前区域设置。

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_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。参考线是在每行项目之间画的一条线。

int h_separation = 4 🔗

项目之间的水平间距。

int icon_margin = 4 🔗

项目的图标和文本之间的间距。

int line_separation = 2 🔗

每行文字之间的行距。

int outline_size = 0 🔗

项目文本轮廓的大小。

注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。

int v_separation = 4 🔗

项目菜单之间的垂直间距。

Font font 🔗

项目文本的字体 Font 。

int font_size 🔗

项目文本的字体大小。

StyleBox cursor 🔗

当该 ItemList 获得焦点时，用作光标的样式盒 StyleBox。

StyleBox cursor_unfocused 🔗

当该 ItemList 未获得焦点时，用作光标的样式盒 StyleBox。

StyleBox focus 🔗

该 ItemList 的焦点样式，绘制在背景之上，但低于其他东西。

StyleBox hovered 🔗

悬停但未被选中的项目的 StyleBox。

StyleBox panel 🔗

该 ItemList 的默认背景。

StyleBox selected 🔗

所选项的样式盒 StyleBox，当该 ItemList 未获得焦点时使用。

StyleBox selected_focus 🔗

所选项的样式盒 StyleBox，当该 ItemList 获得焦点时使用。