Migrate from Unity UI (UGUI) to UI Toolkit

This page guides developers with experience in Unity UI (UGUI) to transition to the new UI Toolkit system. It explores the similarities and differences between UGUI and the UI Toolkit.

As UGUI is a runtime-only UI system, this page focuses on runtime UI. UI Toolkit can create both runtime and Editor UI. This guide applies to both use cases for UI Toolkit.

UIヒエラルキー

Both UGUI and UI Toolkit build and maintain the UI inside a hierarchy tree structure. In UGUI, all elements in this hierarchy are visible as individual GameObjects in the hierarchy view panel. In UI Toolkit, visual elements organize into a Visual Tree. The Visual Tree isn’t visible in the panel.

UI Toolkit での UI 階層の表示とデバッグは、UI デバッガーを使用して行えます。UI デバッガーは、エディターツールバーの Window > UI Toolkit > Debugger の下にあります。

主な相違点

Canvas と UIDocument

The Canvas component in UGUI is similar to the UIDocument component in UI Toolkit. Both are MonoBehaviours that attach to GameObjects.

In UGUI, a Canvas component sits at the root of the UI tree. It works with the Canvas Scaler component to determine the sort order, rendering, and scaling mode of the UI underneath.

UI Toolkit では、UIDocument コンポーネントに PanelSettings オブジェクトへの参照が含まれています。PanelSettings には、スケールモードやソート順などの、UI のレンダリング設定が含まれています。複数の UIDocument コンポーネントが同じ PanelSettings オブジェクトを指すことができるので、同じシーンに複数の UI 画面を使用する場合にパフォーマンスが最適化されます。

In UGUI, the UI tree hierarchy sits underneath the GameObject holding the Canvas component. In UI Toolkit, the UIDocument component holds a reference to the root element of the Visual Tree.

UIDocument コンポーネントには、(ランタイムにビジュアルツリーが構築される基となる) UI レイアウトを定義する UXML ファイルへの参照も含まれています。詳しくは UI の作成 のセクションを参照してください。

ノート:
For Editor UI, no UIDocument component is needed. You can derive your custom class from EditorWindow, then implement CreateGUI(). For a practical example, see the guide on Creating custom Editor windows.

GameObject Components versus Visual Elements

UI Toolkit では、UI 要素は “コントロール” または “ビジュアル要素” と呼ばれます。UI 要素には、例えば以下のようなものがあります。

• コントロール
• ボタン
• テキストラベル

UGUI builds the UI hierarchy from GameObjects. Adding new UI elements requires adding new GameObjects to the hierarchy. The individual controls are implemented as MonoBehaviour components.

In UI Toolkit, the Visual Tree is virtual and doesn’t use GameObjects. You can no longer build or view the UI hierarchy in the hierarchy view, but it removes the overhead of using a GameObject for each UI element.

In UGUI, UI elements derive (directly or indirectly) from the UIBehavior base class. Similarly, in UI Toolkit all UI elements derive from a base class called VisualElement. The key difference is the VisualElement class doesn’t derive from MonoBehaviour. You can not attach visual elements to GameObjects.

Working with UI Toolkit controls in script is similar to working with UGUI controls. The following table shows common script interactions with UI controls in UGUI, and their UI Toolkit counterparts.

アクション	UGUI	UI Toolkit
ラベルにテキストを書き込む	m_Label.text = "My Text";	m_Label.text = "My Text";
トグルの状態を読み取る	bool isToggleChecked = m_Toggle.isOn;	bool isToggleChecked = m_Toggle.value;
ボタンへのコールバックの割り当て	m_Button.onClick.AddListener(MyCallbackFunc);	m_Button.clicked += MyCallbackFunc_1; or m_Button.RegisterCallback<ClickEvent>(MyCallbackFunc_2);

コントロールとそのプロパティやイベントについての詳細は、コントロールの概要 のページを参照してください。

UI要素へのアクセス

In UGUI, there are two ways scripts can access UI elements:

• エディターで UI コンポーネントへの参照を割り当てる
• GetComponentInChildren<T>() などのヘルパー関数を使用して、階層内でコンポーネントを見つける

UI Toolkit にはゲームオブジェクトやコンポーネントがないため、エディターでコントロールへの参照を直接割り当てることはできません。これらはランタイムにクエリ関数を使用して解決する必要があります。 代わりに、UIDocument コンポーネントを通してビジュアルツリーにアクセスします。

UIDocument is a MonoBehaviour, so you can assign it as a reference and make it part of a Prefab. The UIDocument component holds a reference to the root visual element. From the root, scripts can find child elements by type or by name, similar to UGUI.

以下の表は、Unity UI での UI コントロールへのアクセス方法と UI Toolkit での UI コントロールへのアクセス方法を直接比較したものです。

