VisualTreeHelper 클래스

참조

정의

네임스페이스:: Windows.UI.Xaml.Media

중요

일부 정보는 릴리스되기 전에 상당 부분 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다.

편집

앱의 시각적 트리에서 개체 관계(자식 개체 또는 부모 개체 축을 따라)를 트래버스하는 데 사용할 수 있는 유틸리티 메서드를 제공합니다.

public ref class VisualTreeHelper sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualTreeHelper final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class VisualTreeHelper

Public NotInheritable Class VisualTreeHelper

상속: Object Platform::Object IInspectable VisualTreeHelper

특성: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 요구 사항

디바이스 패밀리	Windows 10 (10.0.10240.0에서 도입되었습니다.)
API contract	Windows.Foundation.UniversalApiContract (v1.0에서 도입되었습니다.)

예제

다음은 시각적 트리 내에서 특정 형식의 자식 요소 목록을 복사할 수 있는 유틸리티 함수의 예입니다. 기본 통과 메서드 GetChildrenCount 및 GetChild를 사용합니다. 중간 컨테이너 내에 있는 중첩 수준에 관계없이 요소를 찾을 수 있도록 재귀를 사용합니다. 또한 형식 비교를 확장하는 System.Reflection의 IsSubclassOf 확장 메서드를 사용하여 하위 형식을 Type에 대한 일치 항목으로 간주합니다.

internal static void FindChildren<T>(List<T> results, DependencyObject startNode)
  where T : DependencyObject
{
    int count = VisualTreeHelper.GetChildrenCount(startNode);
    for (int i = 0; i < count; i++)
    {
        DependencyObject current = VisualTreeHelper.GetChild(startNode, i);
        if ((current.GetType()).Equals(typeof(T)) || (current.GetType().GetTypeInfo().IsSubclassOf(typeof(T))))
        {
            T asType = (T)current;
            results.Add(asType);
        }
        FindChildren<T>(results, current);
    }
}

설명

시각적 트리

VisualTreeHelper 클래스의 목적은 개체의 런타임 트리에서 찾고 있는 개체를 검색하는 데 도움이 되지만 시나리오에 사용할 수 있는 보다 직접적인 개체 관계 API는 없습니다. 경우에 따라 개체의 정확한 형식이나 이름을 알 수 없습니다. 또는 특정 개체가 트리의 어딘가에 나타나는 것을 알고 있지만 정확한 위치를 알지 못할 수도 있습니다. 이러한 유형의 시나리오에서 VisualTreeHelper는 시각적 트리에서 모든 개체를 재귀적으로 찾은 다음 이 집합을 살펴보고 조건에 따라 일치 항목을 찾을 수 있으므로 유용합니다.

앱의 시각적 트리는 앱 개체 및 속성의 더 큰 개체 트리를 필터링된 표현으로 개념화할 수 있습니다. 렌더링에 영향을 주는 개체만 시각적 트리에 있습니다. 예를 들어 컬렉션 클래스는 시각적 트리의 일부가 아닙니다. 대신 시각적 트리는 모든 컬렉션을 "자식" 개념으로 추상화합니다.

그러나 시각적 트리에는 페이지의 XAML 태그에 XAML 요소로 표시되지 않는 개체가 포함될 수도 있습니다. 시각적 트리가 컨트롤의 복합 부분인 개체를 추가하기 때문입니다. 이러한 컨트롤 파트는 일반적으로 리소스 사전 항목 또는 발표자의 XAML인 적용된 컨트롤 템플릿에서 올 수 있습니다.

XAML은 태그 및 태그 정의 중에 사용하기 용이하도록 설계되었으므로 XAML 태그와 시각적 트리가 노드에 대한 노드와 정확히 일치하지 않으므로 경우에 따라 추가 요소가 있습니다. 예를 들어 XAML에는 한 요소가 다른 요소 내에 중첩된 경우 속성 값을 설정하는 속성 요소가 있습니다. 시각적 트리에서는 다른 개체가 설정하는 개체의 속성처럼 보입니다. XAML에는 설정되는 속성이 태그에 명시적으로 지정되지 않은 콘텐츠 속성 개념도 있습니다. 특정 용어 및 XAML 규칙에 대한 자세한 내용은 XAML 개요를 참조하세요.

