VisualTreeHelper Classe

Definizione

Spazio dei nomi:

Microsoft.UI.Xaml.Media

Fornisce metodi di utilità che possono essere usati per attraversare le relazioni tra oggetti (lungo assi figlio o oggetti padre) nell'albero visivo dell'app.

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

Ereditarietà

Object Platform::Object IInspectable VisualTreeHelper

Attributi

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Esempio

Ecco un esempio di funzione di utilità che può copiare un elenco di elementi figlio di un determinato tipo dall'interno di un albero visivo. Usa i metodi di attraversamento di base GetChildrenCount e GetChild. Usa la ricorsione in modo che gli elementi possano essere trovati indipendentemente dal livello di annidamento all'interno di contenitori intermedi. Usa anche un metodo di estensione IsSubclassOf da System.Reflection che estende il confronto dei tipi per considerare i sottotipi come corrispondenza per un tipo.

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

Commenti

Albero visivo

Lo scopo della classe VisualTreeHelper consiste nell'individuare gli oggetti da cercare nell'albero di runtime di oggetti, ma non è disponibile un'API più diretta per la relazione con oggetti. A volte, non si conoscerà il tipo o il nome esatto dell'oggetto. O forse si sa che un oggetto specifico viene visualizzato da qualche parte nell'albero, ma non si conosce la posizione esatta. Per questi tipi di scenari, VisualTreeHelper è utile perché è possibile trovare in modo ricorsivo tutti gli oggetti nell'albero visivo e quindi esaminare questo set e cercare una corrispondenza in base ai criteri.

L'albero visivo per un'app può essere concettualizzato come rappresentazione filtrata dell'albero a oggetti più grande di oggetti e proprietà di un'app. Solo gli oggetti che hanno una implicazione per il rendering sono presenti in un albero visivo. Ad esempio, una classe di raccolta non fa parte dell'albero visivo. L'albero visivo astrae invece qualsiasi raccolta in un concetto di "figlio".

Tuttavia, l'albero visivo può includere anche oggetti che non sono rappresentati come elementi XAML nel markup XAML di una pagina. Ciò avviee perché l'albero visivo aggiunge oggetti che sono le parti composite dei controlli. Queste parti di controllo possono venire da un modello di controllo applicato, che è in genere XAML da un elemento del dizionario risorse o da un relatore.

Il markup XAML e un albero visivo non corrispondono esattamente a node-for-node perché XAML è progettato per il markup e la facilità d'uso durante la definizione di markup, quindi a volte ha elementi aggiuntivi. Ad esempio, XAML ha elementi di proprietà, che imposta i valori delle proprietà se viene trovato un elemento annidato all'interno di un altro. In un albero visivo, si tratta solo di una proprietà su un oggetto impostato da un altro oggetto. XAML include anche un concetto di proprietà del contenuto, in cui la proprietà impostata non è designata in modo esplicito nel markup. Per altre informazioni sulla terminologia specifica e sulle regole per XAML, vedere Panoramica xaml.

L'albero visivo viene usato internamente per il processo di rendering dell'interfaccia utente, ma la conoscenza della struttura dell'albero visivo è importante per determinati scenari, ad esempio la scrittura o la sostituzione di un modello di controllo o l'analisi della struttura e delle parti di un controllo in fase di esecuzione. Per questi scenari, la Windows Runtime fornisce l'API VisualTreeHelper che può esaminare l'albero visivo in modo più generalizzato. È possibile costruire un albero di questo tipo usando anche proprietà padre e figlio specifiche dell'oggetto, ma è necessario conoscere esattamente le proprietà supportate da ogni elemento e che è difficile da individuare o gestire.

In genere si combinano diverse chiamate API di VisualTreeHelper per scrivere funzioni helper personalizzate che analizzano l'albero visivo in modi specifici per gli scenari dell'app.

Attraversamento di un albero visivo

