FrameworkElement.FindName(String) Método

Definição

Namespace:

Windows.UI.Xaml

Recupera um objeto que tem o nome do identificador especificado.

public:
 virtual Platform::Object ^ FindName(Platform::String ^ name) = FindName;

IInspectable FindName(winrt::hstring const& name);

public object FindName(string name);

function findName(name)

Public Function FindName (name As String) As Object

Parâmetros

name

String

Platform::String

winrt::hstring

O nome do objeto solicitado.

Retornos

Object

Platform::Object

IInspectable

O objeto solicitado. Isso poderá ser nulo se nenhum objeto correspondente for encontrado no namescope XAML atual.

Comentários

Importante

Para usar o método FindName com eficiência, você deve entender o conceito de um namescope XAML e como um namescope XAML é criado no tempo de carregamento XAML e, em seguida, referenciado e possivelmente modificado em tempo de execução. Para obter mais informações, consulte Namescopes XAML.

O uso mais comum de FindName em seu código Windows Runtime será de dentro da chamada InitializeComponent gerada para uma página XAML. Nessa situação, FindName é invocado somente depois que a página XAML é carregada. InitializeComponent fornece a infraestrutura de modo que qualquer objeto que tenha sido instanciado pelo carregamento XAML possa ser acessado convenientemente pelo código code-behind. Em seguida, você pode referenciar os objetos como uma variável que compartilha o mesmo nome que o atributo x:Name declarado por marcação.

Uma API em tempo de execução, como FindName, está funcionando em uma árvore de objetos em tempo de execução do aplicativo como ela existe na memória. Quando parte dessa árvore de objetos é criada a partir de modelos ou XAML carregado em tempo de execução, um namescope XAML normalmente não é contíguo dentro dessa árvore de objetos. O resultado é que pode haver um objeto nomeado na árvore de objetos que um determinado escopo FindName não pode encontrar. As descontinuidades entre namescopes XAML que você pode encontrar em cenários de aplicativo típicos são quando objetos são criados aplicando um modelo ou quando objetos são criados por uma chamada para XamlReader.Load e, posteriormente, adicionados à árvore de objetos.

Se você retornar um resultado nulo inesperado para FindName, experimente estas técnicas:

• Para objetos nomeados provenientes de um modelo, se você estiver definindo ou derivando de um controle, poderá chamar GetTemplateChild do escopo do objeto em que o modelo é aplicado. Você deve estar em um escopo de definição de classe derivada para usar GetTemplateChild, pois ele é um método protegido de Control.
• Se você não estiver em um escopo de definição de classe derivada, poderá inserir a árvore visual de um modelo usando VisualTreeHelper em um ponto no tempo de vida do objeto após a aplicação do modelo (manipular o evento Loaded ). O VisualTreeHelper usa uma metáfora pai-filho para percorrer a árvore, em vez de usar o conceito de namescope XAML. Andar na árvore geralmente requer um conhecimento específico da composição do controle, pois ela vem de um determinado modelo. Você pode usar VisualTreeHelper.GetChild no controle para obter a raiz de modelo aplicada do controle e chamar FindName especificamente na raiz do modelo para acessar elementos que são nomeados dentro do modelo XAML.
• Para o caso XamlReader.Load , você deve preservar uma referência ao valor retornado da chamada XamlReader.Load , que é um objeto que se tornará o proprietário ou a base do namescope XAML criado que é relevante. Em seguida, chame FindName desse escopo.

O objeto retornado por FindName não é necessariamente um FrameworkElement. Por exemplo, você pode aplicar um nome a um storyboard de animação e os vários tipos de storyboard de animação não derivam de FrameworkElement.

A propriedade Name de um objeto (ou o atributo x:Name semelhante) é atribuída especificando um atributo em um elemento de objeto na marcação XAML. Você pode definir um valor Name depois que o XAML de origem inicial for carregado, mas essa técnica tem algumas limitações (consulte Comentários em Nome).

TextElement define um FindName semelhante. Isso habilita um comportamento FindName no modelo de objeto, que não se limita a FrameworkElement. As chamadas feitas por qualquer implementação de FindName podem atravessar para uma árvore de objeto de elemento de texto/ FrameworkElement mista e usar um namescope XAML comum para que uma chamada FrameworkElement.FindName possa encontrar um elemento de texto nomeado e vice-versa.

Os valores de nome adicionados ou alterados em tempo de execução na árvore de objetos serão atualizados para o namescope XAML em ação nesse nível na árvore de objetos. Em outras palavras, se você criar um novo FrameworkElement, dê a ele um Nome e, em seguida, adicione-o à árvore de objetos, chamando FindName de dentro desse namescope XAML pode localizar e retornar o objeto criado pelo código.

Confira também

• Name
• Namescopes XAML
• Atributo x:Name