Diretiva x:Name

Artigo
12/18/2024

Identifica exclusivamente elementos definidos por XAML em um namescope XAML. Os namescopes XAML e seus modelos de exclusividade podem ser aplicados aos objetos instanciados, quando as estruturas fornecem APIs ou implementam comportamentos que acessam o grafo de objeto criado por XAML em tempo de execução.

Uso do atributo XAML

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

Valores XAML

Valor	Descrição
`XAMLNameValue`	Uma cadeia de caracteres que está em conformidade com as restrições do de Gramática XamlName.

Observações

Depois que x:Name é aplicado ao modelo de programação de suporte de uma estrutura, o nome é equivalente à variável que contém uma referência de objeto ou uma instância, conforme retornado por um construtor.

O valor de um uso de diretiva x:Name deve ser exclusivo em um namescope XAML. Por padrão, quando usado pela API dos Serviços XAML do .NET, o namescope XAML primário é definido no elemento raiz XAML de uma única produção XAML e abrange os elementos contidos nessa produção XAML. Namescopes XAML discretos adicionais que podem ocorrer em uma única produção XAML podem ser definidos por estruturas para abordar cenários específicos. Por exemplo, no WPF, novos namescopes XAML são definidos e criados por qualquer modelo que também seja definido nessa produção XAML. Para obter mais informações sobre namescopes XAML (escritos para WPF, mas relevantes para muitos conceitos de namescope XAML), consulte Namescopes XAML do WPF.

Em geral, x:Name não deve ser aplicado em situações que também usam x:Key. Implementações XAML por estruturas existentes específicas introduziram conceitos de substituição entre x:Key e x:Name, mas essa não é uma prática recomendada. Os Serviços XAML do .NET não dão suporte a esses conceitos de substituição ao lidar com informações de nome/chave, como INameScope ou DictionaryKeyPropertyAttribute.

As regras de permissão de x:Name, bem como a imposição de exclusividade de nome, são potencialmente definidas por estruturas de implementação específicas. No entanto, para ser utilizável com os Serviços XAML do .NET, as definições de estrutura de exclusividade do namescope XAML devem ser consistentes com a definição de informações INameScope nesta documentação e devem usar as mesmas regras sobre onde as informações são aplicadas. Por exemplo, a implementação do WPF (Windows Presentation Foundation) divide vários elementos de marcação em intervalos NameScope separados, como dicionários de recursos, a árvore lógica criada pelo XAML no nível da página, modelos e outro conteúdo adiado e impõe a exclusividade do nome XAML em cada um desses namescopes XAML.

Para tipos personalizados que usam gravadores de objetos XAML do .NET XAML Services, uma propriedade mapeada para x:Name em um tipo pode ser estabelecida ou alterada. Você define esse comportamento fazendo referência ao nome da propriedade a ser mapeada com o RuntimeNamePropertyAttribute no código de definição de tipo. RuntimeNamePropertyAttribute é um atributo de nível de tipo.

Using.NET Serviços XAML, a lógica de suporte para suporte ao namescope XAML pode ser definida de forma neutra em uma estrutura implementando a interface INameScope.

Notas de uso do WPF

Na configuração de build padrão para um aplicativo WPF que usa XAML, classes parciais e code-behind, o x:Name especificado se torna o nome de um campo criado no código subjacente quando XAML é processado por uma tarefa de compilação de marcação e esse campo mantém uma referência ao objeto. Por padrão, o campo criado é interno. Você pode alterar o acesso ao campo especificando o atributo x:FieldModifier. No WPF e no Silverlight, a sequência é que a compilação de marcação define e nomeia o campo em uma classe parcial, mas o valor está inicialmente vazio. Em seguida, um método gerado chamado InitializeComponent é chamado de dentro do construtor de classe. InitializeComponent consiste em chamadas FindName usando cada um dos valores x:Name que existem na parte definida por XAML da classe parcial como cadeias de caracteres de entrada. Os valores retornados são atribuídos à referência de campo com nome semelhante para preencher os valores de campo com objetos criados com base na análise XAML. A execução de InitializeComponent possibilita fazer referência ao grafo de objeto de tempo de execução usando o x:Name/nome de campo diretamente, em vez de precisar chamar FindName explicitamente sempre que precisar de uma referência a um objeto definido por XAML.

Para um aplicativo WPF que usa os destinos do Microsoft Visual Basic e inclui arquivos XAML com Page ação de build, uma propriedade de referência separada é criada durante a compilação que adiciona a palavra-chave WithEvents a todos os elementos que têm um x:Name, para dar suporte a Handles sintaxe para delegados do manipulador de eventos. Essa propriedade é sempre pública. Para obter mais informações, consulte de Tratamento de Eventos do Visual Basic e WPF.

x:Name é usado pelo processador XAML do WPF para registrar um nome em um namescope XAML no tempo de carregamento, mesmo para casos em que a página não é compilada por ações de build (por exemplo, XAML flexível de um dicionário de recursos). Um motivo para esse comportamento é porque o x:Name é potencialmente necessário para ElementName associação. Para obter detalhes, consulte Data Binding Overview.

Conforme mencionado anteriormente, x:Name (ou Name) não devem ser aplicados em situações que também usam x:Key. O ResourceDictionary do WPF tem um comportamento especial de se definir como um namescope XAML, mas retornar valores não implementados ou nulos para APIs INameScope como uma forma de impor esse comportamento. Se o analisador XAML do WPF encontrar Name ou x:Name em um ResourceDictionarydefinido por XAML, o nome não será adicionado a nenhum namescope XAML. A tentativa de localizar esse nome de qualquer namescope XAML e dos métodos FindName não retornará resultados válidos.

x:Name e Name

Muitos cenários de aplicativo WPF podem evitar qualquer uso do atributo x:Name, pois a propriedade de dependência Name conforme especificado no namespace XAML padrão para várias das classes base importantes, como FrameworkElement e FrameworkContentElement, satisfaz essa mesma finalidade. Ainda há alguns cenários comuns de XAML e WPF em que o acesso de código a um elemento sem Name propriedade no nível da estrutura é importante. Por exemplo, determinadas classes de suporte de storyboard e animação não dão suporte a uma propriedade Name, mas geralmente precisam ser referenciadas no código para controlar a animação. Você deve especificar x:Name como um atributo em linhas do tempo e transformações que são criadas no XAML, caso pretenda referenciá-las do código posteriormente.

Se Name estiver disponível como uma propriedade na classe, Name e x:Name poderão ser usados de forma intercambiável como atributos, mas uma exceção de análise resultará se ambos forem especificados no mesmo elemento. Se o XAML for compilado, a exceção ocorrerá na compilação de marcação, caso contrário, ocorrerá na carga.

Name pode ser definido usando a sintaxe do atributo XAML e no código usando SetValue; no entanto, observe que definir a propriedade Name no código não cria a referência de campo representativo dentro do namescope XAML na maioria das circunstâncias em que o XAML já está carregado. Em vez de tentar definir Name no código, use NameScope métodos do código em relação ao namescope apropriado.

Name também pode ser definido usando a sintaxe do elemento de propriedade com texto interno, mas isso é incomum. Por outro lado, x:Name não pode ser definido na sintaxe do elemento de propriedade XAML ou no código usando SetValue; ele só pode ser definido usando a sintaxe de atributo em objetos porque é uma diretiva.

Notas de uso do Silverlight

x:Name para Silverlight é documentado separadamente. Para obter mais informações, consulte namespace XAML (x:) Recursos de linguagem (Silverlight).

Compartilhar via