» VR開発メモトップへ

UI Toolkitメモ

最終更新日：2022年02月09日

UnityのUI Toolkitの使い方についてメモしていく場所です。

更新履歴

（2022年2月9日）「独自の要素を作成するには」を追加
（2021年12月1日）「UI Builderで実行時のスタイルシートが適用されない」を更新
（2021年10月5日）「エディタ専用のコントロールを使用するには」を追加
（2021年9月2日）Unity 2021.2について追記
（2021年8月26日）とりあえずページ作成

UI Toolkitについて

UI ToolkitはUnityの新しいUIシステムで、ブラウザのHTML、CSS、jQueryと似たような仕組みでエディタやランタイム（ゲーム中）のUIを作ることができます。

HTMLのような.uxmlファイル、CSSのような.ussファイル、jQueryのようなUQueryがあり、UIを視覚的にデザインできるUI Builderや、ChromeのデベロッパーツールのようなUI Toolkit Debuggerがあります。

UI Toolkitを手っ取り早く試すには

ProjectウィンドウでEditorフォルダを作って右クリックしてCreate > UI Toolkit > Editor Windowを実行し、適当にウィンドウの名前を入力します（TestWindowとか）。生成されるコードを見れば基本的なところはだいたい分かると思います。Window > UI Toolkitにウィンドウを開くメニューが追加されています。

さらに、Window > UI Toolkit > DebuggerでUI Toolkit Debuggerを開き、Pick Elementをクリックして、開いているTestWindowにマウスをホバーすると要素が確認できます。

どんな要素が使えるか調べるには

Windows > UI Toolkit > Samplesで要素の一覧が表示されます。また、下記ページにリファレンスがあります。

UI Toolkitを実行時に使用する

ゲーム中のUIを作成するには

Unity 2021.2以降では実行時にUI ToolkitのUIを使用できます。

ProjectウィンドウでCreate > UI Toolkit > Panel Settings Assetを、同じくCreate > UI Toolkit > UI Documentで.uxmlファイルを作成し、UXMLファイルをダブルクリックして適当にコンポーネントを追加します。ゲームオブジェクトにUI Documentコンポーネントをアタッチして、Parel Settingsと.uxmlをアタッチするととりあえず表示されます。

なお、ワールド空間にUI ToolkitのUIを表示することは現在できません（一応RenderTextureを使用する方法はあります）。UGUIを使用する必要があります。

また、実行時には使用できないコントロールが多数あります。「エディタ専用のコントロールを使用するには」を参照してください。

なお、Gameウィンドウに表示されているUIに対してもUI Toolkit Debuggerを使用できます。

UI DocumentコンポーネントのUXMLにアクセスするには

下記の要領でアクセスできます。

var startButton = GetComponent<UIDocument>().rootVisualElement.Q<Button>("start-button");

startButton.clicked += () =>
{
    StartGame();
}

複数のUIの表示を切り替えるには

UI Documentコンポーネントはひとつのゲームオブジェクトにつきひとつしかアタッチできないため、複数のゲームオブジェクトにUI Documentをアタッチして表示の有効・無効を切り替える必要があります。

Unity公式のサンプルプロジェクト「UI Toolkit Unity Royale Runtime Demo」が参考になります。

なお、ゲームオブジェクト自体やUI Documentを無効にするとイベントが剥がれてしまいますが、style.displayで非表示にすると剥がれません。

outRoomUIDocument.rootVisualElement.style.display = DisplayStyle.None;
inRoomUIDocument.rootVisualElement.style.display = DisplayStyle.Flex;

UXMLのTips

DOMのIDに相当するものはどこ？

nameになります。

<ui:Button ... name="start-button" />

これをQ<Button>(“start-button”)のようにしてクエリできます。

UI BuilderではHierarchyで要素をダブルクリックしてリネームすると設定できます。

TextFieldの入力値の変化を知るには

var textField = GetComponent<UIDocument>().rootVisualElement.Q<TextField>();
textField.RegisterValueChangedCallback(changeEvent =>
{
    Debug.Log(changeEvent.newValue);
});

独自の要素を作成するには

以下のようにVisualElementを継承したクラスを作成すると、カスタム要素としてUI Builderの左下のLibraryのProjectのところから使用できるようになります。なお、namespaceを使うとカテゴリ分けして表示されます。

class MyElement : VisualElement
{
    public new class UxmlFactory : UxmlFactory<MyElement, UxmlTraits> { }
}

UI Builderの下記ページに説明があります。

USSのTips

UI Builderで実行時のスタイルシートが適用されない

右上のほうのActive Editor ThemeからUnity Default Runtime Themeをチェックします。

UI BuilderのTips

エディタ専用のコントロールを使用するには

Hierarchyで.uxmlを選択して、InspectorのEditor Extension Authoringをオンにすると、Libraryにエディタのみで使用できるコントローラが表示されます。

その他のTips

UIElementsSchemaフォルダは何？

UXMLファイルをVisual StudioやRiederで編集するときの補完処理に使われるとのことです。バージョン管理からはずしてもよさそうです。

以下φ(..)メモメモ中

書いた人：こりん（@korinVR）
» VR開発メモトップへ