시각적 트리는 UI 렌더링 프로세스에 내부적으로 사용되지만 시각적 트리의 구조를 아는 것은 컨트롤 템플릿 작성 또는 바꾸기 또는 런타임에 컨트롤의 구조 및 파트 분석과 같은 특정 시나리오에서 중요합니다. 이러한 시나리오의 경우 Windows 런타임 보다 일반화된 방식으로 시각적 트리를 검사할 수 있는 VisualTreeHelper API를 제공합니다. (이론적으로 개체별 부모 및 자식 속성을 사용하여 이러한 트리를 생성할 수도 있지만 각 요소가 지원하는 속성을 정확히 알고 있어야 하며 이를 검색하거나 관리하기가 어렵습니다.)

일반적으로 여러 VisualTreeHelper API 호출을 결합하여 사용자 고유의 앱 시나리오와 관련된 방식으로 시각적 트리를 조사하는 사용자 고유의 도우미 함수를 작성합니다.

시각적 트리 트래버스

개체 트리(구어체로 트리를 걷는 것으로 알려짐)를 트래버스하는 것은 개체 모델에서 일반적인 기술입니다. 자식 개체를 참조하는 속성(일반적으로 컬렉션임) 또는 포함하는 개체에 대한 부모 관계를 사용합니다(일반적으로 컬렉션 내에서 수행되고 컬렉션 자체를 반환). 프로세스에 대한 대략적인 설명으로 자식 속성과 부모 속성 또는 도우미 메서드의 연속을 호출하여 찾고 있던 개체가 포함된 값을 검색할 때까지 개체 트리의 축을 탐색합니다. 일반적으로 트리의 구조를 광범위하게 쿼리할 필요가 없도록 XAML에서 콘텐츠를 생성할 수 있어야 합니다. 트리를 트래버스할 필요가 없도록 하려면 XAML 요소를 만드는 XAML 태그의 x:Name Name / 특성에 대한 값을 XAML 요소에 제공해야 합니다. 이렇게 하면 런타임 코드 액세스에 사용할 수 있는 즉각적인 참조가 생성되며 트리를 걷는 것보다 개체 참조를 가져오는 데 오류가 발생하기 쉬운 기술이 훨씬 적습니다. 또는 XAML이 아닌 코드를 통해 개체를 만드는 경우 런타임에 개체 참조를 유지하는 프라이빗 필드 또는 변수를 선언해야 합니다. 일반적으로 사용자 고유의 코드에서 만든 개체를 찾기 위해 트리를 트래버스할 필요가 없습니다.

그러나 개체에 이름을 지정하고 개체 참조를 scope 유지하는 것이 가능하거나 실용적이지 않은 경우가 있습니다. 이러한 시나리오 중 하나는 사용자가 제공하거나 데이터 바인딩에서 제공하는 동적 콘텐츠를 추가하거나 보기 모델 및 비즈니스 개체를 사용하는 경우입니다. 이러한 경우 추가된 항목 수 또는 컨트롤 및 해당 자식의 구조를 항상 예측할 수 없습니다. 또 다른 시나리오는 컨트롤에 적용된 템플릿 또는 컨트롤 또는 발표자 콘텐츠의 복합 섹션을 검사하는 것입니다.

루트에서 멀리 떨어진 트리를 아래로 트래버스하는 작업은 0이 아닌 값에 대해 GetChildrenCount 를 사용한 다음 GetChild 를 사용하여 특정 인덱스를 요청할 수 있습니다. 요소를 특정 UIElement 하위 형식으로 캐스팅하려는 경우 try/catch 기술 또는 해당 기술을 사용해야 할 수 있습니다. 일반적으로 VisualTreeHelper API는 요소를 DependencyObject 로 반환하며 유용한 작업을 수행하려면( 이름 값 확인과 같은 간단한 작업에도) 캐스팅해야 합니다.

이전 버전에 대한 참고 사항

Windows 8

UI 스레딩

Windows 8 잘못된(현재) UI 스레드에서 개체를 참조하는 VisualTreeHelper 함수 호출이 허용되었습니다. Windows 8.1 함수는 현재 UI 스레드에서 호출되지 않는 경우 예외를 throw합니다. 이 새로운 동작을 고려하면 매우 드문 앱 마이그레이션 시나리오여야 합니다. 처음에는 스레드 간에 UI 요소를 가져오기가 어렵습니다.

