Uquery로 시각적 요소 찾기

UQuery를 사용하여 시각적 트리에서 요소를 찾을 수 있습니다.UQuery는 JQuery와 Linq에서 영감을 얻었으며 동적 메모리 할당을 제한하도록 설계되었습니다.이를 통해 모바일 플랫폼에서 최적의 성능을 발휘할 수 있습니다.

You can use UQuery through the Q and Query extension methods. Internally, the Q and Query methods use UQueryBuilder to construct a query. These extension methods reduce the verbosity of creating a UQueryBuilder.

To use UQuery to find elements, you must load and instantiate the UXML first.

To use Query and Q, construct specified selections rules on a root visual element. Query returns a list of elements that match the selection rules. Q is the shorthand for Query<T>.First(). It returns the first element that matches the selection rules.

You can filter the return results of Query with the public methods of UQueryBuilder, such as First, Last, AtIndex, Children, and Where.

You can query elements by their name, their USS class, or their element type(C# type). You can also query with a predicate or make complex hierarchical queries.

다음 섹션에서는 이 예시 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

To find elements by their name, use Query(name: "element-name") or Q(name: "element-name"). You can omit name as it’s the first argument. For example:

//Find a list of elements named "Ok".
List<VisualElement> result1 = root.Query("OK").ToList();

//Find the first element named "Ok" and add a tooltip for it.
VisualElement result2 = root.Query("OK").First(); //or VisualElement result = root.Q("OK");         
result.tooltip = "This is a tooltip!";    

//Find the second element named "Ok".
VisualElement result3 = root.Query("OK").AtIndex(1);       

//Find the last element named "Ok".
VisualElement result4 = root.Query("OK").Last();

Query by USS class

To find elements by a USS class, use Query(className: "class-name") or Q(className: "class-name"). For example:

//Find all the elements that have the class "yellow" and assign them to a list.
List<VisualElement> result = root.Query(className: "yellow").ToList();

//Find the first element that has the class "yellow".
VisualElement result = root.Q(className: "yellow");

Query by element type

To find elements by their element type(C# type), use Query<Type> or Q<Type>. For example:

//Find the first button and add a tooltip for it.
VisualElement result = root.Q<Button>();
result.tooltip = "This is a tooltip!";

//Find the third button.
VisualElement result = root.Query<Button>().AtIndex(2);

참고:기본 클래스가 아닌 요소의 실제 타입으로만 쿼리할 수 있습니다.

Query with a predicate

Other than to query element by name, class, and type, you can also use the Where method to select all elements that satisfy a predicate. The predicate must be a function callback that takes a single VisualElement argument. For example, the following code snippet finds the all the elements with the “yellow” USS class that have no tool tips:

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

Complex hierarchical queries

You can combine name, class, and type to make complex hierarchical queries. For example:

//Find the first button named "OK" that has a class of "yellow".
VisualElement result = root.Query<Button>(className: "yellow", name: "OK").First();
result.tooltip = "This is a tooltip!";

//Find the child cancel button of the "container2".
VisualElement result = root.Query<VisualElement>("container2").Children<Button>("Cancel").First();

Operate on results

You can use the ForEach method to operate directly on the query results. For example, the following code snippet adds a tool tip for any elements that have no tool tips:

root.Query().Where(elem => elem.tooltip == "").ForEach(elem => elem.tooltip="This is a tooltip!");

베스트 프랙티스

UQuery를 사용할 때는 다음 사항을 고려하십시오.

UQuery는 계층 구조를 횡단하여 이름, 클래스 또는 타입별로 요소를 찾습니다.초기화 시 UQuery의 캐시 결과입니다.
여러 요소를 검색해야 하는 경우 QueryState 구조체(element.Query() 메서드에 의해 반환됨)를 사용하여 열거하면 리스트가 생성되는 것을 방지할 수 있습니다.또한 쿼리를 한 번 구성하여 다른 요소에서 실행할 수도 있습니다.
UI 툴킷은 더 이상 필요하지 않은 시각적 요소를 파괴하지 않고 C# 가비지 컬렉터를 사용하여 수집합니다.실수로 시각적 요소에 대한 레퍼런스를 해당 요소의 출처인 UIDocuments 또는 Window보다 오래 지속되는 클래스에 유지하지 않도록 주의하십시오.
클로저 내부에서 VisualElement 변수를 캡처합니다.
많은 요소를 생성하거나 릴리스하는 경우 가비지 컬렉터 스파이크를 방지하려면 점진적 가비지 컬렉션을 활성화하십시오.

추가 리소스

C# 스크립트에서 UXML 인스턴스화

C# 스크립트로 UI 구조화