最后同步日期：2026-04-15 | Godot 官方原文 — ItemList

ItemList

节点继承关系

继承链：Node → CanvasItem → Control → ItemList

Control

类型	名称	说明
属性	Size	控件尺寸
属性	Position	控件位置
属性	AnchorsPreset	锚点预设
属性	GrowDirection	超出容器时的扩展方向
属性	MouseFilter	鼠标事件过滤（停止 / 通过 / 忽略）
属性	FocusMode	焦点模式（无 / 单击 / 全部）
信号	gui_input	接收到 GUI 输入事件
信号	mouse_entered	鼠标进入控件区域
信号	mouse_exited	鼠标离开控件区域
信号	focus_entered	获得焦点
信号	focus_exited	失去焦点
信号	resized	尺寸变化
方法	GrabFocus()	获取焦点
方法	ReleaseFocus()	释放焦点
方法	SetAnchorsPreset()	设置锚点预设
方法	GetMinimumSize()	获取最小尺寸

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

ItemList 显示一个可选中的项目列表，可以是文字也可以是图标。就像网购的购物车列表——每个商品一行，点一下就选中。

使用频率：★★★ 一般常用（背包、歌曲列表等常见）

节点用途

• 显示可选中的项目列表
• 背包物品列表
• 歌曲列表、存档列表

使用场景

• 背包界面中的物品列表
• 游戏的存档选择界面
• 好友列表

常用节点搭配

• 搭配 VBoxContainer 做布局
• 搭配 Label 显示列表标题

生效必备素材/资源

可选：图标图片用于列表项图标。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
item_count	int	0	—	列表项总数（只读）
max_columns	int	1	—	最大列数（1=单列列表，>1=网格模式）
select_mode	枚举	Single	—	选择模式：Single（单选）、Multi（多选）
allow_reselect	bool	false	—	是否允许重复选中同一项
icon_mode	枚举	Top	—	图标模式
fixed_column_width	int	0	—	固定列宽
fixed_icon_size	Vector2	(0, 0)	—	固定图标大小
same_column_width	bool	false	—	所有列是否等宽

信号

信号	触发时机	参数
item_selected	单击选中一个项目时	int 索引
multi_selected	多选模式下选中/取消选中时	int 索引, bool 是否选中
item_clicked	点击项目时	int 索引, int 鼠标按钮, int 按键掩码
item_activated	双击项目时	int 索引
nothing_selected	点击空白区域取消选中时	无

常用方法

方法	说明
AddItem("文字", icon)	添加一个列表项
AddIconItem(Texture2D)	添加一个纯图标项
Select(index)	选中指定项
IsSelected(index)	判断某项是否被选中
RemoveItem(index)	移除指定项
GetItemText(index)	获取指定项的文字
SetItemText(index, string)	设置指定项的文字
GetItemCount()	获取列表项总数
Clear()	清空列表

代码示例

C

using Godot;

public partial class InventoryList : ItemList
{
    public override void _Ready()
    {
        Size = new Vector2(200, 300);
        AllowReselect = true;

        AddItem("木剑");
        AddItem("铁盾");
        AddItem("生命药水");
        AddItem("魔法卷轴");

        ItemSelected += (index) =>
        {
            GD.Print($"选中了: {GetItemText(index)}");
        };
    }
}

GDScript

extends ItemList

func _ready():
    size = Vector2(200, 300)
    allow_reselect = true

    add_item("木剑")
    add_item("铁盾")
    add_item("生命药水")
    add_item("魔法卷轴")

    item_selected.connect(func(index: int):
        print("选中了: " + get_item_text(index))
    )