FrameworkElement.Name Propriedade

Definição

Obtém ou define o nome de identificação do elemento.Gets or sets the identifying name of the element. O nome fornece uma referência para que o code-behind, como o código do manipulador de eventos, possa consultar um elemento de marcação depois que ele é construído durante o processamento por um processador XAMLXAML.The name provides a reference so that code-behind, such as event handler code, can refer to a markup element after it is constructed during processing by a XAMLXAML processor.

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; }
member this.Name : string with get, set
Public Property Name As String

Valor da propriedade

O nome do elemento.The name of the element. O padrão é uma cadeia de caracteres vazia.The default is an empty string.

Implementações

Atributos

Exemplos

O exemplo a seguir define a propriedade Name no código e registra o nome no NameScope recém-criado chamando RegisterName.The following example sets the Name property in code, and then registers the name into the newly created NameScope by calling RegisterName. A técnica ilustrada aqui é um requisito para animar com storyboards, porque os storyboards exigem direcionamento pelo Namee não podem ser direcionados por referência de objeto.The technique illustrated here is a requirement for animating with storyboards, because storyboards require targeting by the Name, and cannot be targeted by object reference.

//  
// 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 XAMLXAML como um atributo na marcação.The most common usage of this property is to specify a XAMLXAML element name as an attribute in markup.

Essa propriedade essencialmente fornece uma propriedade de conveniência de nível de estrutura do WPF para definir a diretiva de XAMLXAML x:Name.This property essentially provides a WPF framework-level convenience property to set the XAMLXAML x:Name Directive.

Os nomes devem ser exclusivos em um namescope.Names must be unique within a namescope. Para obter mais informações, consulte Namescopes WPF XAML.For more information, see WPF XAML Namescopes.

Obter um Name se você estiver criando elementos no código não for comum.Getting a Name if you are creating elements in code is not common. 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.If you have the appropriate reference in code already, you can just call methods and properties on the element reference and will not generally need the Name. Uma exceção a isso é se a cadeia de caracteres de Name tiver algum significado sobrecarregado, por exemplo, se for útil exibir esse nome em Interface de UsuárioUI.An exception to this is if the Name string has some overloaded meaning, for instance if it is useful to display that name in Interface de UsuárioUI. Definir um Name do code-behind se o Name original foi definido da marcação também não é recomendado e alterar a propriedade depois de carregar o XAMLXAML não alterará a referência do objeto original.Setting a Name from code-behind if the original Name was set from markup is also not recommended, and changing the property after loading the XAMLXAML will not change the original object reference. As referências de objeto são criadas somente quando os namescopes subjacentes são explicitamente criados durante a análise.The object references are created only when the underlying namescopes are explicitly created during parsing. Você deve chamar RegisterName especificamente para fazer uma alteração efetiva na propriedade Name de um elemento já carregado.You must specifically call RegisterName to make an effective change to the Name property of an already loaded element.

Um caso notável em que a definição de Name do código é importante é ao registrar nomes de elementos nos quais os storyboards serão executados, para que possam ser referenciados em tempo de execução.One notable case where setting Name from code is important is when registering names for elements that storyboards will run against, so that they can be referenced at run time. Antes de registrar um nome, talvez também seja necessário instanciar e atribuir uma instância de NameScope.Before you can register a name, might also need to instantiate and assign a NameScope instance. Consulte a seção de exemplo ou visão geral de storyboards.See the Example section, or Storyboards Overview.

A definição de Name do código tem aplicativos limitados, mas obter um elemento por Name é mais comum.Setting Name from code has limited applications, but getting an element by Name is more common. Um cenário específico é se seu aplicativo dá suporte a um modelo de navegação em que as páginas são recarregadas no aplicativo e o código de tempo de execução não é necessariamente code-behind definido para essa página.One particular scenario is if your application supports a navigation model where pages reload into the application, and the run time code is not necessarily code-behind defined for that page. O método utilitário FindName, que está disponível em qualquer FrameworkElement, pode encontrar qualquer elemento por Name na árvore lógica para esse elemento, pesquisando a árvore recursivamente, conforme necessário.The utility method FindName, which is available from any FrameworkElement, can find any element by Name in the logical tree for that element, searching the tree recursively as necessary. Ou você pode usar o método estático FindLogicalNode de LogicalTreeHelper, que também usa uma cadeia de caracteres Name como um argumento.Or you can use the FindLogicalNode static method of LogicalTreeHelper, which also takes a Name string as an argument.

Normalmente, os elementos raiz usados (Window, Page por exemplo) implementam a interface INameScope.Typically used root elements (Window, Page for example) implement the interface INameScope. As implementações dessa interface devem impor que os nomes não sejam ambíguos em seu escopo.Implementations of this interface are expected to enforce that names be unambiguous within their scope. Os elementos raiz que definem essa interface também definem os limites de comportamento do namescope para todas as APIs relacionadas.The root elements that define this interface also define the namescope behavior boundaries for all the related APIs.

A propriedade Name também serve como um identificador para outros processos.The Name property also serves as an identifier for other processes. Por exemplo, o modelo de automação de WPFWPF usará Name como AutomationId para clientes e provedores.For instance, the WPFWPF automation model will use Name as the AutomationId for clients and providers.

Os valores de cadeia de caracteres usados para Name têm algumas restrições, conforme imposto pela diretiva x:Name subjacente definida pela especificação de XAMLXAML.The string values used for Name have some restrictions, as imposed by the underlying x:Name Directive defined by the XAMLXAML specification. Mais notavelmente, um Name deve começar com uma letra ou o caractere de sublinhado () e deve conter apenas letras, dígitos ou sublinhados.Most notably, a Name must start with a letter or the underscore character (), and must contain only letters, digits, or underscores. Para obter mais informações, consulte Namescopes WPF XAML.For more information, see WPF XAML Namescopes.

Name é uma das poucas propriedades de dependência que não podem ser animadas (IsAnimationProhibited é true nos metadados), pois o próprio nome é vital para direcionar uma animação.Name is one of the very few dependency properties that cannot be animated (IsAnimationProhibited is true in metadata), because the name itself is vital for targeting an animation. A vinculação de dados de um Name é tecnicamente possível, mas é um cenário extremamente incomum porque uma Name associada a dados não pode atender à finalidade principal pretendida da propriedade: para fornecer um ponto de conexão de identificador para code-behind.Data binding a Name is technically possible, but is an extremely uncommon scenario because a data-bound Name cannot serve the main intended purpose of the property: to provide an identifier connection point for code-behind.

Informações de Propriedade de DependênciaDependency Property Information

Campo de identificadorIdentifier field NameProperty
Propriedades de metadados definidas como trueMetadata properties set to true IsAnimationProhibited

Aplica-se a