VisualTreeHelper Classe

Definição

Namespace:

Microsoft.UI.Xaml.Media

Fornece métodos utilitários que podem ser usados para percorrer relações de objeto (ao longo de eixos filho-objeto ou objeto pai) na árvore visual do seu aplicativo.

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

Herança

Object Platform::Object IInspectable VisualTreeHelper

Atributos

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Exemplos

Aqui está um exemplo de uma função de utilitário que pode copiar uma lista de elementos filho de um tipo específico de dentro de uma árvore visual. Ele usa os métodos básicos de passagem GetChildrenCount e GetChild. Ele usa recursão para que os elementos possam ser encontrados independentemente do nível de aninhamento em contêineres intermediários. Ele também usa um método de extensão IsSubclassOf de System.Reflection que estende a comparação de tipos para considerar subtipos como uma correspondência para um 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);
    }
}

Comentários

A árvore visual

A finalidade da classe VisualTreeHelper é ajudar na descoberta de objetos que você está procurando na árvore de runtime de objetos, mas não há uma API de relação de objeto mais direta disponível para seu cenário. Às vezes, você não saberá o tipo ou o nome exato do objeto. Ou talvez você saiba que um objeto específico aparece em algum lugar na árvore, mas você não sabe a posição exata. Para esses tipos de cenários, o VisualTreeHelper é útil porque você pode encontrar recursivamente todos os objetos na árvore visual e, em seguida, examinar esse conjunto e procurar uma correspondência com base em seus critérios.

A árvore visual de um aplicativo pode ser conceitualizada como uma representação filtrada da árvore de objetos maior dos objetos e propriedades de um aplicativo. Somente os objetos que têm uma implicação de renderização estão presentes em uma árvore visual. Por exemplo, uma classe de coleção não faria parte da árvore visual. Em vez disso, a árvore visual abstrai qualquer coleção em um conceito "filhos".

No entanto, a árvore visual também pode incluir objetos que não são representados como elementos XAML na marcação XAML de uma página. Isso ocorre porque a árvore visual adiciona objetos que são as partes compostas de controles. Essas partes de controle podem vir de um modelo de controle aplicado, que geralmente é XAML de um item de dicionário de recursos ou de um apresentador.

A marcação XAML e uma árvore visual não correspondem exatamente ao nó para nó porque o XAML foi projetado para marcação e facilidade de uso durante a definição de marcação, portanto, às vezes tem elementos extras. Por exemplo, XAML tem elementos de propriedade, que define valores de propriedade se um elemento for encontrado aninhado dentro de outro. Em uma árvore visual, isso se pareceria apenas com uma propriedade em um objeto que está sendo definido por outro objeto. O XAML também tem um conceito de uma propriedade de conteúdo, em que a propriedade que está sendo definida não é explicitamente designada na marcação. Para obter mais informações sobre a terminologia específica e as regras para XAML, consulte Visão geral de XAML.

A árvore visual é usada internamente para o processo de renderização da interface do usuário, mas conhecer a estrutura da árvore visual é importante para determinados cenários, como gravar ou substituir um modelo de controle ou análise da estrutura e das partes de um controle em tempo de execução. Para esses cenários, o Windows Runtime fornece a API VisualTreeHelper que pode examinar a árvore visual de maneira mais generalizada. (Teoricamente, você poderia construir essa árvore usando propriedades pai e filhos específicas do objeto também, mas teria que saber exatamente quais propriedades cada elemento tinha suporte e isso é difícil de descobrir ou gerenciar.)

Normalmente, você combina várias chamadas à API do VisualTreeHelper para escrever suas próprias funções auxiliares que investigam a árvore visual de maneiras específicas para os cenários do seu próprio aplicativo.

Atravessando uma árvore visual

