FrameworkElement.Name Propriedade

Definição

Namespace:

System.Windows

Assembly:

PresentationFramework.dll

Obtém ou define o nome de identificação do elemento. O nome fornece uma referência para que code-behind, como o código do manipulador de eventos, possa se referir a um elemento de marcação depois de ser construído durante o processamento por um processador XAML.

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

[System.Windows.Localizability(System.Windows.LocalizationCategory.NeverLocalize)]
public string Name { get; set; }

[<System.Windows.Localizability(System.Windows.LocalizationCategory.NeverLocalize)>]
member this.Name : string with get, set

Public Property Name As String

Valor da propriedade

String

O nome do elemento. O padrão é uma cadeia de caracteres vazia.

Implementações

Name

Atributos

LocalizabilityAttribute

Exemplos

O exemplo a seguir define a Name propriedade no código e registra o nome no recém-criado NameScope chamando RegisterName. A técnica ilustrada aqui é um requisito para animar com storyboards, pois os storyboards exigem direcionamento Namepelo , e não podem ser direcionados pela referência de objeto.

//  
// Create a Rectangle
//
Rectangle myRectangle = new Rectangle();
myRectangle.Width = 200;
myRectangle.Height = 200;
myRectangle.Name = "myRectangle";
this.RegisterName(myRectangle.Name, myRectangle);

'  
' Create a Rectangle
'
Dim myRectangle As New Rectangle()
myRectangle.Width = 200
myRectangle.Height = 200
myRectangle.Name = "myRectangle"
Me.RegisterName(myRectangle.Name, myRectangle)

Comentários

O uso mais comum dessa propriedade é especificar um nome de elemento XAML como um atributo na marcação.

Essa propriedade fornece essencialmente uma propriedade de conveniência no nível da estrutura do WPF para definir a diretiva XAML x:Name.

Os nomes devem ser exclusivos em um namescope. Para obter mais informações, consulte Namescopes WPF XAML.

Obter um Name se você estiver criando elementos no código não é comum. Se você já tiver a referência apropriada no código, basta chamar métodos e propriedades na referência do elemento e geralmente não precisará do Name. Uma exceção a isso é se a Name cadeia de caracteres tiver algum significado sobrecarregado, por exemplo, se for útil exibir esse nome na interface do usuário. A configuração de um Name code-behind se o original Name foi definido a partir da marcação também não é recomendada, e alterar a propriedade depois de carregar o XAML não alterará a referência de objeto original. As referências de objeto são criadas somente quando os namescopes subjacentes são criados explicitamente durante a análise. Você deve chamar RegisterName especificamente para fazer uma alteração efetiva na Name propriedade de um elemento já carregado.

Um caso notável em que a configuração Name do código é importante é ao registrar nomes para elementos em que os storyboards serão executados, para que possam ser referenciados em tempo de execução. Antes de registrar um nome, talvez também seja necessário criar uma instância e atribuir uma NameScope instância. Consulte a seção Exemplo ou Visão Geral de Storyboards.

A configuração Name do código tem aplicativos limitados, mas obter um elemento é Name mais comum. Um cenário específico é se o aplicativo dá suporte a um modelo de navegação em que as páginas são recarregada no aplicativo e o código de tempo de execução não é necessariamente code-behind definido para essa página. O método FindNameutilitário, que está disponível em qualquer FrameworkElementum, pode encontrar qualquer elemento Name na árvore lógica para esse elemento, pesquisando a árvore recursivamente conforme necessário. Ou você pode usar o FindLogicalNode método estático de LogicalTreeHelper, que também usa uma Name cadeia de caracteres como um argumento.

Elementos raiz normalmente usados (WindowPagepor exemplo) implementam a interfaceINameScope. Espera-se que as implementações dessa interface imponham que os nomes sejam inequívocas em seu escopo. Os elementos raiz que definem essa interface também definem os limites de comportamento do namescope para todas as APIs relacionadas.

A Name propriedade também serve como um identificador para outros processos. Por exemplo, o modelo de automação do WPF será usado Name como AutomationId para clientes e provedores.

Os valores de cadeia de caracteres usados têm Name algumas restrições, conforme imposto pela diretiva x:Name subjacente definida pela especificação XAML. Mais notavelmente, é Name necessário começar com uma letra ou o caractere sublinhado (_) e deve conter apenas letras, dígitos ou sublinhados. Para obter mais informações, consulte Namescopes WPF XAML.

Name é uma das poucas propriedades de dependência que não podem ser animadas (IsAnimationProhibited está true em metadados), porque o nome em si é vital para direcionar uma animação. A associação Name de dados é tecnicamente possível, mas é um cenário extremamente incomum porque um limite Name de dados não pode servir à principal finalidade pretendida da propriedade: fornecer um ponto de conexão do identificador para code-behind.

Informações da propriedade de dependência

Campo identificador	NameProperty
Propriedades de metadados definidas como true	IsAnimationProhibited