UE5 ListViewの使い方｜Entry Widgetと動的バインド・仮想化

1ListView とは

ListView（リストビュー）は UE5 の UMG（Unreal Motion Graphics）で提供される仮想化対応のリストウィジェットです。インベントリ、スコアボード、クエスト一覧、ロビーのプレイヤー一覧など、同じ形式の項目を縦/横に並べて表示する用途で使います。

古くからある Vertical Box / Scroll Box 内に手動で要素を作る方式と違い、ListView は画面に見える範囲だけウィジェットを生成し、スクロールで再利用するため、数千〜数万件のデータでも軽快に動作します。

2ListView と類似ウィジェット

3使い方の全体像

1. 1 行ぶんの表示を担うEntry Widget Blueprint を作成（UUserWidget 派生）
2. Entry Widget にIUserObjectListEntry インタフェースを実装
3. 項目データを表すUObject 派生クラスを作成（プロパティを持つ）
4. 親の Widget にListView を配置し、Entry Widget Class に手順 1 のクラスを指定
5. Event Construct や任意のタイミングで、Set List Items / Add Item で項目を流し込む

4ステップ 1: 項目データクラス

表示する 1 件ぶんのデータを保持する UObject を作成。BlueprintReadWrite なプロパティを持たせます。

// ItemData.h
UCLASS(BlueprintType)
class MYGAME_API UItemData : public UObject
{
    GENERATED_BODY()
public:
    UPROPERTY(BlueprintReadWrite) FString Name;
    UPROPERTY(BlueprintReadWrite) int32   Quantity;
    UPROPERTY(BlueprintReadWrite) UTexture2D* Icon;
};

Blueprint Only でも構いません。Object 派生の Blueprint クラスを作って同じプロパティを持たせます。

5ステップ 2: Entry Widget Blueprint

1 行ぶんの見た目を作る Widget Blueprint。WBP_ItemEntry として作成し、TextBlock / Image などをデザイン。Class Settings → Implemented Interfaces に IUserObjectListEntry を追加します。

イベント実装（Blueprint）

インタフェースを追加すると On List Item Object Set イベントが呼び出せるようになります。引数の ListItemObject をデータクラスにキャストして UI に反映します。

Event On List Item Object Set
    │ (Object: UObject*)
    ▼
Cast To ItemData
    │
    ├ Name → Set Text (TextBlock_Name)
    ├ Quantity → Format Text "x{n}" → Set Text (TextBlock_Qty)
    └ Icon → Set Brush from Texture (Image_Icon)

C++ 版

// WBP_ItemEntry の親 C++
UCLASS()
class MYGAME_API UItemEntryWidget
    : public UUserWidget, public IUserObjectListEntry
{
    GENERATED_BODY()
protected:
    UPROPERTY(meta = (BindWidget)) UTextBlock* TextName;
    UPROPERTY(meta = (BindWidget)) UTextBlock* TextQty;
    UPROPERTY(meta = (BindWidget)) UImage*     ImageIcon;

    virtual void NativeOnListItemObjectSet(UObject* InObject) override
    {
        if (UItemData* Data = Cast<UItemData>(InObject))
        {
            TextName->SetText(FText::FromString(Data->Name));
            TextQty ->SetText(FText::FromString(
                FString::Printf(TEXT("x%d"), Data->Quantity)));
            if (Data->Icon) ImageIcon->SetBrushFromTexture(Data->Icon);
        }
    }
};

6ステップ 3: 親ウィジェットへ ListView を配置

親の Widget Blueprint（例: WBP_Inventory）を開き、パレットから ListView をキャンバスにドラッグ。Details パネルで:

• Entry Widget Class → WBP_ItemEntry
• Orientation → Vertical（縦並び）/ Horizontal（横並び）
• Selection Mode → None / Single / Multi など
• Item Alignment → Fill / Left / Center / Right

7ステップ 4: 項目を流し込む

Blueprint

Event Construct
    │
    ▼
For Each (ItemDataArray)
    │ Loop Body
    ▼
    Add Item (ListView, item)

C++

// 親 Widget で
TArray<UObject*> Items;
for (int32 i = 0; i < 50; ++i)
{
    UItemData* D = NewObject<UItemData>(this);
    D->Name = FString::Printf(TEXT("Item %d"), i);
    D->Quantity = FMath::RandRange(1, 99);
    Items.Add(D);
}
ListView->SetListItems(Items);   // 一括差し替え
// 個別追加なら ListView->AddItem(D);

8主な API

9主なイベント

10選択モード

11仮想化の仕組み

ListView は画面に見える行ぶん + 余裕分の Entry Widget のみを生成し、スクロールに応じて再利用します。例えば 10000 件の項目があっても、生成されるウィジェットは数十個。OnListItemObjectSet が再利用時に呼ばれる前提で実装しておくのが重要です（古いデータが残らないように、全プロパティを書き直す）。

12よくあるトラブル

13パフォーマンスの注意

• Entry Widget は軽量に保つ（複雑なレイアウトや高解像度画像は再生成コストが大きい）
• SetListItems と AddItem の使い分け: 全更新は SetListItems、追加だけなら AddItem
• 大量データを一気に追加する場合は1 度に SetListItems
• Texture のロードは非同期を検討

14FAQ

Q: 構造体（Struct）をリスト項目にしたい
A: ListView は UObject 派生のみ。Struct を持つ UObject ラッパークラスを作って包みます。

Q: 並べ替え（ソート）したい
A: 元の TArray を並べ替えてから SetListItems で再投入します。ListView 自体にソート機能はありません。

Q: 検索フィルタを実装したい
A: 別途検索用のテキストボックスを置き、入力に応じてフィルタした配列を SetListItems で再投入します。

15関連

• TileView — グリッド状のリスト
• TreeView — ツリー状のリスト
• UMG / Widget Blueprint — UI 構築
• UObject — UE のオブジェクト基底
• Scroll Box — 仮想化なしのスクロール