unity-ui-development

Unity UI 開発

概要

Unity には 2 つの UI システムがあります。UGUI（従来の GameObject ベースのシステム）と、ウェブ技術に着想を得た新しいリテインドモードシステムの UI Toolkit です。このスキルでは、両方のシステムと、それぞれを使用する場面、実装パターンについて説明します。

UI システムの選択

要素	UGUI	UI Toolkit
ランタイム UI	成熟しており、機能が充実	対応（Unity 2023+）
エディター UI	非対応	エディターの主要システム
ワールド空間 UI	優秀（ワールド空間キャンバス）	限定的
アニメーション／トゥイーン	DOTween、Animator、LeanTween	USS トランジション、C# による操作
スタイル設定	要素ごとに手動で設定	USS スタイルシート（CSS に類似）
パフォーマンス	キャンバスが多いとドローコールが増加	リテインドモードにより、ドローコールが少ない
学習曲線	Unity 開発者にとっては緩やか	高め（ウェブに似たパラダイム）
VR/AR	十分にサポート	ワールド空間のサポートは限定的

推奨： ワールド空間 UI、VR/AR、アセットストアとの最大限の互換性が必要なプロジェクトには UGUI を使用してください。エディター拡張、複雑なデータ駆動型 UI（リスト、ツリー）、Unity 2023+ のプロジェクトには UI Toolkit を使用してください。

UGUI（キャンバスベースの UI）

キャンバスの設定

レンダーモード	用途	備考
Screen Space - Overlay	HUD、メニュー	常に最前面に表示され、カメラは不要
Screen Space - Camera	UI へのポストプロセス	レンダーカメラを割り当てる
World Space	ゲーム内の看板、体力バー	インタラクション用にイベントカメラを設定する

パフォーマンスのルール： 静的な UI と動的な UI は、別々のキャンバスに分けてください。子要素が 1 つでも変更されると、キャンバス内のすべての子要素が再構築されます。

RectTransform のアンカー設定

Anchor presets control how elements resize with parent:
- Stretch-Stretch: Element fills parent (full-screen backgrounds)
- Center-Center: Fixed size at center (popup dialogs)
- Bottom-Left: Fixed corner position (minimap)
- Top-Stretch: Stretches horizontally, fixed at top (nav bar)

RectTransform のアンカープリセットウィジェットを使ってアンカーを設定します（Alt+Shift を押したままにすると、ピボットと位置も設定されます）。コードでは anchorMin、anchorMax、offsetMin、offsetMax を使用します。

レイアウトコンポーネント

コンポーネント	目的
HorizontalLayoutGroup	子要素を左から右へ配置
VerticalLayoutGroup	子要素を上から下へ配置
GridLayoutGroup	グリッド状に配置（インベントリスロットなど）
LayoutElement	最小／推奨／可変サイズを上書き
ContentSizeFitter	コンテンツに合わせて自動的にサイズ変更
AspectRatioFitter	アスペクト比を維持

意図しない引き伸ばしを防ぐには、Layout.childForceExpandWidth/Height を無効にします。

イベント処理

using UnityEngine.UI;
using TMPro;

[SerializeField] Button startButton;
[SerializeField] TMP_InputField nameField;
[SerializeField] Slider volumeSlider;

void OnEnable()
{
    startButton.onClick.AddListener(OnStartClicked);
    nameField.onEndEdit.AddListener(OnNameChanged);
    volumeSlider.onValueChanged.AddListener(OnVolumeChanged);
}

void OnDisable()
{
    startButton.onClick.RemoveListener(OnStartClicked);
    nameField.onEndEdit.RemoveListener(OnNameChanged);
    volumeSlider.onValueChanged.RemoveListener(OnVolumeChanged);
}

リークやゴースト参照を防ぐため、OnDisable で必ず RemoveListener を呼び出してください。

TextMeshPro

従来の Text ではなく、必ず TextMeshPro（TMP_Text、TextMeshProUGUI）を使用してください。プロンプトが表示されたら、TMP Essentials をインポートします。インラインアイコンには、リッチテキストタグ <color=#FF0000>、<b>、<size=24>、<sprite=0> を使用します。

