FrameworkElement.Name Propiedad

  • Referencia

Definición

Espacio de nombres:
Windows.UI.Xaml
Editar

Obtiene o establece el nombre de identificación del objeto. Cuando un procesador XAML crea el árbol de objetos a partir del marcado XAML, el código en tiempo de ejecución puede hacer referencia al objeto declarado por XAML por este nombre.

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 de propiedad

String

Platform::String

winrt::hstring

Nombre del objeto , que debe ser una cadena válida en la gramática XamlName (vea la tabla en la referencia de atributo x:Name ). El valor predeterminado es una cadena vacía.

Ejemplos

En este ejemplo se obtiene un valor para Name de un objeto existente y se usa ese nombre para volver a asignar una animación. Para dirigir una animación, establezca la propiedad adjunta 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

Comentarios

El uso más común de esta propiedad es especificar el atributo x:Name para un objeto en el marcado XAML o leer ese valor tal y como se estableció en el marcado. En la mayoría de los casos, el atributo x:Name y la propiedad Name son equivalentes. En cualquier elemento único, el atributo x:Name y la propiedad Name son mutuamente excluyentes como atributos XAML; Si intenta establecer x:Name y Name en el mismo elemento de objeto en el marcado, se produce un error del analizador.

Cuando usas las acciones de compilación de página predeterminadas para XAML, cualquier elemento XAML que tenga un atributo x:Name o Name genera referencias de campo que finalmente se rellenan mediante InitializeComponent cuando se carga el XAML. Las referencias de campo permiten un modelo de programación en el que los objetos se pueden hacer referencia directamente por su nombre en el código subyacente específico de la página, una vez que el árbol de objetos XAML se carga en una página o aplicación.

Los nombres deben ser únicos en un ámbito de nombres XAML. Por lo general, el ámbito de nombres XAML se define mediante la página XAML, pero ciertas características como plantillas o llamadas a la API como XamlReader.Load pueden definir ámbitos de nombres XAML independientes. Para obtener más información, consulta Ámbitos de nombres XAML.

El nombre nunca debe localizarse. Name se usa como variable de nombre de campo en código subyacente. Normalmente, este código no es accesible para el localizador que podría tener acceso a los archivos XAML que definen la interfaz de usuario, aunque esto depende de los procedimientos de localización y modelo de implementación. Este es un motivo por el que no debes mostrar ninguna cadena que proceda de Name en la interfaz de usuario de la aplicación.

Escenarios de nombre

Establecer x:Name o Name en el XAML que define los elementos de la interfaz de usuario admite varios escenarios principales: + Destino de animación Para aplicar una animación a una propiedad de objeto, debe tener como destino una instancia específica. Para ello, establezca la propiedad adjunta Storyboard.TargetName en cualquier escala de tiempo. El valor que establezca aquí es la cadena que asignó como x:Name o Name . Para obtener más información, consulta Animaciones con guion gráfico.

  • Partes de una plantilla de control Para admitir el modelo de estado visual y la inicialización del control, los autores de controles deben especificar valores name para las partes clave de un control con plantilla. Para obtener más información, consulte Inicio rápido: Plantillas de control.
  • Interacción en tiempo de ejecución general Por ejemplo, el código dentro de un controlador de eventos puede controlar un evento en un objeto que proporciona la interfaz de usuario de cambio, pero el cambio a las propiedades se produce en otro elemento de interfaz de usuario cercano. La manera más fácil de escribir código para esta situación es usar la referencia de campo generada a partir de un nombre.

FindName

