Diretiva x:Name

Artigo
10/18/2023

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 gráfico de objetos 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 da gramática XamlName.

Comentários

Depois x:Name de 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 retornada por um construtor.

O valor do uso de uma x:Name diretiva deve ser exclusivo dentro de um namescope XAML. Por padrão, quando usado pela API de Serviços XAML do .NET, o namescope XAML primário é definido no elemento raiz XAML de uma única produção XAML e engloba os elementos contidos nessa produção XAML. Escopos de nomes 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 WPF XAML Namescopes.

Em geral, x:Name não deve ser aplicado em situações que também utilizem x:Key. As 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 oferecem suporte a esses conceitos de substituição ao manipular informações de nome/chave, como INameScope ou DictionaryKeyPropertyAttribute.

As regras para a permissão, bem como a aplicação da x:Name exclusividade do 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 da exclusividade namescope XAML devem ser consistentes com a definição de INameScope informações nesta documentação e devem usar as mesmas regras em relação ao local onde as informações são aplicadas. Por exemplo, a implementação do Windows Presentation Foundation (WPF) divide vários elementos de marcação em intervalos separados NameScope , 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, em seguida, impõe a exclusividade do nome XAML em cada um desses escopos de nomes XAML.

Para tipos personalizados que usam gravadores de objeto XAML dos Serviços XAML do .NET, uma propriedade mapeada para x:Name 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 o suporte a namescope XAML pode ser definida de forma neutra em termos de estrutura implementando a INameScope interface.

Notas de uso do WPF

Na configuração de compilação padrão para um aplicativo WPF que usa XAML, classes parciais e code-behind, o especificado x:Name se torna o nome de um campo criado no código subjacente quando o XAML é processado por uma tarefa de compilação de marcação e esse campo conté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 é inicialmente vazio. Em seguida, um método gerado chamado é chamado InitializeComponent de dentro do construtor de classe. InitializeComponentFindName consiste em chamadas usando cada um dos x:Name valores existentes na parte definida por XAML da classe parcial como cadeias de caracteres de entrada. Os valores de retorno são atribuídos à referência de campo com nome semelhante para preencher os valores de campo com objetos que foram criados a partir da análise XAML. A execução de torna possível fazer referência ao gráfico de objeto de tempo de execução usando o nome do x:Name campo / diretamente, em vez de ter que chamar FindName explicitamente sempre que você precisar de InitializeComponent 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 compilação, uma propriedade de referência separada é criada durante a compilação que adiciona a palavra-chave a WithEvents todos os elementos que têm um x:Name, para oferecer suporte Handles à sintaxe para representantes do manipulador de eventos. Esta propriedade é sempre pública. Para obter mais informações, consulte Manipulação de eventos WPF e do Visual Basic.

x:Name é usado pelo processador XAML do WPF para registrar um nome em um namescope XAML no momento do carregamento, mesmo para casos em que a página não é compilada por marcação por ações de compilação (por exemplo, XAML solto de um dicionário de recursos). Uma razão para esse comportamento é porque o x:Name é potencialmente necessário para ElementName vinculação. Para obter detalhes, consulte Visão geral da vinculação de dados.

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

x:Nome e Nome

Muitos cenários de aplicativo WPF podem evitar qualquer uso do x:Name atributo, porque a Name propriedade de dependência, 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, certas classes de suporte de animação e storyboard não oferecem suporte a uma Name propriedade, mas geralmente precisam ser referenciadas no código para controlar a animação. Você deve especificar x:Name como um atributo em linhas de tempo e transformações que são criadas em XAML, se você pretende fazer referência a elas a partir do código mais tarde.

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

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

Name também pode ser definido usando sintaxe de 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 ; ele só pode ser definido usando SetValuea sintaxe de atributo em objetos porque é uma diretiva.

Notas de uso do Silverlight

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

Compartilhar via