UI Toolkit（USS/UXML）

アーキテクチャ

UI Toolkit Stack:
  UXML  -- Structure (like HTML)
  USS   -- Styling (like CSS)
  C#    -- Logic (like JavaScript)

UXML の構造

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:VisualElement class="container">
        <ui:Label text="Player Stats" class="title" />
        <ui:ProgressBar name="health-bar" title="HP" high-value="100" />
        <ui:Button name="attack-btn" text="Attack" class="action-btn" />
        <ui:ListView name="inventory-list" />
    </ui:VisualElement>
</ui:UXML>

USS のスタイル設定

.container {
    flex-direction: column;
    padding: 10px;
    background-color: rgba(0, 0, 0, 0.8);
    border-radius: 8px;
}

.title {
    font-size: 24px;
    color: white;
    -unity-font-style: bold;
    margin-bottom: 10px;
}

.action-btn {
    height: 40px;
    background-color: #4CAF50;
    color: white;
    border-radius: 4px;
    transition-duration: 0.2s;
}

.action-btn:hover {
    background-color: #66BB6A;
    scale: 1.05 1.05;
}

CSS と USS の主な違い：Unity 固有のプロパティには -unity- プレフィックスを使用します。レイアウトモデルは Flexbox です（デフォルトの flex-direction: column）。アニメーションには transition-duration、transition-property を使用します。

C# との連携

[RequireComponent(typeof(UIDocument))]
public class StatsUI : MonoBehaviour
{
    void OnEnable()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;
        var healthBar = root.Q<ProgressBar>("health-bar");
        var attackBtn = root.Q<Button>("attack-btn");
        var inventory = root.Q<ListView>("inventory-list");

        attackBtn.RegisterCallback<ClickEvent>(OnAttack);
        healthBar.value = player.Health;

        // ListView binding
        inventory.makeItem = () => new Label();
        inventory.bindItem = (element, index) =>
            ((Label)element).text = items[index].Name;
        inventory.itemsSource = items;
    }
}

Q<T>("name") または Q<T>(className: "class") で要素を検索します。RegisterCallback<EventType> でコールバックを登録します。必ず rootVisualElement から検索してください。

データバインディング（Unity 2023.2+）

// Runtime data binding with [CreateProperty] and INotifyBindablePropertyChanged
public class PlayerData : INotifyBindablePropertyChanged
{
    public event EventHandler<BindablePropertyChangedEventArgs> propertyChanged;
    private int _health;

    [CreateProperty]
    public int Health
    {
        get => _health;
        set { _health = value; Notify(); }
    }
    void Notify([CallerMemberName] string prop = "")
        => propertyChanged?.Invoke(this, new BindablePropertyChangedEventArgs(prop));
}

UXML では binding-path="Health" を使ってバインドするか、C# では element.SetBinding("value", new DataBinding { dataSourcePath = ... }) を使用します。

一般的な UI パターン

パターン	UGUI の方法	UI Toolkit の方法
ポップアップダイアログ	子パネルを有効化／無効化	ビジュアルツリーに追加／削除
スクロールリスト	ScrollRect + VerticalLayoutGroup	ListView（仮想化）
ドラッグ＆ドロップ	IBeginDragHandler、IDragHandler、IEndDragHandler	PointerManipulator
タブシステム	Toggle グループ + パネル	RadioButtonGroup + 表示切り替え
ツールチップ	カーソルに追従するパネル	Manipulator + VisualElement の位置指定
画面フェード	CanvasGroup.alpha のトゥイーン	USS opacity トランジション

追加リソース

参考ファイル

• references/ugui-patterns.md -- UGUI の高度なパターン：スクロールの最適化、動的レイアウト、ワールド空間でのインタラクション、ローカライズ、セーフエリアの処理、画面への適応
• references/ui-toolkit-advanced.md -- カスタムコントロール、ListView/TreeView の活用、カスタムマニピュレーター、エディター UI との統合、テーマ設定、レスポンシブレイアウト