Godot入門：ItemListの使い方と活用法

対象読者：Godotの基本操作を少し触ったことがある初級者の方

はじめに
ItemListとは？
このノードを使うべき場面
主なプロパティと機能
もっと使いこなす：カスタマイズできるパラメータ
1. 1. 項目の追加と選択検知
2. 2. グリッド表示にする
よくある質問：似たノードとの違い
まとめ
関連性の高いノード解説記事

はじめに

インベントリの持ち物一覧やセーブデータの選択画面など、複数の選択肢から一つ（または複数）を選ばせるUIでよく使われるのが ItemList です。テキストとアイコンを並べて表示し、クリックで選択できます。

ItemListとは？

ItemListは、テキストやアイコン付きの項目を縦（またはグリッド状）に並べて表示し、クリックで選択させるためのUIノードです。項目の追加・削除・選択状態の管理を、すべて標準機能でまかなえます。

たとえるなら、ファイル選択ダイアログの一覧そのものです。並んだ項目の中から、クリックで一つを選ぶという操作を簡単に実現できます。

ItemList は Control → CanvasItem → Node を継承しています。スクロールバーも自動で表示されるため、項目数が多くても安心して使えます。

このノードを使うべき場面

インベントリで持ち物の一覧から一つを選ばせるとき
セーブデータ選択画面で、複数のセーブ枠から選ばせるとき
設定項目やクエスト一覧など、リスト形式で選ばせたいとき
項目数が多くなるほど便利になるノードです： スクロールや複数選択（select_mode）にも標準対応しているため、リストが長くなるほど自作するより手間が省けます

使わない・別のノードが適切な場合：

親子関係のある階層構造（フォルダのような入れ子構造）を表示したい → Tree を使う
選択肢を普段は畳んでおきたい（クリックで開くドロップダウン） → OptionButton を使う
選択機能は不要で、ただ整列させたいだけ → GridContainer を使う

使うかどうかの目安： 「一覧から選ばせる」操作が必要ならItemListがほぼ第一候補です。階層構造が必要になった時点でTreeへの切り替えを検討しましょう。

主なプロパティと機能

ItemListの代表的なプロパティとメソッドを以下にまとめました。

プロパティ/メソッド	役割	型
`add_item(text, icon)`	項目を追加（アイコンは省略可）	int（追加した項目のindex）
`get_item_count()`	現在の項目数を取得	int
`select(idx)`	指定したindexの項目を選択状態にする	void
`is_selected(idx)`	指定したindexが選択されているか	bool
`select_mode`	単一選択・複数選択の切り替え	int
`max_columns`	グリッド状に並べる際の列数（0で縦一列）	int
`item_selected`	項目がクリックされたときに発火するシグナル	Signal

もっと使いこなす：カスタマイズできるパラメータ

まずは基本を動かしてみてから、余裕が出たら試してみてください。

1. 項目の追加と選択検知

貼り付け先の準備： ①シーンツリーで＋ボタンから「ItemList」を検索して追加　②右クリックして「アタッチスクリプト」→GDScriptのまま「作成」を押し、開いたエディタに以下を貼り付け

extends ItemList

func _ready() -> void:
	add_item("ポーション")
	add_item("エーテル")
	add_item("エリクサー")
	item_selected.connect(_on_item_selected)

func _on_item_selected(index: int) -> void:
	print("選択されたアイテム: ", get_item_text(index))

2. グリッド表示にする

アイコン付きのアイテムを、縦一列ではなくグリッド状に並べたいときはmax_columnsを設定します。

max_columns = 4  # 4列のグリッド表示にする
icon_mode = ItemList.ICON_MODE_TOP  # アイコンをテキストの上に表示

よくある質問：似たノードとの違い

Q. ItemListとTreeの違いは？
A. ItemListはフラットな（階層のない）一覧を表示します。フォルダのような親子関係のある階層構造を表示したい場合はTreeを使います。

Q. ItemListとOptionButtonの違いは？
A. OptionButton は普段は畳まれていて、クリックすると選択肢が開くドロップダウン形式です。ItemListは常に全項目が一覧表示された状態になります。

Q. ItemListとGridContainerの違いは？
A. GridContainer は子ノードを格子状に自動整列させるだけで、選択機能はありません。クリックで選択する機能が必要ならItemListを使います。

まとめ

ItemList は、複数の選択肢から選ばせるUIを手軽に実現できるノードです。

インベントリやセーブデータ選択など、一覧から選ばせる場面で幅広く使えます
add_item、item_selectedなど、基本のプロパティ・シグナルから覚えましょう
max_columnsやicon_modeを使えば、グリッド表示のアイテム欄にも応用できます

次の記事では、値を直感的に調整できる Slider を解説します。