Atributo x:Namex:Name attribute

Identifica de forma exclusiva os elementos de objetos para obter acesso ao objeto instanciado de code-behind ou código geral.Uniquely identifies object elements for access to the instantiated object from code-behind or general code. 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.Once applied to a backing programming model, x:Name can be considered equivalent to the variable holding an object reference, as returned by a constructor.

Uso do atributo XAMLXAML attribute usage

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

Valores XAMLXAML values

TermoTerm DescriçãoDescription
XAMLNameValueXAMLNameValue Uma cadeia em conformidade com as restrições da gramática XamlName.A string that conforms to the restrictions of the XamlName grammar.

Gramática XamlNameXamlName grammar

A seguir, você encontrará a gramática normativa para uma cadeia usada como chave nesta implementação XAML:The following is the normative grammar for a string that is used as a key in this XAML implementation:

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 para letras maiúsculas e minúsculas do alfabeto romano, dígitos e o caractere de sublinhado ( _ ).Characters are restricted to the lower ASCII range, and more specifically to Roman alphabet uppercase and lowercase letters, digits, and the underscore (_) character.
  • Não há suporte à faixa de caracteres Unicode.The Unicode character range is not supported.
  • Um nome não pode começar com um dígito.A name cannot begin with a digit. Algumas implementações de ferramenta precedem um sublinhado ( _ ) a uma cadeia de caracteres se o usuário fornece um dígito como o caractere inicial, ou a ferramenta gera valores de x:Name com base em outros valores que contêm dígitos.Some tool implementations prepend an underscore (_) to a string if the user supplies a digit as the initial character, or the tool autogenerates x:Name values based on other values that contain digits.

ComentáriosRemarks

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.The specified x:Name becomes the name of a field that is created in the underlying code when XAML is processed, and that field holds a reference to the object. 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.The process of creating this field is performed by the MSBuild target steps, which also are responsible for joining the partial classes for a XAML file and its code-behind. Esse comportamento não é necessariamente especificado pela linguagem XAML. É a implementação particular 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.This behavior is not necessarily XAML-language specified; it is the particular implementation that Universal Windows Platform (UWP) programming for XAML applies to use x:Name in its programming and application models.

Cada atributo x:Name definido deve ser exclusivo em um namescope XAML.Each defined x:Name must be unique within a XAML namescope. 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.Generally, a XAML namescope is defined at the root element level of a loaded page and contains all elements under that element in a single XAML page. Namescopes XAML adicionais são definidos por qualquer modelo de controle ou de dados que seja definido nessa página.Additional XAML namescopes are defined by any control template or data template that is defined on that page. No 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.At run time, another XAML namescope is created for the root of the object tree that is created from an applied control template, and also by object trees created from a call to XamlReader.Load. Para saber mais, veja Namescopes XAML.For more info, see XAML namescopes.

As ferramentas de design muitas vezes geram valores x:Name automaticamente para elementos quando são introduzidos na superfície de design.Design tools often autogenerate x:Name values for elements when they are introduced to the design surface. 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.The autogeneration scheme varies depending on which designer you are using, but a typical scheme is to generate a string that starts with the class name that backs the element, followed by an advancing integer. 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 de "Button1".For example, if you introduce the first Button element to the designer, you might see that in the XAML this element has the x:Name attribute value of "Button1".

x:Name não pode ser definido na sintaxe do elemento da propriedade XAML ou em códigos que usam SetValue.x:Name cannot be set in XAML property element syntax, or in code using SetValue. x:Name só pode ser definido usando sintaxe de atributo XAML em elementos.x:Name can only be set using XAML attribute syntax on elements.

Observação    Especificamente para aplicativos C++/CX, um campo de apoio para uma referência x:Name não é criado para o elemento raiz de um arquivo ou página XAML.Note  Specifically for C++/CX apps, a backing field for an x:Name reference is not created for the root element of a XAML file or page. Se você precisa mencionar o objeto raiz do code-behind C++, use outras APIs ou outro percurso de árvore.If you need to reference the root object from C++ code-behind, use other APIs or tree traversal. Por exemplo, você pode chamar FindName para um elemento filho nomeado conhecido e depois chamar Parent.For example you can call FindName for a known named child element and then call Parent.

x:Name e outras propriedades de Namex:Name and other Name properties

Alguns tipos usados no XAML da UWP também têm uma propriedade chamada Name.Some types used in UWP XAML also have a property named Name. Por exemplo, FrameworkElement.Name e TextElement.Name.For example, FrameworkElement.Name and 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.If Name is available as a settable property on an element, Name and x:Name can be used interchangeably in XAML, but an error results if both attributes are specified on the same element. Também há casos em que há uma propriedade Name mas que é somente leitura (como VisualState.Name).There are also cases where there's a Name property but it's read-only (like 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.If that's the case you always use x:Name to name that element in the XAML and the read-only Name exists for some less-common code scenario.

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.Note  FrameworkElement.Name generally should not be used as a way to change values originally set by x:Name, although there are some scenarios that are exceptions to that general rule. Em cenários típicos, a criação e definição de namescopes XAML é uma operação do processador XAML.In typical scenarios, the creation and definition of XAML namescopes is a XAML processor operation. A modificação de FrameworkElement.Name no tempo de execução pode resultar em um alinhamento inconsistente de nomenclatura de campo privado/namescope XAML, que será difícil de controlar no code-behind.Modifying FrameworkElement.Name at run time can result in an inconsistent XAML namescope / private field naming alignment, which is hard to keep track of in your code-behind.

x:Name e x:Keyx:Name and x:Key

x:Name pode ser aplicado como um atributo aos elementos em um ResourceDictionary para atuar como substituto do atributo x:Key.x:Name can be applied as an attribute to elements within a ResourceDictionary to act as a substitute for the x:Key attribute. (É regra que todos os elementos em uma ResourceDictionary deve ser um atributo x:Key ou x:Name). Isso é comum para animações Storyboarded.(It's a rule that all elements in a ResourceDictionary must have an x:Key or x:Name attribute.) This is common for Storyboarded animations. Para obter mais informações, consulte a seção de Referências de ResourceDictionary e recursos XAML.For more info, see section of ResourceDictionary and XAML resource references.