UQuery を使用すると、ビジュアルツリー から要素を見つけることができます。UQuery は JQuery と Linq に発想を得て、動的なメモリ割り当てを制限するように設計されています。これにより、モバイルプラットフォームで最適なパフォーマンスを実現できます。
UQuery は以下の拡張メソッドを介して使用できます。
内部的には、Q メソッドと Query メソッドは UQueryBuilder を使用し、クエリを作成します。これらの拡張メソッドは、UQueryBuilder を作成する際の煩雑さを軽減します。
UQuery を使用して要素を検索するには、まず UXML を ロード して インスタンス化 し、それから Query または Q を使用してルートのビジュアル要素に選択ルールを作成する必要があります。
Query は選択ルールに一致する要素のリストを返します。First、Last、AtIndex、Children、Where など、UQueryBuilder のパブリックメソッドを使用して、Query の返り値にフィルターをかけることができます。
Q は Query<T>.First()の省略形です。選択規則に一致する最初の要素を返します。
要素の 名前、USS クラス、要素の型 (C# 型) でクエリを実行できます。また、述語 を使ったクエリや 複雑な階層クエリ の作成も可能です。
以下のセクションでは、この例の UXML を使用して、要素の検索方法を説明します。
<UXML xmlns="UnityEngine.UIElements">
<VisualElement name="container1">
<Button name="OK" text="OK" />
<Button name="Cancel" text="Cancel" />
</VisualElement>
<VisualElement name="container2">
<Button name="OK" class="yellow" text="OK" />
<Button name="Cancel" text="Cancel" />
</VisualElement>
<VisualElement name="container3">
<Button name="OK" class="yellow" text="OK" />
<Button name="Cancel" class="yellow" text="Cancel" />
</VisualElement>
</UXML>
要素を name (名前) で検索するには、Query(name: "element-name") か Q(name: "element-name") を使用します。name は最初の引数なので省略できます。
下の例は、“Ok” という名前の要素を見つけます。
List<VisualElement> result = root.Query("OK").ToList();
下の例では、Query を使って “Ok” という名の最初の要素を見つけます。
VisualElement result = root.Query("OK").First(); //or VisualElement result = root.Q("OK");
下の例では、Qを使って“Ok ”という最初の要素を見つけます。
VisualElement result = root.Q("OK");
下の例は、“Ok” という名前の 2 番目の要素を見つます。
VisualElement result3 = root.Query("OK").AtIndex(1);
下の例は、“Ok” という名前の最後の要素を見つます。
VisualElement result4 = root.Query("OK").Last();
USS クラスで 要素を検索するには、Query(className: "class-name") か Q(className: "class-name") を使用します。
下の例では、クラス “yellow” を持つすべての要素を見つけ、それらをリストに割り当てます。
List<VisualElement> result = root.Query(className: "yellow").ToList();
下の例では、クラス “yellow” を持つ最初の要素を見つけます。
VisualElement result = root.Q(className: "yellow");
要素の型 (C# 型) から要素を検索するには、Query<Type> か Q<Type> を使用します。
下の例では最初のボタンを見つけ、それにツールチップを加えます。
VisualElement result = root.Q<Button>();
result.tooltip = "This is a tooltip!";
下の例では、3 つ目のボタンを見つけます。
VisualElement result = root.Query<Button>().AtIndex(2);
ノート: 基本クラスではなく、要素の実際の型によってのみクエリを行うことができます。
名前、クラス、型で要素を問い合わせる以外に、Where メソッドを使用して、述語を満たすすべての要素を選択することもできます。述語は、単一の VisualElement 引数をとる関数コールバックでなければなりません。
下の例は、ツールチップを持たない “yellow” USS クラスを持つすべての要素を見つけます。
List<VisualElement> result = root.Query(className: "yellow").Where(elem => elem.tooltip == "").ToList();
name、class、type を組み合わせて、複雑な階層クエリを作ることができます。
下の例では、クラス “yellow” を持つ “OK” という名の最初のボタンを見つけます。
VisualElement result = root.Query<Button>(className: "yellow", name: "OK").First();
下の例では、 “container2” の子キャンセルボタンを見つけます。
VisualElement result = root.Query<VisualElement>("container2").Children<Button>("Cancel").First();
ForEach メソッドを使用すると、クエリ結果を直接操作できます。
下の例では、ツールチップのない要素にツールチップを加えます。
root.Query().Where(elem => elem.tooltip == "").ForEach(elem => elem.tooltip="This is a tooltip!");
UQuery を使用する際は、以下の点を考慮してください。
QueryState 構造体 (element.Query() メソッドで返されます) を使用し、リストの作成を避けるために列挙します。また、クエリを一度構築し、異なる要素に対して実行することもできます。VisualElement 変数をキャプチャします。