UQuery でビジュアル要素を検索する

UQuery を使用して、ビジュアルツリー から要素を検索できます。UQuery は JQuery と Linq からヒントを得ており、動的メモリ割り当てを制限するように設計されています。これにより、モバイルプラットフォームで最適なパフォーマンスが可能になります。

クエリメソッド

以下の拡張メソッドで UQuery を使用できます。

• Q
• Query

内部的には、Q メソッドと Query メソッドは UQueryBuilder を使用してクエリを作成します。これらの拡張子メソッドは、UQueryBuilder を作成する際の煩雑さを軽減します。

UQuery を使用して要素を検索するには、まず UXML を ロード して インスタンス化 し、次に Query または Q を使用してルートのビジュアル要素の選択ルールを構築します。

Query は、選択ルールに一致する要素のリストを返します。Query の戻り値は、UQueryBuilder のパブリックメソッド (First、Last、AtIndex、Children、Where など) を使用してフィルターできます。

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>

名前によるクエリ

要素を 名前 で検索するには、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 クラスによるクエリ

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 メソッドを使用して、述語を満たす要素すべてを選択することもできます。述語は、1 つの VisualElement 引数を取る関数コールバックである必要があります。

以下の例では、USS クラスが “yellow” で、ツールチップを持たない要素すべてを検索します。

List<VisualElement> result = root.Query(className: "yellow").Where(elem => elem.tooltip == "").ToList();

複雑な階層クエリ

名前、クラス、型を組み合わせて、複雑な階層クエリを作成できます。

以下の例では、“OK” という名前のボタンのうち、“yellow” クラスを持つ最初のボタンを検索します。

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 を使用する場合は、以下の点を考慮してください。

• UQuery は階層を走査して、名前、クラス、型で要素を検索します。初期化時に UQuery の結果をキャッシュします。
• 複数の要素を取得する必要がある場合は、(element.Query() メソッドによって返される) QueryState 構造体を使用し、リストの作成を避けて列挙します。また、クエリを 1 回作成し、異なる要素に対して実行することもできます。
• UI Toolkit は、不要になったビジュアル要素は破棄せず、C# ガベージコレクターを使用して収集します。要素の取得元の UIDocument または Window よりも長く存続するクラスのビジュアル要素への参照を誤って保持しないように注意してください。
• クロージャ内の VisualElement 変数をキャプチャします。
• 多くの要素を作成またはリリースする場合は、インクリメンタルガベージコレクション を有効にして、ガベージコレクターのスパイクを回避します。

追加リソース

• USS セレクター
• ビジュアル要素とビジュアルツリーについて
• C# スクリプトから UXML と USS をロードする
• C# スクリプトから UXML をインスタンス化する