Unity UI Toolkitの使い方｜画面を作り、ボタンの処理をつなぐ

UnityのUI Toolkitは、UXMLというファイルで画面の部品を並べ、USSで見た目を整え、C#で動きをつなぐUIの仕組みです。

ゲーム画面に出すまでの流れは、公式マニュアルでは次の4つにまとめられています。

1. ボタンなどの部品を置いたUXMLを作る
2. シーンにUI Documentを置き、そのUXMLを指定する
3. MonoBehaviourのスクリプトで部品の動きを決める
4. 必要なら、入力を受け取るイベントシステムを設定する

この記事では、この流れに沿って、ボタンを1つ置き、押したらコンソールに文字を出すところまでを説明します。

説明は、Unity 6.3 LTSの公式マニュアルとスクリプトリファレンスの記載（2026年10月18日に確認）をもとにしています。

画面は、Unity 6.6（6000.6.5f1）のUniversal 3Dテンプレートで作った練習用のプロジェクトで撮影し、UI Builderで画面を作るところから、再生してボタンを押すまでを実際に確かめました。

6.3 LTSの画面そのものは確かめていません。

最新版のUnity 6.6のマニュアルも公開されていますが、長期サポートのある6.3 LTSを基準にしました。

画面の名前は英語版の表記です。

UI ToolkitとuGUIのどちらを使うか

UnityのUIの仕組みには、UI Toolkitのほかに、ゲームオブジェクトで組み立てるuGUI（Unity UI）があります。

公式マニュアルの比較のページでは、ゲーム中のUIはuGUIが推奨で、UI Toolkitは代わりの選択肢とされています。

エディタ拡張のUIは、UI Toolkitが推奨です。

同じページでは、ゲーム中のUIでUI Toolkitがよく使われる例として、UIの多いプロジェクトの解像度違いに対応するメニューやHUD、ワールド空間のUIとVR、独自のシェーダーやマテリアルを使うUIが挙がっています。

一方で、キーフレームのアニメーションを使うUIはuGUIがよく使われるとされています。

機能の比較表では、UI Toolkitはシーン上での直接の編集、インスペクターで設定するイベント、アニメーションクリップやTimelineとの連携に対応していません。

反対に、データバインディング、UIのトランジションアニメーション、まとめて管理するスタイルは、UI Toolkitだけが対応しています。

uGUIで作る場合は、Unity Canvasの使い方から始めてください。

UI Toolkitで使うもの

公式マニュアルでは、UI Documentはシーンとレイアウトのファイルをつなぐ橋渡しで、UXMLが画面の構造を、Panel Settingsが描画を受け持つと説明されています。

手順1：UI Builderで画面を作る

1. Window → UI Toolkit → UI Builder を開く
2. Viewportの左上の File → New で、新しいUXMLを作って保存する
3. LibraryからVisualElementをHierarchyへドラッグし、画面全体の土台にする
4. 土台を選び、InspectorでFlexのGrowを1にする
5. LibraryからButtonを土台の中へドラッグする
6. ButtonのNameに、スクリプトから探すための名前（例：start-button）を入れる
7. Viewportの File → Save で保存する

Growを1にすると、その要素が画面全体に広がります。

子の要素を中央にそろえる場合は、Align ItemsとJustify Contentの両方をCenterにします。

Unity 6.6で試すと、Visual ElementをHierarchyのいちばん上に置いた時点で、FlexのGrowはすでに1になっていました。

この場合、手順4は値が1になっているかを確かめるだけで済みます。

ボタンの文字は、InspectorのTextで変えられます。

Textの欄は複数行を入力できる欄で、Enterキーで確定しようとすると改行が文字に入り、保存したUXMLが text="Start
" になりました。

文字を入れたら、Enterキーではなく別の欄を押して確定します。

公式マニュアルでは、色のAlphaは初期値が0で、そのままでは透明になるため、色を付けるときはAlphaを255にするよう注意書きがあります。

UXMLは文字で書くこともできます。

上の手順と同じ内容をUXMLで書くと、次のようになります。

<ui:UXML xmlns:ui="UnityEngine.UIElements" editor-extension-mode="False">
    <ui:VisualElement style="flex-grow: 1; align-items: center; justify-content: center;">
        <ui:Label text="Title" />
        <ui:Button text="Start" name="start-button" />
    </ui:VisualElement>
</ui:UXML>

このUXMLをそのままAssetsに置いてUI Documentに指定し、Unity 6.6で再生すると、Titleの文字とStartのボタンが表示され、ボタンも反応しました。

UI Builderで保存したUXMLは、この例からLabelの行を除いた内容で、1行目に xmlns:uie="UnityEditor.UIElements" の指定が加わっていました。

同じ見た目を複数の要素に使うようになったら、USSのクラスにまとめます。

UI Builderでは、要素に直接設定した値を、Extract Inlined Styles to New Class で新しいクラスに移せます。

手順2：シーンに表示する

1. メニューの GameObject → UI Toolkit → UI Document を選ぶ（Unity 6.6では GameObject → UI Toolkit → Legacy → UI Document）
2. Hierarchyにできたゲームオブジェクトを選ぶ
3. 作ったUXMLを、InspectorのUI DocumentのSource Assetへドラッグする（欄の右の丸いボタンを押し、一覧から選んでもよい）

公式マニュアルでは、GameObject → UI Toolkit → UI Document を選ぶと、Panel Settingsのアセットと初期のテーマが入ったUI Toolkitフォルダーと、UI Documentが付いたゲームオブジェクトが作られると説明されています。