L'attraversamento dell'albero degli oggetti (talvolta noto come camminare l'albero) è una tecnica comune nei modelli a oggetti. Si usano proprietà che fanno riferimento a oggetti figlio (in genere queste sono raccolte) o relazioni padre a un oggetto contenente (in genere questa operazione viene eseguita dall'interno di una raccolta e restituisce la raccolta stessa). Come descrizione approssimativa del processo, si chiama una successione di proprietà figlio e proprietà padre, o forse metodi helper, per esplorare gli assi dell'albero degli oggetti finché non si recupera un valore che contiene l'oggetto da cercare. Come regola generale, è necessario poter costruire il contenuto in XAML in modo che non sia necessario eseguire query sulla struttura dell'albero in modo esteso. Per evitare la necessità di attraversare l'albero, è necessario assegnare agli elementi XAML un valore per l'attributo x:Name / Name nel markup XAML che li crea. In questo modo viene creato un riferimento immediato disponibile per l'accesso al codice in fase di esecuzione e questa è una tecnica molto meno soggetta a errori per ottenere riferimenti a oggetti rispetto alla passeggiata dell'albero. In alternativa, se si creano oggetti tramite codice anziché XAML, è necessario dichiarare campi privati o variabili che mantengono riferimento all'oggetto in fase di esecuzione. In genere non è necessario attraversare l'albero per trovare oggetti creati nel proprio codice.

Tuttavia, esistono casi in cui non è possibile o pratico assegnare un nome a un oggetto e mantenere un riferimento all'oggetto nell'ambito. Uno di questi scenari è se si aggiunge contenuto dinamico fornito dall'utente o fornito dall'associazione dati o usando modelli di visualizzazione e oggetti business. In questi casi non è sempre possibile stimare il numero di elementi aggiunti o la struttura di un controllo e dei relativi elementi figlio. Un altro scenario esamina un modello applicato per un controllo o una sezione composita di un controllo o contenuto del relatore.

È possibile attraversare l'albero verso il basso (lontano dalla radice) più livelli usando GetChildrenCount per i valori non zero e quindi GetChild per richiedere un indice specifico. Potrebbe essere necessario usare tecniche try/catch o l'equivalente se si sta tentando di eseguire il cast di elementi come sottotipi UIElement specifici. In genere l'API VisualTreeHelper restituisce elementi come DependencyObject e sarà necessario eseguirne il cast per eseguire qualsiasi operazione utile (anche per un'operazione semplice come controllo del relativo valore nome ).

Metodi

DisconnectChildrenRecursive(UIElement)	Rimuove in modo esplicito tutti i riferimenti da un UIElement di destinazione, con l'obiettivo di pulire i cicli di riferimento.
FindElementsInHostCoordinates(Point, UIElement)	Recupera un set di oggetti che si trovano all'interno di un punto di coordinata x-y specificato di un'interfaccia utente dell'app. Il set di oggetti rappresenta i componenti di un albero visivo che condivide tale punto.
FindElementsInHostCoordinates(Point, UIElement, Boolean)	Recupera un set di oggetti che si trovano all'interno di un punto di coordinata x-y specificato di un'interfaccia utente dell'app. Il set di oggetti rappresenta i componenti di un albero visivo che condivide tale punto.
FindElementsInHostCoordinates(Rect, UIElement)	Recupera un set di oggetti che si trovano all'interno di un frame Rect specificato di un'interfaccia utente dell'app. Il set di oggetti rappresenta i componenti di un albero visivo che condivide un'area rettangolare e può includere elementi che si sovrascludono.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	Recupera un set di oggetti che si trovano all'interno di un frame Rect specificato di un'interfaccia utente dell'app. Il set di oggetti rappresenta i componenti di un albero visivo che condivide un'area rettangolare e può includere elementi che si sovrascludono.
GetChild(DependencyObject, Int32)	Usando l'indice specificato, ottiene un oggetto figlio specifico dell'oggetto fornito esaminando l'albero visivo.
GetChildrenCount(DependencyObject)	Restituisce il numero di elementi figlio presenti nell'insieme figlio di un oggetto nell'albero visivo.
GetOpenPopups(Window)	Recupera una raccolta di tutti i controlli popup aperti dalla finestra di destinazione.
GetOpenPopupsForXamlRoot(XamlRoot)	Recupera una raccolta di tutti i controlli popup aperti da XamlRoot di destinazione.
GetParent(DependencyObject)	Restituisce l'oggetto padre di un oggetto nell'albero visivo.

Vedi anche

• Modelli di controllo XAML
• Ambiti dei nomi XAML