Partilhar via

Atributo x:Name

  • Artigo

Identifica exclusivamente os elementos do objeto para acesso ao objeto instanciado do code-behind ou do código geral. Uma vez aplicado a um modelo de programação de suporte, x:Name pode ser considerado equivalente à variável que contém uma referência de objeto, conforme retornado por um construtor.

Uso do atributo XAML

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

Valores XAML

Termo Descrição
Valor XAMLName Uma cadeia de caracteres que está em conformidade com as restrições da gramática XamlName.

Gramática XamlName

Veja a seguir a gramática normativa de uma cadeia de caracteres 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 ao intervalo ASCII inferior e, mais especificamente, às letras maiúsculas e minúsculas do alfabeto romano, dígitos e ao caractere sublinhado (_).
  • Não há suporte para o intervalo de caracteres Unicode.
  • Um nome não pode começar com um dígito. Algumas implementações de ferramentas precedem um sublinhado (_) a uma cadeia de caracteres se o usuário fornecer um dígito como o caractere inicial ou se a ferramenta gerar automaticamente valores x:Name com base em outros valores que contêm dígitos.

Comentários

O x:Name especificado se torna o nome de um campo criado no código subjacente quando o XAML é processado e esse campo contém uma referência ao objeto. O processo de criação desse campo é executado pelas etapas de destino do MSBuild, que também são responsáveis por unir as classes parciais de um arquivo XAML e seu code-behind. Esse comportamento não é necessariamente especificado pela linguagem XAML; é a implementação específica que a programação da Plataforma Universal do Windows (UWP) para XAML aplica para usar x:Name em seus modelos de programação e aplicativo.

Cada 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 desse elemento em uma única página XAML. Namescopes XAML adicionais são definidos por qualquer modelo de controle ou modelo de dados definido nessa página. Em tempo de execução, outro namescope XAML é criado para a raiz da árvore de objetos criada a partir de um modelo de controle aplicado e também por árvores de objetos criadas a partir de uma chamada para XamlReader.Load. Para obter mais informações, consulte Namescopes XAML.

As ferramentas de design geralmente geram automaticamente valores x:Name para elementos quando eles são introduzidos na superfície de design. O esquema de geração automática varia dependendo de qual designer você está usando, mas um esquema típico é gerar uma cadeia de caracteres que começa com o nome da classe que suporta o elemento, seguido por um inteiro avançado. Por exemplo, se você introduzir o primeiro elemento Button ao designer, poderá ver que, no XAML, esse elemento tem o valor do atributo x:Name de "Button1".

x:Name não pode ser definido na sintaxe do elemento de propriedade XAML ou no código usando SetValue. x:Name só pode ser definido usando a sintaxe de atributo XAML em elementos.

Observação Especificamente para aplicativos C++/CX, um campo de suporte para uma referência x:Name não é criado para o elemento raiz de um arquivo ou página XAML. Se você precisar fazer referência ao objeto raiz do code-behind C++, use outras APIs ou passagem de árvore. Por exemplo, você pode chamar FindName para um elemento filho nomeado conhecido e, em seguida, chamar Parent.

x:Name e outras propriedades Name

Alguns tipos usados no XAML UWP também têm uma propriedade chamada Name. Por exemplo, FrameworkElement.Name e TextElement.Name.

Se Name estiver disponível como uma propriedade configurável em um elemento, Name e x:Name poderão ser usados de forma intercambiável em XAML, mas ocorrerá um erro se ambos os atributos forem especificados no mesmo elemento. Também há casos em que há uma propriedade Name, mas ela é somente leitura (como VisualState.Name). Se esse for o caso, você sempre usará x:Name para nomear esse elemento no XAML e o Name somente leitura existe para algum cenário de código menos comum.

ObserveFrameworkElement.Name geralmente não deve ser usado como uma maneira de alterar os valores originalmente definidos por x:Name, embora existam alguns cenários que são exceções a essa regra geral. Em cenários típicos, a criação e a definição de namescopes XAML são uma operação do processador XAML. Modificar FrameworkElement.Name em tempo de execução pode resultar em um alinhamento inconsistente de namescope / nomenclatura de campo privado XAML, que é difícil de acompanhar em seu code-behind.

x:Nome e x:Chave

x:Name pode ser aplicado como um atributo a elementos dentro de um ResourceDictionary para atuar como um substituto para o atributo x:Key. (É uma regra que todos os elementos em um ResourceDictionary deve ter um atributo x:Key ou x:Name.) Isso é comum para animações com storyboard. Para obter mais informações, consulte a seção de ResourceDictionary e referências de recursos XAML.