Unity 6.6では、GameObject → UI Toolkit の中にUI Documentが直接は無く、Legacyの中に移っていました。

選ぶと、AssetsにUI Toolkitフォルダーができ、中にPanelSettingsと、UnityThemesフォルダーのUnityDefaultRuntimeThemeが作られました。

Hierarchyには、UI Documentが付いたUIDocumentという名前のゲームオブジェクトができました。

Unity 6.6のUI DocumentのInspectorには、新しいPanel Rendererコンポーネントへの移行を勧める表示が出ます。

表示によると、UI Documentはこの先も使えますが、新しい機能は追加されません。

この記事の手順は、6.6でもUI Documentのまま最後まで動きました。

1つのPanel Settingsに、複数のUI Documentをつなぐこともできます。

画面を部品ごとに別のUXMLに分けて作るときに使います。

手順3：ボタンの処理をつなぐ

ボタンを押したときの処理は、MonoBehaviourのスクリプトで書き、UI Documentと同じゲームオブジェクトに付けます。

using UnityEngine;
using UnityEngine.UIElements;

public class StartMenu : MonoBehaviour
{
    Button _startButton;

    void OnEnable()
    {
        // UXMLはUI Documentが読み込み済みなので、その一番上の要素から探す
        var root = GetComponent<UIDocument>().rootVisualElement;
        _startButton = root.Q<Button>("start-button");
        _startButton.clicked += OnStartClicked;
    }

    void OnDisable()
    {
        if (_startButton != null)
        {
            _startButton.clicked -= OnStartClicked;
        }
    }

    void OnStartClicked()
    {
        Debug.Log("Start が押されました");
    }
}

このスクリプトをUI Documentのゲームオブジェクトに追加して再生し、ボタンを押すとConsoleに文字が出ます。

このコードは、公式マニュアルの例とスクリプトリファレンスの書き方をもとにしたものです。

Unity 6.6で、このコードをそのままStartMenu.csとしてAssetsに置き、メニューの Component → Scripts → Start Menu でUIDocumentのゲームオブジェクトに追加しました。

再生してStartボタンを押すと、押すたびにConsoleに「Start が押されました」が1行ずつ出ました。

OnEnableで探す理由

公式マニュアルでは、UI DocumentはOnEnableが呼ばれたときにUXMLを読み込むため、部品を扱う処理はOnEnableに書くよう説明されています。

また、UI Documentは、OnEnableとOnDisableのタイミングで中身を消します。

公式マニュアルの別の例でも、UIが読み込み直されるときは同じゲームオブジェクトのスクリプトがいったん無効になってから有効に戻るため、UIを扱う処理はOnEnableとOnDisableに書くよう注意書きがあります。

clickedとClickEventの違い

ボタンの処理のつなぎ方は、主に2つあります。

どちらの場合も、OnDisableで外しておくと、同じ処理が何度もつながるのを防げます。

公式マニュアルの例も、OnDisableでUnregisterCallbackを呼んでいます。

Input System 1.20のドキュメントによると、ClickEventはポインターでのクリックだけで発生し、ゲームパッドの決定ボタンでは発生しません。

ゲームパッドの決定ボタンにも反応させたい場合は、clickedを使います。

画面サイズに合わせる

解像度の違う画面でUIの大きさをどう変えるかは、Panel SettingsのScale Modeで決めます。

Scale With Screen Sizeでは、基準にする解像度（Reference Resolution）と、幅と高さのどちらに合わせるか（Screen Match Mode）を設定します。

ボタンが反応しないときの確認

• スクリプトがUI Documentと同じゲームオブジェクトに付いているか
• Q<Button> に渡した名前が、UXMLのNameと一字一句同じか
• 部品を探す処理がOnEnableに書かれているか
• uGUIと同じシーンで使う場合、EventSystemの入力モジュールが入力の設定と合っているか

スクリプトリファレンスでは、Qは条件に合う要素が見つからないとnullを返すと説明されています。

名前が違うと、clickedにつなぐ行でNullReferenceExceptionが出ます。

UXMLのボタンの名前だけをstartButtonに変えて再生すると、その時点でConsoleにNullReferenceExceptionが出て、場所はStartMenu.csの13行目（clickedにつなぐ行）と表示されました。

ボタンは画面に出ますが、押してもConsoleには何も出ません。

EventSystemは要るか

公式マニュアルでは、再生を始めるとUI Toolkitが既定のイベントシステムを自動で作るため、UI Toolkitだけのシーンでは、シーンにEventSystemを置く必要はないとされています。

uGUIと同じシーンで使う場合は、EventSystemと、入力の設定に合った入力モジュールが必要です。

Unity 6.6の練習用のシーン（Universal 3Dテンプレート）でも、EventSystemを置かずに、マウスのクリックでボタンが反応しました。

Active Input Handlingは、Edit → Project Settings → Player の Other Settings にあります。

切り替え方は、Input Systemの切り替え｜Active Input Handlingで説明しています。

UIを一時的に隠す

公式マニュアルでは、UI Documentは無効になると中身を消すと説明されています。

すぐにまた表示するUIは、コンポーネントを無効にするのではなく、rootVisualElementのdisplayをnoneにして隠す方法が案内されています。

// 隠す
root.style.display = DisplayStyle.None;
// もう一度表示する
root.style.display = DisplayStyle.Flex;

参考にした公式ページ

• Comparison of UI systems in Unity
• Get started with runtime UI
• Get started with UI Builder
• UI Document component
• Panel Settings properties reference
• Runtime UI event system and input handling
• Button.clicked（スクリプトリファレンス）
• Input System 1.20：Understand UI system compatibility