VisualTreeHelper Klasse

Definition

Namespace:

Windows.UI.Xaml.Media

Stellt Hilfsprogrammmethoden bereit, die zum Durchlaufen von Objektbeziehungen (entlang der Achsen untergeordneter Objekte oder übergeordneter Objekte) in der visuellen Struktur Ihrer App verwendet werden können.

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

Vererbung

Object Platform::Object IInspectable VisualTreeHelper

Attribute

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows-Anforderungen

Gerätefamilie	Windows 10 (eingeführt in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (eingeführt in v1.0)

Beispiele

Hier sehen Sie ein Beispiel für eine Hilfsprogrammfunktion, die eine Liste mit untergeordneten Elementen eines bestimmten Typs aus einer visuellen Struktur kopieren kann. Es verwendet die grundlegenden Traversalmethoden GetChildrenCount und GetChild. Es verwendet Rekursion, damit Elemente unabhängig von der Ebene der Schachtelung in Zwischencontainern gefunden werden können. Außerdem wird eine IsSubclassOf-Erweiterungsmethode von System.Reflection verwendet, die den Typvergleich erweitert, um Untertypen als Übereinstimmung für einen Typ zu betrachten.

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);
    }
}

Hinweise

Die visuelle Struktur

Der Zweck der VisualTreeHelper-Klasse besteht darin, bei der Ermittlung von Objekten zu helfen, nach denen Sie in der Laufzeitstruktur von Objekten suchen, aber es ist keine direktere Objektbeziehungs-API für Ihr Szenario verfügbar. Manchmal kennen Sie den genauen Typ oder Namen des Objekts nicht. Oder vielleicht wissen Sie, dass ein bestimmtes Objekt irgendwo in der Struktur angezeigt wird, Aber Sie wissen nicht, wo genau sie steht. Für diese Arten von Szenarien ist VisualTreeHelper hilfreich, da Sie alle Objekte in der visuellen Struktur rekursiv finden und dann diesen Satz durchsuchen und basierend auf Ihren Kriterien nach einer Übereinstimmung suchen können.

Die visuelle Struktur für eine App kann als gefilterte Darstellung der größeren Objektstruktur der Objekte und Eigenschaften einer App konzipiert werden. In einer visuellen Struktur sind nur die Objekte vorhanden, die eine Renderingimplication aufweisen. Beispielsweise wäre eine Auflistungsklasse nicht Teil der visuellen Struktur. Stattdessen abstrahiert die visuelle Struktur jede Sammlung zu einem "untergeordneten" Konzept.

Die visuelle Struktur kann jedoch auch Objekte enthalten, die nicht als XAML-Elemente im XAML-Markup einer Seite dargestellt werden. Dies liegt daran, dass die visuelle Struktur Objekte hinzufügt, die die zusammengesetzten Teile von Steuerelementen sind. Diese Steuerelementteile können aus einer angewendeten Steuerelementvorlage stammen, die in der Regel XAML aus einem Ressourcenwörterbuchelement ist, oder von einem Referenten.

XAML-Markup und eine visuelle Struktur stimmen nicht genau mit node-for-node überein, da XAML für Markup konzipiert ist und während der Markupdefinition einfach zu verwenden ist, sodass es manchmal zusätzliche Elemente enthält. XAML verfügt beispielsweise über Eigenschaftselemente, die Eigenschaftswerte festlegen, wenn ein Element geschachtelt in einem anderen gefunden wird. In einer visuellen Struktur würde dies nur wie eine Eigenschaft für ein Objekt aussehen, das von einem anderen Objekt festgelegt wird. XAML hat auch das Konzept einer Inhaltseigenschaft, bei der die festgelegte Eigenschaft nicht explizit im Markup festgelegt ist. Weitere Informationen zur spezifischen Terminologie und zu den Regeln für XAML finden Sie unter XAML-Übersicht.

Die visuelle Struktur wird intern für den Ui-Renderingprozess verwendet, aber die Kenntnis der Struktur der visuellen Struktur ist für bestimmte Szenarien wichtig, z. B. das Schreiben oder Ersetzen einer Steuerelementvorlage oder die Analyse der Struktur und Teile eines Steuerelements zur Laufzeit. Für diese Szenarien stellt der Windows-Runtime die VisualTreeHelper-API bereit, mit der die visuelle Struktur generalisiert untersucht werden kann. (Theoretisch könnten Sie eine solche Struktur auch mithilfe objektspezifischer übergeordneter und untergeordneter Eigenschaften erstellen, aber Sie müssten genau wissen, welche Eigenschaften jedes Element unterstützt, und das ist schwer zu ermitteln oder zu verwalten.)

