Version: 2022.3
언어: 한국어
C# 스크립트에서 UXML 인스턴스화
C# 스크립트로 UI 구조화

Uquery로 시각적 요소 찾기

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

쿼리 메서드

다음 확장 메서드를 통해 UQuery를 사용할 수 있습니다.

내부적으로 QQuery 메서드는 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>

이름으로 쿼리

이름으로 요소를 찾으려면 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”라는 두 번째 요소를 찾습니다.

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!";

다음 예시에서는 세 번째 버튼을 찾습니다.

VisualElement result = root.Query<Button>().AtIndex(2);

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

술어로 쿼리

이름, 클래스 및 타입별로 요소를 쿼리하는 것 외에도 Where 메서드를 사용하여 술어를 만족하는 모든 요소를 선택할 수도 있습니다.술어는 단일 VisualElement 인자를 받는 함수 콜백이어야 합니다.

다음 예시는 툴팁이 없는 “yellow” USS 클래스를 가진 요소를 모두 찾습니다.

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

복잡한 계층적 쿼리

이름, 클래스, 타입을 결합하여 복잡한 계층적 쿼리를 만들 수 있습니다.

다음 예제에서는 클래스가 “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를 사용할 때는 다음 사항을 고려하십시오.

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

추가 리소스

C# 스크립트에서 UXML 인스턴스화
C# 스크립트로 UI 구조화