Windows 8 위해 컴파일되었지만 Windows 8.1 실행 중인 앱은 Windows 8.1 동작을 사용하며, 스레드 간 개체를 사용하는 다운스트림 앱 코드가 아닌 VisualTreeHelper 함수 호출에서 특별히 throw됩니다.

화상 키보드용 앱 UI

Windows 8 사용자가 화상 키보드를 호출할 때마다 ScrollViewer를 전체 앱 UI와 연결하는 내부적으로 구현된 논리가 있었습니다. 이 화상 키보드는 사용자가 접근성 센터를 통해 요청하는 특정 접근성 기능입니다. 시스템에서 키보드 디바이스를 검색하지 않는 경우 텍스트 입력 컨트롤에 대한 앱 UI에 표시할 수 있는 소프트 키보드와 다릅니다. 여기에서 내부 ScrollViewer 가 수행하는 일은 키보드가 UI 공간을 차지하고 있기 때문에 강제로 스크롤하는 경우 앱이 있는 영역을 스크롤할 수 있도록 하는 것입니다.

Windows 8.1 시작해도 화상 키보드가 나타날 때 시스템에는 여전히 UI/레이아웃 동작이 있지만 더 이상 내부적으로 만든 이 ScrollViewer를 사용하지 않습니다. 대신 앱 코드가 변경하거나 검사할 수 없는 전용 내부 컨트롤을 사용합니다.

이 동작 변경의 대부분의 측면은 앱에 전혀 영향을 주지 않습니다. 그러나 레이아웃을 변경하기 위한 암시적 Style for ScrollViewer 를 제공하거나 VisualTreeHelper를 사용하여 트리를 탐색하여 내부적으로 만든 ScrollViewer 를 찾아 런타임에 변경하여 앱에서 이 동작을 예상했을 수 있습니다. Windows 8.1 위해 컴파일된 앱의 경우 해당 코드는 유용하지 않습니다.

Windows 8용으로 컴파일되었지만 Windows 8.1에서 실행하는 앱은 Windows 8 동작을 계속 사용합니다.

버전 기록

Windows 버전	SDK 버전	추가된 값
1903	18362	GetOpenPopupsForXamlRoot

메서드

DisconnectChildrenRecursive(UIElement)	참조 주기 정리를 목표로 대상 UIElement에서 모든 참조를 명시적으로 제거합니다.
FindElementsInHostCoordinates(Point, UIElement)	앱 UI의 지정된 x-y 좌표점 내에 있는 개체 집합을 검색합니다. 개체 집합은 해당 지점을 공유하는 시각적 트리의 구성 요소를 나타냅니다.
FindElementsInHostCoordinates(Point, UIElement, Boolean)	앱 UI의 지정된 x-y 좌표점 내에 있는 개체 집합을 검색합니다. 개체 집합은 해당 지점을 공유하는 시각적 트리의 구성 요소를 나타냅니다.
FindElementsInHostCoordinates(Rect, UIElement)	앱 UI의 지정된 Rect 프레임 내에 있는 개체 집합을 검색합니다. 개체 집합은 사각형 영역을 공유하는 시각적 트리의 구성 요소를 나타내며, 오버드롤되는 요소를 포함할 수 있습니다.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	앱 UI의 지정된 Rect 프레임 내에 있는 개체 집합을 검색합니다. 개체 집합은 사각형 영역을 공유하는 시각적 트리의 구성 요소를 나타내며, 오버드롤되는 요소를 포함할 수 있습니다.
GetChild(DependencyObject, Int32)	제공된 인덱스를 사용하여 시각적 트리를 검사하여 제공된 개체의 특정 자식 개체를 가져옵니다.
GetChildrenCount(DependencyObject)	시각적 트리에서 개체의 자식 컬렉션에 있는 자식 수를 반환합니다.
GetOpenPopups(Window)	대상 창에서 열려 있는 모든 팝업 컨트롤의 컬렉션을 검색합니다.
GetOpenPopupsForXamlRoot(XamlRoot)	대상 XamlRoot에서 열려 있는 모든 팝업 컨트롤의 컬렉션을 검색합니다.
GetParent(DependencyObject)	시각적 트리에서 개체의 부모 개체를 반환합니다.

적용 대상