FrameworkElement.Name Propriedade

Definição

Namespace:

Windows.UI.Xaml

Obtém ou define o nome de identificação do objeto. Quando um processador XAML cria a árvore de objetos com base na marcação XAML, o código em tempo de execução pode se referir ao objeto declarado por XAML por esse nome.

public:
 property Platform::String ^ Name { Platform::String ^ get(); void set(Platform::String ^ value); };

winrt::hstring Name();

void Name(winrt::hstring value);

public string Name { get; set; }

var string = frameworkElement.name;
frameworkElement.name = string;

Public Property Name As String

<frameworkElement Name="xamlNameString"/>

Valor da propriedade

String

Platform::String

winrt::hstring

O nome do objeto, que deve ser uma cadeia de caracteres válida na gramática XamlName (consulte a tabela na referência de atributo x:Name ). O padrão é uma cadeia de caracteres vazia.

Exemplos

Este exemplo obtém um valor para Name de um objeto existente e usa esse nome para redirecionar uma animação. Você direciona uma animação definindo a propriedade anexada Storyboard.TargetName .

private void Start_Animation(object sender, PointerRoutedEventArgs e)
{

    // If the Storyboard is running and you try to change
    // properties of its animation objects programmatically, 
    // an error will occur.
    myStoryboard.Stop();

    // Get a reference to the rectangle that was clicked.
    Rectangle myRect = (Rectangle)sender;

    // Change the TargetName of the animation to the name of the
    // rectangle that was clicked.
    myDoubleAnimation.SetValue(Storyboard.TargetNameProperty, myRect.Name);

    // Begin the animation.
    myStoryboard.Begin();
}

Private Sub Start_Animation(ByVal sender As Object, ByVal e As PointerRoutedEventArgs)
    ' If the Storyboard is running and you try to change
    ' properties of its animation objects programmatically, 
    ' an error will occur.
    myStoryboard.Stop()
    ' Get a reference to the rectangle that was clicked.
    Dim myRect As Rectangle = CType(sender, Rectangle)
    ' Change the TargetName of the animation to the name of the
    ' rectangle that was clicked.
    myDoubleAnimation.SetValue(Storyboard.TargetNameProperty, myRect.Name)
    ' Begin the animation.
    myStoryboard.Begin()
End Sub

Comentários

O uso mais comum dessa propriedade é especificar o atributo x:Name para um objeto na marcação XAML ou ler esse valor como ele foi definido na marcação. Na maioria das maneiras, o atributo x:Name e a propriedade Name são equivalentes. Em qualquer elemento único, o atributo x:Name e a propriedade Name são mutuamente exclusivos como atributos XAML; se você tentar definir x:Name e Name no mesmo elemento de objeto na marcação, um erro do analisador será gerado.

Quando você usa as ações de build de página padrão para XAML, qualquer elemento XAML que tenha um atributo x:Name ou Name gera referências de campo que eventualmente são preenchidas por InitializeComponent quando o XAML é carregado. As referências de campo habilitam um modelo de programação pelo qual os objetos podem ser referenciados diretamente pelo nome no code-behind específico da página, depois que a árvore de objetos XAML é carregada em uma página ou aplicativo.

Os nomes devem ser exclusivos em um namescope XAML. Geralmente, o namescope XAML é definido pela página XAML, mas determinados recursos, como modelos ou chamadas à API, como XamlReader.Load , podem definir namescopes XAML separados. Para saber mais, veja Namescopes XAML.

O nome nunca deve ser localizado. O nome é usado como uma variável de nome de campo no code-behind. Normalmente, esse código é inacessível para o localizador que, de outra forma, pode ter acesso a arquivos XAML que definem a interface do usuário, embora isso dependa do modelo de implantação e dos procedimentos de localização. Esse é um dos motivos pelos quais você não deve exibir cadeias de caracteres provenientes de Nome na interface do usuário do aplicativo.

Cenários para Nome

Definir x:Name ou Name no XAML que define elementos de interface do usuário dá suporte a vários cenários principais: + Direcionamento de animação Para aplicar uma animação a uma propriedade de objeto, você deve direcionar uma instância específica. Faça isso definindo a propriedade anexada Storyboard.TargetName em qualquer Linha do Tempo. O valor definido aqui é a cadeia de caracteres que você atribuiu como x:Name ou Name. Para saber mais, consulte Animações com storyboard.