アクション	UGUI	UI Toolkit
UI 要素を名前で探す	transform.FindChild("childName");	rootVisualElement.Query("childName");
UI 要素のタイプ別検索	transform.GetComponentInChildren<Button>();	rootVisualElement.Query<Button>();
エディターでの参照の直接割り当て	可	不可

UIの作成

One of the biggest differences between UGUI and UI Toolkit is the creation of user interfaces.

Both UGUI and UI Toolkit allow you to visually build the UI and preview it in the Editor. In UGUI, the UI is then saved inside a Prefab, along with any logic scripts attached to individual UI controls.

UI Toolkit では、UI レイアウトは UI Builder で作成され、1 つまたは複数の UXML ファイルとして保存されます。ランタイムに、UIDocument コンポーネントが、ビジュアルツリーがアセンブルした UXML ファイルをメモリにロードします。

For a method similar to UGUI, you can create UI controls directly from a script, then add them to a Visual Tree at runtime.

プレハブ

UGUI uses GameObjects for individual UI controls and Prefabs that both contain visuals and logic. UI Toolkit takes a different approach to reusability, as it separates logic and layout. You can create reusable UI components through UXML and custom controls.

UI Toolkit でプレハブに類似したテンプレートを作成するには、以下を行ってください。

1. 部分的な UI 要素のための XML ファイルを作成します。
2. UIDocument コンポーネントを持つゲームオブジェクトを作成します。
3. そのゲームオブジェクト内で UXML ファイルを参照します。
4. 同じゲームオブジェクトに、UI コンポーネントのロジックを処理するスクリプトを追加します。
5. このゲームオブジェクトをプレハブとして保存します。

UI Layout

Arranging individual UI elements on screen in UGUI is a manual process. By default, UI controls are free floating and are only affected by their direct parent. Other UI controls under the same parent don’t affect their siblings positions or sizes. Pivots and anchors control the position and size of an element.

UI Toolkit のレイアウトシステムは、ウェブデザインの影響を受けており、自動レイアウト生成に基づいています。自動レイアウトシステムは、デフォルトで全ての要素に影響し、要素のサイズと位置は、同じ親の下にある他の要素に影響します。

The default behavior in UI Toolkit is comparable to placing all elements inside a VerticalLayoutGroup in UGUI, and adding a LayoutElement component to each.

You can disable automatic layout generation by changing the IStyle position property of the visual element. All visual elements have this property. See Visual Tree for a code sample.

UI Toolkit has no direct equivalents for anchoring and pivots of UI elements, due to the fundamental layout differences compared to UGUI.

The size and position of an element is controlled by the layout engine. To learn more about this, please see the Layout Engine documentation, and the Positioning section of the Visual Tree page.

レンダリングの順番

In UGUI, the order of the GameObjects in the hierarchy determines the rendering order. Objects further down in the hierarchy render last and appear on top. In a scene with multiple Canvases, the Sort Order on the root Canvas component determines the render order of the individual UI trees.

The render order in a Visual Tree in UI Toolkit operates the same way. Parent elements render before their children, and children render from the first to the last, so that the last appears on top. IUn a scene with multiple UI Documents, the render order is determined by the Sort Order setting on the root UIDocument component.

To change the rendering order of an element in UGUI, such as making an element appear on top, you can call the sibling functions on the Transform component of the GameObject. The VisualElement class offers comparable functions to control the rendering order. As all UI Toolkit controls derive from this class, all controls have access to this function.

The table below shows the UGUI functions to control render order and the equivalent functions in UI Toolkit:

アクション	UGUI	UI Toolkit
要素を他の兄弟の下にレンダリングする	transform.SetAsFirstSibling();	myVisualElement.SendToBack();
要素を他の兄弟の上にレンダリングする	transform.SetAsLastSibling();	myVisualElement.BringToFront();
要素の兄弟に対するレンダリング順序を手動で制御する	transform.SetSiblingIndex(newIndex);	myVisualElement.PlaceBehind(sibling); myVisualElement.PlaceInFront(sibling);

イベント

Just like in UGUI, user interactions in UI Toolkit trigger events. The code can subscribe to receive a callback on events, such as pressing a button or moving a slider.

In UGUI, all UI elements are based on MonoBehaviour, and can expose their events in the Editor. This allows to set up logic with other GameObjects, for example to hide or unhide other UI elements, or to assign callback functions.

UI Toolkit では、ロジックと UI レイアウトが別々に保存されます。コールバックをゲームオブジェクトに直接設定したり、プレハブに保存することはできなくなりました。全てのコールバックはランタイムで設定し、スクリプティングによって処理する必要があります。

Button playButton = new Button("Play");
playButton.RegisterCallback<ClickEvent>(OnPlayButtonPressed);
...
private void OnPlayButtonPressed(ClickEvent evt)
{
  // Handle button press  
}

The event dispatching system in UI Toolkit differs from events in UGUI. Depending on the event type, events aren’t just sent to the target UI control, but also to all the parent controls.

To learn more about this, see Events Dispatching.