Sie kombinieren in der Regel mehrere VisualTreeHelper-API-Aufrufe, um Ihre eigenen Hilfsfunktionen zu schreiben, die die visuelle Struktur auf spezifisch für die Szenarien Ihrer eigenen App untersuchen.

Durchlaufen einer visuellen Struktur

Das Durchlaufen der Objektstruktur (manchmal umgangssprachlich als Durchlaufen der Struktur bezeichnet) ist eine gängige Technik in Objektmodellen. Sie verwenden Eigenschaften, die entweder auf untergeordnete Objekte (in der Regel sind dies Auflistungen) oder übergeordnete Beziehungen zu einem enthaltenden Objekt verweisen (in der Regel erfolgt dies innerhalb einer Auflistung und gibt die Auflistung selbst zurück). Als grobe Beschreibung des Prozesses rufen Sie eine Abfolge untergeordneter Eigenschaften und übergeordneter Eigenschaften oder vielleicht Hilfsmethoden auf, um in den Achsen der Objektstruktur zu navigieren, bis Sie einen Wert abrufen, der das gesuchte Objekt enthält. In der Regel sollten Sie In der Lage sein, Ihre Inhalte in XAML so zu erstellen, dass Sie die Struktur der Struktur der Struktur nicht ausführlich abfragen müssen. Damit die Struktur nicht durchlaufen werden muss, sollten Sie XAML-Elementen einen Wert für das x:Name / Name-Attribut im XAML-Markup zuweisen, von dem sie erstellt werden. Dadurch wird ein sofortiger Verweis erstellt, der für den Codezugriff zur Laufzeit verfügbar ist, und dies ist eine viel weniger fehleranfällige Technik zum Abrufen von Objektverweise als das Durchlaufen der Struktur. Wenn Sie Objekte anstelle von XAML mithilfe von Code erstellen, sollten Sie alternativ private Felder oder Variablen deklarieren, die den Objektverweis zur Laufzeit beibehalten. Es ist in der Regel nicht erforderlich, die Struktur zu durchlaufen, um Objekte zu finden, die in Ihrem eigenen Code erstellt wurden.

Es gibt jedoch Fälle, in denen es nicht möglich oder praktisch ist, einem Objekt einen Namen zu geben und einen Objektverweis im Bereich beizubehalten. Ein solches Szenario ist, wenn Sie dynamische Inhalte hinzufügen, die vom Benutzer bereitgestellt oder durch Datenbindung bereitgestellt werden, oder wenn Sie Ansichtsmodelle und Geschäftsobjekte verwenden. In diesen Fällen können Sie nicht immer die Anzahl der hinzugefügten Elemente oder die Struktur eines Steuerelements und seiner untergeordneten Elemente vorhersagen. Ein anderes Szenario besteht darin, eine angewendete Vorlage für ein Steuerelement oder einen zusammengesetzten Abschnitt eines Steuerelements oder Referenteninhalts zu untersuchen.

Das Durchlaufen der Struktur nach unten (weg vom Stamm) auf mehreren Ebenen kann mithilfe von GetChildrenCount für nichtzero-Werte und dann mit GetChild erfolgen, um einen bestimmten Index anzufordern. Möglicherweise müssen Sie try/catch-Techniken oder die entsprechende Methode verwenden, wenn Sie Elemente als bestimmte UIElement-Untertypen umwandeln möchten. Im Allgemeinen gibt die VisualTreeHelper-API Elemente als DependencyObject zurück, und Sie müssen es umwandeln, um etwas Nützliches zu tun (auch für einen so einfachen Vorgang wie das Überprüfen des Namenswerts ).

Hinweise zu früheren Versionen

Windows 8

Ui-Threading

Windows 8 zulässige VisualTreeHelper-Funktionsaufrufe, die auf Objekte im falschen (nicht dem aktuellen) UI-Thread verweisen. Ab Windows 8.1 löst die Funktion eine Ausnahme aus, wenn sie nicht vom aktuellen UI-Thread aufgerufen wird. Die Berücksichtigung dieses neuen Verhaltens sollte ein sehr ungewöhnliches Anwendungsmigrationsszenario sein. Es ist überhaupt schwierig, Benutzeroberflächenelemente über Threads hinweg zu erhalten.

