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

属性

bool

allow_reselect

false

bool

allow_rmb_select

false

bool

allow_search

true

bool

auto_height

false

bool

auto_width

false

bool

clip_contents

true (overrides Control)

int

fixed_column_width

0

Vector2i

fixed_icon_size

Vector2i(0, 0)

FocusMode

focus_mode

2 (overrides Control)

IconMode

icon_mode

1

float

icon_scale

1.0

int

item_count

0

int

max_columns

1

int

max_text_lines

1

bool

same_column_width

false

SelectMode

select_mode

0

OverrunBehavior

text_overrun_behavior

3

bool

wraparound_items

true

方法

int

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

int

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

void

clear()

void

deselect(idx: int)

void

deselect_all()

void

ensure_current_is_visible()

void

force_update_list_size()

HScrollBar

get_h_scroll_bar()

int

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

AutoTranslateMode

get_item_auto_translate_mode(idx: int) const

Color

get_item_custom_bg_color(idx: int) const

Color

get_item_custom_fg_color(idx: int) const

Texture2D

get_item_icon(idx: int) const

Color

get_item_icon_modulate(idx: int) const

Rect2

get_item_icon_region(idx: int) const

String

get_item_language(idx: int) const

Variant

get_item_metadata(idx: int) const

Rect2

get_item_rect(idx: int, expand: bool = true) const

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

bool

is_anything_selected()

bool

is_item_disabled(idx: int) const

bool

is_item_icon_transposed(idx: int) const

bool

is_item_selectable(idx: int) const

bool

is_item_tooltip_enabled(idx: int) const

bool

is_selected(idx: int) const

void

move_item(from_idx: int, to_idx: int)

void

remove_item(idx: int)

void

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

void

set_item_auto_translate_mode(idx: int, mode: AutoTranslateMode)

void

set_item_custom_bg_color(idx: int, custom_bg_color: Color)

void

set_item_custom_fg_color(idx: int, custom_fg_color: Color)

void

set_item_disabled(idx: int, disabled: bool)

void

set_item_icon(idx: int, icon: Texture2D)

void

set_item_icon_modulate(idx: int, modulate: Color)

void

set_item_icon_region(idx: int, rect: Rect2)

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

font_hovered_color

Color(0.95, 0.95, 0.95, 1)

Color

font_hovered_selected_color

Color(1, 1, 1, 1)

Color

font_outline_color

Color(0, 0, 0, 1)

Color

font_selected_color

Color(1, 1, 1, 1)

Color

guide_color

Color(0.7, 0.7, 0.7, 0.25)

int

h_separation

4

int

icon_margin

4

int

line_separation

2

int

outline_size

0

int

v_separation

4

Font

font

int

font_size

StyleBox

cursor

StyleBox

cursor_unfocused

StyleBox

focus

StyleBox

hovered

StyleBox

hovered_selected

StyleBox

hovered_selected_focus

StyleBox

panel

StyleBox

selected

StyleBox

selected_focus

信号

empty_clicked(at_position: Vector2, mouse_button_index: int) 🔗

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

at_position 为点击的位置，使用控件的局部坐标系。

item_activated(index: int) 🔗

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

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

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

at_position 为点击的位置，使用控件的局部坐标系。

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 来选择多个项目。

SelectMode SELECT_TOGGLE = 2

允许选择多个项目，可以切换项目是否选中。

属性说明

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，点击鼠标右键可以选中项目。

  • 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，控件将自动调整高度以适合其内容。

bool auto_width = false 🔗

  • void set_auto_width(value: bool)

  • bool has_auto_width()

如果为 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) 🔗

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

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

IconMode icon_mode = 1 🔗

图标的位置，是在文本的上方还是在文本的左边。参阅 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 🔗

允许单选或多选。参阅SelectMode常量。

OverrunBehavior text_overrun_behavior = 3 🔗

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

bool wraparound_items = true 🔗

  • void set_wraparound_items(value: bool)

  • bool has_wraparound_items()

如果为 true，则控件会自动将项目移动至新的一行，适配内容。另见 HFlowContainer 的这一行为。

如果为 false，控件会添加水平滚动条，使所有项目都可见。

方法说明

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

在项目列表中添加一个项目，不带文本、只有图标。返回添加项目的索引。

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

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

使用 icon 指定图标，列表项不带图标时请为 icon 指定 null。

如果 selectable 为 true，则该列表项可被选中。

void clear() 🔗

移除列表中的所有项目。

void deselect(idx: int) 🔗

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

void deselect_all() 🔗

确保没有选择任何项目。

void ensure_current_is_visible() 🔗

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

void force_update_list_size() 🔗

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

HScrollBar get_h_scroll_bar() 🔗

返回水平滚动条。

警告：这是一个必需的内部节点，删除和释放它可能会导致崩溃。如果你希望隐藏它或其任何子项，请使用它们的 CanvasItem.visible 属性。

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 🔗

返回项目的自动翻译模式。

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_auto_translate_mode(idx: int, mode: AutoTranslateMode) 🔗

设置与给定索引关联的项目的自动翻译模式。

项目默认使用 Node.AUTO_TRANSLATE_MODE_INHERIT，表示使用与 ItemList 相同的自动翻译模式。

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_hovered_selected_color = Color(1, 1, 1, 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 hovered_selected 🔗

项目处于悬停且选中状态时的 StyleBox，在 ItemList 未获得焦点时使用。

StyleBox hovered_selected_focus 🔗

项目处于悬停且选中状态时的 StyleBox，在 ItemList 获得焦点时使用。

StyleBox panel 🔗

该 ItemList 的默认背景。

StyleBox selected 🔗

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

StyleBox selected_focus 🔗

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