Atravessar a árvore de objetos (às vezes conhecida coloquialmente como andar na árvore) é uma técnica comum em modelos de objeto. Você usa propriedades que fazem referência a objetos filho (normalmente são coleções) ou relações pai a um objeto que contém (geralmente isso é feito de dentro de uma coleção e retorna a própria coleção). Como uma descrição aproximada do processo, você chama uma sucessão de propriedades filho e propriedades pai, ou talvez métodos auxiliares, para navegar pelos eixos da árvore de objetos até recuperar um valor que contém o objeto que você estava procurando. Como regra geral, você deve ser capaz de construir seu conteúdo em XAML de modo que não precise consultar extensivamente a estrutura da árvore. Para evitar a necessidade de percorrer a árvore, você deve dar aos elementos XAML um valor para o atributo x:Name / Name na marcação XAML que os cria. Isso cria uma referência imediata que está disponível para acesso ao código em tempo de execução e essa é uma técnica muito menos propensa a erros para obter referências de objeto do que andar na árvore. Como alternativa, se você estiver criando objetos por meio de código em vez de XAML, deverá declarar campos privados ou variáveis que retêm a referência de objeto em tempo de execução. Normalmente, não é necessário percorrer a árvore para localizar objetos criados em seu próprio código.

No entanto, há casos em que não é possível ou prático dar um nome a um objeto e manter uma referência de objeto no escopo. Um desses cenários é se você estiver adicionando conteúdo dinâmico fornecido pelo usuário ou fornecido pela associação de dados ou usando modelos de exibição e objetos de negócios. Nesses casos, você nem sempre pode prever o número de itens adicionados ou a estrutura de um controle e seus filhos. Outro cenário é examinar um modelo aplicado para um controle ou uma seção composta de um controle ou conteúdo do apresentador.

A passagem da árvore para baixo (longe da raiz) pode ser feita usando GetChildrenCount para valores diferentes de zero e, em seguida, GetChild para solicitar um índice específico. Talvez seja necessário usar técnicas try/catch ou o equivalente se estiver tentando converter elementos como subtipos UIElement específicos. Geralmente, a API VisualTreeHelper retorna elementos como um DependencyObject e você precisará convertê-lo para fazer qualquer coisa útil (mesmo para uma operação tão simples quanto verificar seu valor de Nome ).

Métodos

DisconnectChildrenRecursive(UIElement)	Remove explicitamente todas as referências de um UIElement de destino, com o objetivo de limpar ciclos de referência.
FindElementsInHostCoordinates(Point, UIElement)	Recupera um conjunto de objetos localizados em um ponto de coordenada x-y especificado de uma interface do usuário do aplicativo. O conjunto de objetos representa os componentes de uma árvore visual que compartilham esse ponto.
FindElementsInHostCoordinates(Point, UIElement, Boolean)	Recupera um conjunto de objetos localizados em um ponto de coordenada x-y especificado de uma interface do usuário do aplicativo. O conjunto de objetos representa os componentes de uma árvore visual que compartilham esse ponto.
FindElementsInHostCoordinates(Rect, UIElement)	Recupera um conjunto de objetos que estão localizados em um quadro Rect especificado de uma interface do usuário do aplicativo. O conjunto de objetos representa os componentes de uma árvore visual que compartilham uma área retangular e podem incluir elementos que se sobressaem.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	Recupera um conjunto de objetos que estão localizados em um quadro Rect especificado de uma interface do usuário do aplicativo. O conjunto de objetos representa os componentes de uma árvore visual que compartilham uma área retangular e podem incluir elementos que se sobressaem.
GetChild(DependencyObject, Int32)	Usando o índice fornecido, obtém um objeto filho específico do objeto fornecido examinando a árvore visual.
GetChildrenCount(DependencyObject)	Retorna o número de filhos que existem na coleção filho de um objeto na árvore visual.
GetOpenPopups(Window)	Recupera uma coleção de todos os controles pop-up abertos da Janela de destino.
GetOpenPopupsForXamlRoot(XamlRoot)	Recupera uma coleção de todos os controles pop-up abertos do XamlRoot de destino.
GetParent(DependencyObject)	Retorna o objeto pai de um objeto na árvore visual.

Confira também

• Modelos de controle XAML
• Namescopes XAML