UI Toolkitメモ
最終更新日：2022年02月09日記事作成日：2021年08月26日
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で編集するときの補完処理に使われるとのことです。バージョン管理からはずしてもよさそうです。
以下φ(..)メモメモ中