x:Diretiva de nomes

Artigo
12/17/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 gráfico de objetos criado por XAML em tempo de execução.

Uso de atributos XAML

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

Valores XAML

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

Comentários

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 retornada por um construtor.

O valor de um uso de diretiva x:Name 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. 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 WPF XAML Namescopes.

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 .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 autorização de x:Name, bem como a aplicação da unicidade do nome, são potencialmente definidas por quadros de execução específicos. No entanto, para serem utilizáveis com os Serviços XAML .NET, as definições de estrutura de exclusividade do namescope XAML devem ser consistentes com a definição de informações de INameScope 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 de NameScope separados, como dicionários de recursos, a árvore lógica criada pelo XAML no nível da página, modelos e outros conteúdos adiados e, em seguida, impõe a exclusividade do nome XAML em cada um desses namescopes XAML.

Para tipos personalizados que usam gravadores de objeto XAML dos Serviços XAML .NET, 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 a namescope XAML pode ser definida de forma neutra em termos de estrutura implementando a interface INameScope.

Notas de uso do WPF

Sob a configuração de compilação 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 que é criado no código subjacente quando o XAML é processado por uma tarefa de compilação 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 está inicialmente vazio. Em seguida, um método gerado chamado InitializeComponent é chamado de dentro do construtor de classe. InitializeComponent consiste em FindName chamadas usando cada um dos valores de x:Name que existem 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 InitializeComponent tornar possível fazer referência ao gráfico de objeto de tempo de execução usando o nome x:Name / campo diretamente, em vez de ter que chamá-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 compilação, 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 oferecer suporte a sintaxe Handles para delegados do manipulador de eventos. Esta propriedade é sempre pública. Para obter mais informações, consulte Visual Basic e WPF Event Handling.

x:Name é usado pelo processador WPF XAML para registrar um nome em um namescope XAML em tempo de 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 definir-se como um namescope XAML, mas retornar valores Not Implemented ou null para APIs INameScope como uma maneira de impor esse comportamento. Se o analisador WPF XAML 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 a partir de qualquer namescope XAML e dos métodos FindName não retornará resultados válidos.

x:Nome e Nome

Muitos cenários de aplicativo WPF podem evitar qualquer uso do atributo x:Name, porque 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 existem alguns cenários comuns de XAML e WPF em que o acesso ao código a um elemento sem propriedade Name no nível da estrutura é importante. Por exemplo, certas classes de suporte a animação e storyboard não suportam uma propriedade Name, mas geralmente precisam ser referenciadas em código para controlar a animação. Você deve especificar x:Name como um atributo em linhas do tempo e transformações criadas em XAML, se pretender fazer referência a elas a partir do código posteriormente.

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

Name pode ser definido usando sintaxe de atributo XAML e em código usando SetValue; observa, no entanto, que definir a propriedade Name no código não cria a 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 no código, use NameScope métodos do código, em relação ao 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 SetValue; ele só pode ser definido usando sintaxe de atributo em objetos porque é uma diretiva.

Notas de uso do Silverlight

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

Partilhar via