VisualTreeHelper Klasse

Definition

public ref class VisualTreeHelper sealed

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 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(Microsoft.UI.Xaml.WinUIContract), 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

Beispiele

Hier ist ein Beispiel für eine Hilfsfunktion, die eine Liste untergeordneter Elemente eines bestimmten Typs aus einer visuellen Struktur kopieren kann. Es verwendet die grundlegenden Traversalmethoden GetChildrenCount und GetChild. Es verwendet Rekursion, damit Elemente unabhängig davon gefunden werden können, welche Schachtelungsebene in Zwischencontainern vorhanden ist. 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, die Suche nach Objekten, die Sie in der Laufzeitstruktur von Objekten suchen, zu unterstützen, aber es ist keine direkte Objektbeziehungs-API für Ihr Szenario verfügbar. Manchmal kennen Sie nicht den genauen Typ oder Namen des Objekts. Oder vielleicht wissen Sie, dass ein bestimmtes Objekt irgendwo in der Struktur angezeigt wird, aber Sie wissen nicht die genaue Position. Für diese Arten von Szenarien ist VisualTreeHelper hilfreich, da Sie alle Objekte in der visuellen Struktur rekursiv finden und dann anhand Ihrer 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. Nur die Objekte mit einer Renderimplation sind in einer visuellen Struktur vorhanden. Beispielsweise wäre eine Sammlungsklasse nicht Teil der visuellen Struktur. Stattdessen abstrahiert die visuelle Struktur jede Sammlung in ein "children"-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, bei der es sich in der Regel um XAML aus einem Ressourcenwörterbuchelement oder aus einem Referenten handelt.

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

Die visuelle Struktur wird intern für den Ui-Renderingprozess verwendet, aber das Wissen 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. In diesen Szenarien stellt die Windows-Runtime die VisualTreeHelper-API bereit, die die visuelle Struktur auf allgemeinere Weise untersuchen kann. (Sie könnten theoretisch eine solche Struktur mit objektspezifischen übergeordneten und untergeordneten Eigenschaften erstellen, aber Sie müssten genau wissen, welche Eigenschaften jedes Element unterstützt, und das ist schwierig zu erkennen oder zu verwalten.)

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

Durchlaufen einer visuellen Struktur

Das Durchlaufen der Objektstruktur (manchmal auch bekannt als Durchlaufen der Struktur) ist eine gängige Technik in Objektmodellen. Sie verwenden Eigenschaften, die entweder auf untergeordnete Objekte verweisen (in der Regel auflistungen) oder übergeordnete Beziehungen zu einem enthaltenden Objekt (in der Regel erfolgt dies innerhalb einer Auflistung und gibt die Auflistung selbst zurück). Als grobe Beschreibung des Prozesses rufen Sie eine Abfolge von untergeordneten Eigenschaften und übergeordneten Eigenschaften oder vielleicht Hilfsmethoden auf, um in den Achsen der Objektstruktur zu navigieren, bis Sie einen Wert abrufen, der das gesuchte Objekt enthält. Im Allgemeinen sollten Sie in der Lage sein, Ihren Inhalt in XAML so zu erstellen, dass Sie die Struktur der Struktur der Struktur nicht umfassend abfragen müssen. Um zu vermeiden, dass die Struktur durchlaufen werden muss, sollten Sie XAML-Elementen einen Wert für das x:Name-Attribut / im XAML-Markup zuweisen, das sie erstellt. Dadurch wird ein sofortiger Verweis erstellt, der für den Laufzeitcodezugriff verfügbar ist. Dies ist eine wesentlich weniger fehleranfällige Technik zum Abrufen von Objektverweise als das Durchlaufen der Struktur. Wenn Sie Objekte auch über Code und nicht über XAML erstellen, sollten Sie private Felder oder Variablen deklarieren, die den Objektverweis zur Laufzeit beibehalten. Normalerweise ist es nicht erforderlich, die Struktur zu durchlaufen, um Objekte zu finden, die in Ihrem eigenen Code erstellt werden.

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 weiteres 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) mit mehreren Ebenen kann mithilfe von GetChildrenCount für Nichtzero-Werte und dann getChild erfolgen, um einen bestimmten Index anzufordern. Möglicherweise müssen Sie try/catch-Techniken oder das entsprechende Verfahren verwenden, wenn Sie Versuchen, Elemente als bestimmte UIElement-Untertypen zu umwandeln. Im Allgemeinen geben die VisualTreeHelper-API Elemente als DependencyObject zurück, und Sie müssen sie umwandeln, um alles Nützliche zu tun (auch für so einfache Vorgänge wie die Überprüfung des Namenswerts ).

Weitere Informationen

• XAML-Steuerelementvorlagen
• XAML-NameScopes