使用UQuery來查找element

UQuery受到JQuery與Linq啟發，UQuery被設計為會限制動態記憶體分配(dynamic memory allocation)，讓手機平台上可以擁有最佳化的效能。
可以使用Query和Q(Q是Query<T>.First()的縮寫)這兩個extension method來使用UQuery。

• Q與Query實際上是使用UQueryBuilder來建構一個query，這些extension method可以減少在建立UQueryBuilder時需要撰寫的模板程式碼。
• 在使用UQuery之前，你必須要先載入並實體化UXML，然後才能用Q或Query建立選取規則(selection rules)
  • 透過選擇規則返回的elements你還可以使用UQueryBuilder上的First，Last， AtIndex，Children與Where公開方法(public method)來更進一步的過濾它們。
• 可以透過element的name，USS class，element type (C# type)來找到想要的element。
• 也可以使用predicate或是組合[複雜結構的query](#Complex hierarchical queries)來找到想要的element
• UQuery會在初始化時Cache這些選出來的Elements。
• UI Toolkit不會自行銷毀沒用到的visual elements，它是使用C# garbage collector 來處理，因此最好不要在UIDocuments或Window之外建立這些elements的引用，避免讓C# garbage collector無法回收。

---

以下使用一個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 by name

語法為： Query(name: "element-name") 或是 Q(name: "element-name") ；你也可以省略參數名稱name，直接使用Query("element-name")

// 這句會回傳所有name為OK的element。
List<VisualElement> result = root.Query("OK").ToList();

// 這句會回傳找到name為OK的第一個element。
VisualElement result = root.Query("OK").First();
// 你也可以直接寫Q
VisualElement result = root.Q("OK");            

// 這句是選name為OK的第二個element（第一個element的index是0）
VisualElement result3 = root.Query("OK").AtIndex(1);

// 這句是選name為OK的最後一個element
VisualElement result4 = root.Query("OK").Last();

Query by USS class

語法為：Query(className: "class-name") 或是 Q(className: "class-name")

// 這句會選出所有class name為yellow的element
List<VisualElement> result = root.Query(className: "yellow").ToList();

// 這句會選class name為yellow的第一個element
VisualElement result = root.Q(className: "yellow");

Query by element type

語法為：Query<Type>() 或是 Q<Type>()

注意：你只能使用actual type來選出Element，而不能使用base type。

// 這句會選出第一個Button element
VisualElement result = root.Q<Button>();
// 將這個button的tooltip更改
result.tooltip = "This is a tooltip!";

// 這句會選出第三個Button element
VisualElement result = root.Query<Button>().AtIndex(2);

Query with a predicate

除了可以使用name，class-name，type來選出element以外，還可以搭配Where做更進一步的篩選，Where的參數是一個VisualElement。

// 這句會選出所有class name為yellow的element，然後在找出tooltip為空字串的element
List<VisualElement> result = root.Query(className: "yellow").Where(elem => elem.tooltip == "").ToList();

Complex hierarchical queries

可以將name，class-name，type等組合在一起，做更複雜的選擇。

// 這句將name，type，class-name做組合，選出class-name為yellow，name為OK的Button element
VisualElement result = root.Query<Button>(className: "yellow", name: "OK").First();

// 這句將選出container2中所有name為Cancel的Button element
VisualElement result = root.Query<VisualElement>("container2").Children<Button>("Cancel").First();