El método de utilidad FindName, que está disponible en cualquier FrameworkElement, puede buscar objetos por nombre en el árbol de objetos siempre que estén en el ámbito de nombres XAML actual. FindName busca en el árbol de objetos creado por XAML en su totalidad. Técnicamente, lo que FindName está buscando realmente es el ámbito de nombres XAML, que no conserva la metáfora del árbol y se representa en su lugar como una tabla hash de nombres. FindName no puede encontrar nombres definidos en las plantillas aplicadas. Para buscar elementos en plantillas aplicadas, use VisualTreeHelper.GetChild para obtener el objeto raíz de plantilla aplicado. A continuación, puedes llamar a FindName en ese objeto raíz y buscarás en el ámbito de nombres XAML de la plantilla en lugar de en la página mayor.

Nombre y enlace de datos

No se puede usar el valor de cadena de Name como un valor de origen directo para un origen de enlace de datos. Si tiene que mostrar el mismo valor de cadena que Name en la interfaz de usuario con enlace, debe replicar el mismo valor en la propiedad Tag , que se puede usar como origen de enlace de propiedades. Tampoco use Name como destino de enlace.

El valor de x:Name o Name es el identificador que se usa para identificar el elemento de origen de un enlace ElementName . Para obtener más información, consulte Enlace de datos en profundidad.

Establecer el nombre en el código

Puede establecer el valor de Name para un objeto en tiempo de ejecución, pero hay algunas consideraciones y limitaciones importantes que debe tener en cuenta.

Por lo general, no se recomienda cambiar el valor de Name en el código en tiempo de ejecución si el objeto tenía un valor Name anterior establecido en XAML. Esto se debe a que establecer un nombre después de cargar el árbol de objetos no creará ni cambiará el nombre de identificación de la referencia de campo equivalente. Si ya existe una referencia de campo porque x:Name se proporciona en el marcado inicial y cambia el valor de Name, el campo y el nombre que necesita usar para buscar el objeto a través de FindName ahora son diferentes porque el campo permanece como nombre definido por marcado.

Establecer un valor name para un objeto que se creó en el código y, por lo tanto, nunca tenía un valor name definido por XAML es adecuado para determinados escenarios. Un escenario de este tipo es si quieres encontrar objetos creados por XAML o creados con código en el árbol mediante FindName como función de utilidad común. Para que ese escenario funcione, el Windows Runtime sigue usando y agrega a la representación hash del ámbito de nombres XAML en tiempo de ejecución. Si intentas agregar nuevos objetos con nombre a un árbol de objetos creado en gran medida xaml existente, los nombres deben ser únicos; de lo contrario, se produce una excepción de nombre duplicado. Es posible que la excepción de nombre duplicado no se produzca en el intento de establecer Nombre. Hasta que intentes agregar el objeto con nombre duplicado al árbol de objetos principal, el nuevo objeto tiene su propio ámbito de nombres XAML autocontenido. Solo es en el momento en que se conecta el objeto a un árbol de objetos más grande que se puede detectar la condición de nombre duplicado. O bien, la excepción puede producirse en la operación que los objetos conectados en el árbol, por ejemplo, en una llamada al método Add de una colección que se conecta al árbol de objetos principal.

Puede ser difícil saber a qué valores name ya existen en el ámbito de nombres XAML al que agregarás más adelante el nuevo objeto. No hay ninguna API específica que informe de la tabla hash completa de los nombres existentes en un ámbito de nombres XAML. Si establece valores name en el código ampliamente, es posible que necesite una técnica para generar cadenas de nombre que sean exclusivas del uso en tiempo de ejecución, o es posible que tenga que encapsular las llamadas que agreguen objetos recién con nombre en un bloque try-catch para detectar las excepciones que podrían dar lugar a un nombre duplicado. O bien, puedes agregar tu propio código a la implementación initializeComponent que lee los valores de nombre generados por XAML.

Tenga en cuenta que solo puede establecer Name en tiempo de ejecución para los objetos que son FrameworkElement o Inline. Si un objeto no tiene una propiedad Name y establecer el nombre en XAML habría requerido el uso del atributo x:Name en lugar de Name, no hay ninguna API en tiempo de ejecución disponible para establecer el nombre en tiempo de ejecución de este objeto.

Se aplica a

Consulte también