Apps, die für Windows 8 kompiliert wurden, aber auf Windows 8.1 ausgeführt werden, verwenden das Windows 8.1 Verhalten und lösen speziell für den VisualTreeHelper-Funktionsaufruf und nicht für nachgeschalteten App-Code aus, der ein threadübergreifendes Objekt verwendet.

App-Benutzeroberfläche für Bildschirmtastatur

Windows 8 eine intern implementierte Logik, die einen ScrollViewer der gesamten App-Benutzeroberfläche zuordnen würde, wenn der Benutzer die Bildschirmtastatur aufruft. Diese Bildschirmtastatur ist ein bestimmtes Barrierefreiheitsfeature, das Benutzer über das Center für erleichterte Bedienung anfordern. Sie ist nicht identisch mit der soften Tastatur, die in der App-Benutzeroberfläche für Texteingabesteuerelemente angezeigt werden kann, wenn das System kein Tastaturgerät erkennt. Der interne ScrollViewer ermöglicht hier das Scrollen des Bereichs, in dem sich die App befindet, wenn das Scrollen erzwungen wird, da die Tastatur Speicherplatz für die Benutzeroberfläche belegt.

Ab Windows 8.1 weist das System weiterhin Benutzeroberflächen-/Layoutverhalten auf, wenn die Bildschirmtastatur angezeigt wird, aber es verwendet diesen intern erstellten ScrollViewer nicht mehr. Stattdessen wird ein dediziertes internes Steuerelement verwendet, das App-Code nicht ändern oder überprüfen kann.

Die meisten Aspekte dieser Verhaltensänderung wirken sich überhaupt nicht auf Apps aus. Möglicherweise hat Ihre App dieses Verhalten jedoch vorhergesehen, indem sie einen impliziten Stil für ScrollViewer bereitstellt, der das Layout ändern soll, oder indem Sie die Struktur mit VisualTreeHelper durchlaufen, um diesen intern erstellten ScrollViewer zu finden und zur Laufzeit zu ändern. Für eine App, die für Windows 8.1 kompiliert wird, ist dieser Code nicht nützlich.

Apps, die für Windows 8 kompiliert wurden, aber unter Windows 8.1 ausgeführt werden, weisen weiterhin das Windows 8-Verhalten auf.

Versionsverlauf

Windows-Version	SDK-Version	Wertschöpfung
1903	18362	GetOpenPopupsForXamlRoot

Methoden

DisconnectChildrenRecursive(UIElement)	Entfernt explizit alle Verweise aus einem UIElement-Ziel, mit dem Ziel, Verweiszyklen zu bereinigen.
FindElementsInHostCoordinates(Point, UIElement)	Ruft eine Gruppe von Objekten ab, die sich innerhalb eines angegebenen x-y-Koordinatenpunkts einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die diesen Punkt gemeinsam nutzen.
FindElementsInHostCoordinates(Point, UIElement, Boolean)	Ruft eine Gruppe von Objekten ab, die sich innerhalb eines angegebenen x-y-Koordinatenpunkts einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die diesen Punkt gemeinsam nutzen.
FindElementsInHostCoordinates(Rect, UIElement)	Ruft eine Gruppe von Objekten ab, die sich in einem angegebenen Rect-Frame einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die einen rechteckigen Bereich gemeinsam nutzen, und kann Elemente enthalten, die überzeichnet werden.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	Ruft eine Gruppe von Objekten ab, die sich in einem angegebenen Rect-Frame einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die einen rechteckigen Bereich gemeinsam nutzen, und kann Elemente enthalten, die überzeichnet werden.
GetChild(DependencyObject, Int32)	Ruft mithilfe des bereitgestellten Indexes ein bestimmtes untergeordnetes Objekt des bereitgestellten Objekts ab, indem die visuelle Struktur untersucht wird.
GetChildrenCount(DependencyObject)	Gibt die Anzahl der untergeordneten Elemente zurück, die in der untergeordneten Auflistung eines Objekts in der visuellen Struktur vorhanden sind.
GetOpenPopups(Window)	Ruft eine Auflistung aller geöffneten Popupsteuerelemente aus dem Zielfenster ab.
GetOpenPopupsForXamlRoot(XamlRoot)	Ruft eine Auflistung aller geöffneten Popupsteuerelemente aus dem XamlRoot-Ziel ab.
GetParent(DependencyObject)	Gibt das übergeordnete Objekt eines Objekts in der visuellen Struktur zurück.

Weitere Informationen

• Schnellstart: Steuerelementvorlagen
• XAML-Namescopes
• Steuerelemente nach Funktion