タイトル: EntryWidgetClass
SEOタイトル: UE5のEntry Widget Classとは｜List View・Dynamic Entry Boxでの使い方
Unreal Engine 5（UE5）のEntry Widget Class（エントリーウィジェットクラス）とは、List ViewやDynamic Entry Boxといった「複数の項目を並べて表示するウィジェット」で、1つ1つの項目（エントリー）の見た目を定義するユーザーウィジェットのクラスを指定するためのプロパティです。リスト全体の枠組みは親ウィジェットが担当し、各項目の中身（アイコン・名前・ボタンなどのレイアウト）は、ここで指定したウィジェットが1件ぶんのテンプレートとして繰り返し使われます。
| この記事の要点 |
|---|
|
Entry Widget Classとは何か
Entry Widget Classは、リスト形式のUIを構成するときに、「リストの容れ物」と「リスト1件ぶんの見た目」を分離するための仕組みです。たとえばインベントリ画面なら、List Viewなどが縦に項目を並べるスクロール領域を提供し、Entry Widget Classとして指定したユーザーウィジェット（アイコン＋アイテム名＋個数のレイアウトなど）が、項目の数だけ複製されて並びます。
この分離により、各項目のレイアウトは1つのウィジェットブループリントとして一元管理できます。デザインを変更したいときはエントリー用ウィジェットだけを編集すれば、リスト全体に反映されます。コードや見た目の再利用性が高まり、保守がしやすくなる点が利点です。
なお、UE5にはエントリーを扱うウィジェットが複数あり、プロパティ名やインターフェースの要否がそれぞれ異なります。代表的なものを次の表にまとめます（仕様はバージョンや実装方法により差があるため、最終的には使用中のエンジンバージョンの公式ドキュメントで確認することを推奨します）。
| ウィジェット | 主な用途 | エントリーに求められる実装 | 仮想化（省メモリ） |
|---|---|---|---|
| List View | 縦方向の項目一覧 | IUserObjectListEntry など | あり（多数の項目向き） |
| Tile View | グリッド状の項目配置 | IUserObjectListEntry など | あり |
| Tree View | 階層構造の表示 | IUserObjectListEntry / IUserTreeViewEntry など | あり |
| Dynamic Entry Box | 件数が変動する少数の項目 | 必須ではない | なし（全件を生成） |
使う場面
List View / Tile View / Tree View
多数のデータを並べて表示し、スクロールさせたい場面ではList View系が適しています。これらのウィジェットは画面に表示される範囲の項目だけを生成・再利用する「仮想化」に対応しているため、項目数が多くてもメモリやパフォーマンスへの負荷を抑えやすいのが特徴です。インベントリ、ランキング、チャットログ、ファイル一覧などが典型的な用途です。
Dynamic Entry Box
一方のDynamic Entry Boxは、件数が変動するものの数があまり多くないUIに向いた容れ物です。デザイン時・実行時の両方でエントリーを自動生成できるため、設定の確認がしやすい反面、項目を仮想化しないため、全件ぶんのウィジェットがまとめて生成されます。公式ドキュメントでも、多数の項目をスクロールさせる用途では避けるよう案内されています。少数のボタンやタブ、アイコンの並びなどに向いています。
設定方法
ここではList Viewを例に、エントリー用ウィジェットの作成からクラス指定までの流れを説明します。
① エントリー用ウィジェットを作成する
まず、リスト1件ぶんの見た目を担当するユーザーウィジェットを作成します。
- コンテンツブラウザで「ユーザーインターフェース」→「ウィジェットブループリント（User Widget）」を作成します。
- 分かりやすい名前（例：WBP_ItemEntry）を付けます。
- デザイナーで、1件ぶんのレイアウト（アイコン用のImage、名前用のText Blockなど）を配置します。
② リストを配置し、Entry Widget Classを指定する
次に、リスト本体を持つウィジェットを用意し、エントリークラスを割り当てます。
- 別のウィジェットブループリント（例：WBP_InventoryScreen）を作成します。
- デザイナーのパレットからList Viewを配置します。
- List Viewを選択し、詳細（Details）パネルの「Entry Widget Class」に、①で作成したエントリー用ウィジェットを指定します。
この指定により、List Viewはデザイナー上でもエントリーのプレビューを表示できるようになります。Tile View・Tree View・Dynamic Entry Boxでも、同様に詳細パネルからエントリーとして使うウィジェットクラスを指定します。
List ViewはIUserObjectListEntryの実装が要る
List View系（List View / Tile View / Tree View）でエントリーとして使うウィジェットには、IUserObjectListEntry（C++上の名称。ブループリント上は「User Object List Entry」インターフェース）を実装することが基本となります。これは、各エントリーが「自分はどのデータ項目を表しているか」を受け取り、表示を更新できるようにするためのインターフェースです。
このインターフェースを実装していないウィジェットでも配置自体は可能な場合がありますが、後述のデータ連携イベントが呼ばれず、項目ごとの内容を反映できません。そのため、List View系を使う際はエントリー側に該当インターフェースを実装しておくのが定石です。
// C++でエントリーウィジェットを定義する例（要点のみ） UCLASS() class UItemEntryWidget : public UUserWidget, public IUserObjectListEntry { GENERATED_BODY() protected: // 項目データが割り当てられたときに呼ばれる virtual void NativeOnListItemObjectSet(UObject* ListItemObject) override; }; |
データ連携（On List Item Object Set）
List View系では、リストに渡したデータ（UObject）が各エントリーに割り当てられるたびに、エントリー側でOn List Item Object Setイベント（ブループリント）／NativeOnListItemObjectSet（C++）が呼ばれます。エントリーウィジェットは、このイベントで受け取ったデータオブジェクトを読み取り、自分のText BlockやImageへ値を反映させます。
大まかな流れは次のとおりです。
- リストに表示したい1件ぶんのデータを、UObject（たとえばUObjectを継承したデータ用クラスのインスタンス）として用意します。
- それらのオブジェクトの配列を、List Viewにアイテムとして渡します（C++ではSetListItems、ブループリントではAdd Item／Set List Itemsに相当するノードなど）。
- List Viewが各エントリーを生成・再利用するタイミングで、対応するデータオブジェクトがエントリーへ渡され、On List Item Object Setが呼ばれます。
- エントリー側のイベント処理で、受け取ったオブジェクトを目的のデータ型へキャストし、表示要素に反映します。
仮想化により、画面外へスクロールしたエントリーウィジェットは別のデータの表示に使い回されます。そのため「最初の表示時に一度だけ値を入れる」のではなく、On List Item Object Setが呼ばれるたびに表示を更新する作りにしておくことが重要です。
// On List Item Object Set 相当の実装イメージ void UItemEntryWidget::NativeOnListItemObjectSet(UObject* ListItemObject) { if (UMyItemData* Data = Cast<UMyItemData>(ListItemObject)) { // ここでText BlockやImageに値を反映する } } |
Dynamic Entry Boxの場合は、上記のインターフェースやイベントは必須ではありません。エントリーを生成する側のロジックで、生成したウィジェットへ値を直接設定する形が一般的です。
つまずきやすいポイント
| 症状 | よくある原因と確認点 |
|---|---|
| エントリーが1件も表示されない | 詳細パネルのEntry Widget Classが未指定。まず正しいウィジェットクラスが割り当てられているかを確認します。 |
| 表示はされるが内容が更新されない | エントリーにList View用インターフェース（IUserObjectListEntry等）が実装されておらず、データ受け取りイベントが呼ばれていない可能性があります。 |
| データの値が反映されない／空のまま | On List Item Object Setでのキャストや代入処理が書かれていない、または目的のデータ型へのキャストに失敗していないかを確認します。 |
| スクロール時に別項目の内容が混ざる | 仮想化でウィジェットが再利用されるため、毎回データ受け取りイベントで全表示要素を上書きする作りになっているか見直します。 |
| 項目が増えると重い・カクつく | 多数の項目をDynamic Entry Boxで扱っていないか確認します。大量データは仮想化対応のList View系の利用を検討します。 |
よくある質問（FAQ）
Q1. List ViewとDynamic Entry Boxは、どちらを使えばよいですか？
項目数が多くスクロールさせたい場合は、仮想化に対応したList View（またはTile View・Tree View）が適しています。一方、件数が少なく、全件を一度に並べたい少数のUI（タブやボタン群など）であればDynamic Entry Boxが扱いやすいです。大量データをDynamic Entry Boxで扱うと、全件ぶんのウィジェットが生成され負荷が高くなりやすい点に注意してください。
Q2. Entry Widget Classに指定するウィジェットは、必ずインターフェースを実装する必要がありますか？
List View系のエントリーとしてデータ連携を行う場合は、IUserObjectListEntryなどのリストエントリー用インターフェースの実装が基本です。Dynamic Entry Boxでは必須ではありません。使用するウィジェットによって要件が異なるため、対象ウィジェットの仕様を確認してください。
Q3. データが反映されないとき、どこを確認すればよいですか？
まず詳細パネルでEntry Widget Classが指定されているか、次にエントリー側でインターフェースが実装されOn List Item Object Setが呼ばれているか、最後にそのイベント内で受け取ったオブジェクトを正しい型へキャストして表示要素へ代入しているか、の順で確認すると原因を切り分けやすくなります。
まとめ
UE5のEntry Widget Classは、リスト系ウィジェットにおいて「各エントリーの見た目」を担当するユーザーウィジェットのクラスを指定するためのプロパティです。List View系では仮想化とIUserObjectListEntryインターフェース、On List Item Object Setによるデータ連携が組み合わさり、Dynamic Entry Boxではより手軽に少数のエントリーを扱えます。用途に合ったウィジェットを選び、エントリークラスの指定・インターフェースの実装・データ反映処理を押さえることで、安定した動的リストUIを実現できます。詳細な仕様は、利用中のエンジンバージョンの公式ドキュメントもあわせて確認することをおすすめします。