Atributo x:Name
Recolher sumário
Expandir sumário

Atributo x:Name

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente ]

Identifica de forma exclusiva os elementos de objetos para obter acesso ao objeto instanciado de code-behind ou código geral. Após aplicação em um modelo de programação de suporte, x:Name pode ser considerado equivalente à variável que mantém a referência do objeto, conforme retornada por um construtor.

Uso do atributo XAML


<object x:Name="XAMLNameValue".../>

Valores XAML

TermoDescrição

XAMLNameValue

Uma cadeia em conformidade com as restrições da gramática XamlName.

 

Gramática XamlName

A seguir, você encontrará a gramática normativa para uma cadeia usada como chave nesta implementação XAML:

XamlName ::= NameStartChar (NameChar)*
NameStartChar ::= LetterCharacter | '_'
NameChar ::= NameStartChar | DecimalDigit
LetterCharacter ::= ('a'-'z') | ('A'–'Z')
DecimalDigit ::= '0'-'9'
CombiningCharacter::= none
  • Os caracteres são restritos à faixa ASCII inferior e, mais especificamente, às letras maiúsculas e minúsculas, aos dígitos e ao caractere de sublinhado (_) do alfabeto romano.
  • Não há suporte à faixa de caracteres Unicode.
  • Um nome não pode começar com um dígito. As implementações de algumas ferramentas precedem um sublinhado (_) na cadeia de caracteres quando o usuário insere um dígito como o caractere inicial, ou a ferramenta gera automaticamente valores x:Name com base em outros valores que incluam dígitos.

Comentários

O atributo x:Name torna-se o nome de um campo criado no código subjacente quando o código XAML é processado. Esse campo mantém uma referência ao objeto. O processo de criação desse campo é realizado pelas etapas de destino do MSBuild, que também são responsáveis por associar as classes parciais de um arquivo XAML e seu code-behind. Esse comportamento não é necessariamente especificado pela linguagem XAML. É a implementação particular que a programação do Tempo de Execução do Windows para XAML aplica para usar x:Name eu seus modelos de programação e aplicativo.

Cada atributo x:Name definido deve ser exclusivo em um namescope XAML. Geralmente, um namescope XAML é definido no nível do elemento raiz de uma página carregada e contém todos os elementos sob esse elemento em uma única página XAML. Namescopes XAML adicionais são definidos por qualquer modelo de controle ou de dados que seja definido nessa página. Em tempo de execução, outro namescope XAML é criado para a raiz da árvore de objetos que é criada de um modelo de controle aplicado e também por árvores de objetos criadas através de uma chamada a XamlReader.Load. Para saber mais, veja Namescopes XAML.

As ferramentas de design muitas vezes geram valores x:Name automaticamente para elementos quando são introduzidos na superfície de design. O esquema de geração automática varia dependendo do designer usado, mas um esquema típico é gerar uma cadeia que comece com o nome da classe que apoia o elemento, seguido por um inteiro adiantado. Por exemplo, se você inserir o primeiro elemento Button no designer, poderá ver que, no XAML, esse elemento tem o valor de atributo x:Name igual a "Button1".

x:Name não pode ser definido na sintaxe do elemento da propriedade XAML ou em códigos que usam SetValue. x:Name só pode ser definido usando sintaxe de atributo XAML em elementos.

Observação  Especificamente para aplicativos C++, um campo existente para uma referência de x:Name não é criado para o elemento raiz de um arquivo ou de uma página XAML. Se você precisa mencionar o objeto raiz do code-behind C++, use outras APIs ou outro percurso de árvore. Por exemplo, você pode chamar FindName para um elemento filho nomeado conhecido e depois chamar Parent.
 

x:Name e outras propriedades de Name

Alguns tipos usados no XAML de Tempo de Execução do Windows também têm uma propriedade chamada Name. Por exemplo, FrameworkElement.Name e TextElement.Name.

Se Name estiver disponível como uma propriedade definível em um elemento, Name e x:Name poderão ser usados de forma intercambiável em XAML, mas ocorrerá erro se os dois atributos forem especificados no mesmo elemento. Também há casos em que há uma propriedade Name, mas que é somente leitura (como VisualState.Name). Se essa for a situação, use sempre x:Name para nomear esse elemento no XAML, e o Name somente leitura existirá para algum cenário de código menos comum.

Normalmente, o XAML de uma interface do usuário é criado usando uma ferramenta de design, como Blend para Microsoft Visual Studio 2013. Normalmente, o código XAML criado pela saída da ferramenta de design gera atributos x:Name de forma consistente nos elementos, mesmo quando há uma propriedade Name equivalente disponível.

Observação  FrameworkElement.Name geralmente não deve ser usada como uma maneira de mudar valores originariamente definidos por x:Name, apesar de haver alguns cenários de exceção a essa regra geral. Em cenários típicos, a criação e definição de namescopes XAML é uma operação do processador XAML. A modificação de FrameworkElement.Name em tempo de execução pode resultar em um inconsistente alinhamento de nomenclatura de campo privado/namescope XAML, que será difícil de controlar no code-behind.
 

x:Name e x:Key

x:Name pode ser aplicado como um atributo aos elementos em uma ResourceDictionary para atuar como substituto do atributo x:Key. (Normalmente é regra que todos os elementos em uma ResourceDictionary precisam ter x:Key.) Isso é comum para animações de storyboard. Para saber mais, veja a seção de Referências de ResourceDictionary e recursos XAML.

Tópicos relacionados

Namescopes XAML
FrameworkElement.Name
FindName
Atributo x:Key

 

 

Mostrar:
© 2017 Microsoft