【Unity】UI ToolkitのVisualElement.Query<T>とVisualElement.Q<T>の違いについて

はじめに

UI ToolkitではVisual TreeからVisualElementを検索するためにUQueryを利用しますが、クエリメソッドとしてQとQueryがあります。

今回はその違いについて取り上げたいと思います。

概要

Queryは該当する全てのVisualElementの情報を返し、Qは該当する最初のVisualElementを返します。

// サンプルコード
// rootVisualElementを根とする木に含まれるButtonを全て取得する
UQueryBuilder<Button> buttons = rootVisualElement.Query<Button>();

// rootVisualElementを根とする木に含まれるButtonを一つ取得する
Button button = rootVisualElement.Q<Button>();

public static T Q<T>(this VisualElement e, string name = null, params string[] classes) where T : VisualElement
public static T Q<T>(this VisualElement e, string name = null, string className = null) where T : VisualElement
public static VisualElement Q(this VisualElement e, string name = null, params string[] classes)
public static VisualElement Q(this VisualElement e, string name = null, string className = null)

public static UQueryBuilder<VisualElement> Query(this VisualElement e, string name = null, params string[] classes)
public static UQueryBuilder<VisualElement> Query(this VisualElement e, string name = null, string className = null)
public static UQueryBuilder<VisualElement> Query(this VisualElement e)
public static UQueryBuilder<T> Query<T>(this VisualElement e, string name = null, params string[] classes) where T : VisualElement
public static UQueryBuilder<T> Query<T>(this VisualElement e, string name = null, string className = null) where T : VisualElement

Unity - Scripting API: UIElements.UQueryExtensions.Query
Unity - Scripting API: UIElements.UQueryExtensions.Q

詳細

厳密に言うとQはQueryで取得した配列の最初の要素を取得します。

Q is the shorthand for Query.First(). It returns the first element that matches the selection rules.

// DeepL翻訳
QはQuery.First()の省略形です。選択規則にマッチする最初の要素を返します。

Unity - Manual: Find visual elements with UQuery

内部実装を見てみれば簡単に雰囲気をつかめます。

// オーバーロードも似た感じのコードが書かれている
public static T Q<T>(this VisualElement e, string name = null, params string[] classes) where T : VisualElement => e.Query<T>(name, classes).Build().First();