• Partes de um modelo de controle Para dar suporte ao modelo de estado visual e à inicialização de controle, os autores de controle devem especificar valores name para as partes principais de um controle com modelo. Para obter mais informações, consulte Início Rápido: Modelos de controle.
• Interação geral em tempo de execução Por exemplo, o código dentro de um manipulador de eventos pode manipular um evento em um objeto que fornece a interface do usuário de alteração, mas a alteração nas propriedades ocorre em outro elemento de interface do usuário próximo. A maneira mais fácil de escrever código para essa situação é usar a referência de campo gerada a partir de um Nome.

FindName

O método de utilitário FindName, que está disponível em qualquer FrameworkElement, pode localizar objetos por nome na árvore de objetos, desde que estejam no namescope XAML atual. FindName pesquisa a árvore de objetos criada por XAML em sua totalidade. Tecnicamente, o que FindName está realmente pesquisando é o namescope XAML, que não preserva a metáfora da árvore e, em vez disso, é representado como uma tabela de hash de nomes. FindName não pode localizar nomes definidos em modelos aplicados. Para localizar itens em modelos aplicados, use VisualTreeHelper.GetChild para obter o objeto raiz do modelo aplicado. Em seguida, você pode chamar FindName nesse objeto raiz e pesquisará o namescope XAML do modelo em vez da página maior.

Nome e associação de dados

Você não pode usar o valor de cadeia de caracteres de Name como um valor de origem direto para uma fonte de associação de dados. Se você precisar exibir o mesmo valor de cadeia de caracteres que Nome na interface do usuário com associação, deverá replicar o mesmo valor para a propriedade Tag , que pode ser usada como uma fonte de associação de propriedade. Também não use Name como um destino de associação.

O valor de x:Name ou Name é o identificador que você usa para identificar o elemento de origem de uma associação ElementName . Para obter mais informações, consulte Associação de dados em detalhes.

Definindo Nome no código

Você pode definir o valor de Name para um objeto em tempo de execução, mas há algumas considerações e limitações importantes que você deve estar ciente.

Alterar o valor de Name no código em tempo de execução se o objeto tiver um valor Name anterior definido em XAML geralmente não é recomendado. Isso ocorre porque a configuração de um nome após o carregamento da árvore de objetos não criará ou alterará o nome de identificação da referência de campo equivalente. Se já existir uma referência de campo porque x:Name é fornecido na marcação inicial e você altera o valor de Name, o campo e o nome que você precisa usar para localizar o objeto por meio de FindName agora são diferentes porque o campo permanece como o nome definido pela marcação.

Definir um valor Name para um objeto que foi criado no código e, portanto, nunca teve um valor name definido por XAML é apropriado para determinados cenários. Um desses cenários é se você quiser encontrar objetos criados por XAML ou criados por código na árvore usando FindName como a função de utilitário comum. Para que esse cenário funcione, o Windows Runtime continua a usar e adicionar à representação de tabela de hash do namescope XAML em tempo de execução. Se você estiver tentando adicionar novos objetos nomeados a uma árvore de objetos criada em grande parte XAML existente, os nomes deverão ser exclusivos; caso contrário, ocorrerá uma exceção de nome duplicado. A exceção de nome duplicado pode não ocorrer na tentativa de definir Name. Até que você tente adicionar o objeto de nome duplicado à árvore de objetos main, o novo objeto tem seu próprio namescope XAML autossuficiido. É apenas no momento que você conecta o objeto a uma árvore de objetos maior que a condição de nome duplicado pode ser detectada. Ou a exceção pode ocorrer na operação que conectou objetos na árvore, por exemplo, em uma chamada para o método Add de uma coleção que se conecta à árvore de objetos main.

Pode ser difícil saber a quais valores de Name já existem no namescope XAML ao qual você adicionará posteriormente o novo objeto. Não há nenhuma API específica que relata a tabela de hash completa de nomes existentes em um namescope XAML. Se você definir valores de Nome no código extensivamente, talvez seja necessário uma técnica para gerar cadeias de caracteres de nome exclusivas para o uso do tempo de execução ou talvez seja necessário encapsular chamadas que adicionam objetos recém-nomeados em um bloco try-catch para capturar as exceções que podem resultar de um nome duplicado. Ou você pode adicionar seu próprio código à implementação InitializeComponent que lê os valores de nome gerados por XAML.

Observe que você só pode definir Name em tempo de execução para objetos que são um FrameworkElement ou um Inline. Se um objeto não tiver uma propriedade Name e definir o nome em XAML precisar usar o atributo x:Name em vez de Name, não haverá nenhuma API em tempo de execução disponível para definir o nome de tempo de execução desse objeto.

Confira também

• FindName(String)
• Atributo x:Name
• Storyboard.TargetName
• Namescopes XAML
• Visão geral do XAML