FrameworkElement.Name Property

Obtient ou définit le nom d'identification de l'objet. Quand un processeur XAML crée l'arborescence d'objets à partir du balisage XAML, le code à l'exécution peut faire référence à l'objet déclaré par XAML par ce nom.

Syntaxe


public string Name { get; set; }


<frameworkElement Name="xamlNameString"/>

Valeur de propriété

Type: System.String [.NET] | Platform::String [C++]

Le nom de l'objet, qui doit être une chaîne valide dans la Grammaire XamlName (voir le tableau à la référence x:Name). La valeur par défaut est une chaîne vide.

Remarques

L'utilisation la plus courante de cette propriété est de spécifier l'attribut X:Name pour un objet dans le balisage XAML, ou de lire cette valeur comme elle a été définie dans le balisage. Par bien des aspects, l'attribut x:Name et la propriété Name sont équivalents. Sur un élément unique, l'attribut x:Name et la propriété Name s'excluent mutuellement en tant qu'attributs XAML ; si vous essayez de définir x:Name et Name sur le même élément objet dans le balisage, une erreur d'analyse est levée.

Lorsque vous utilisez les actions de génération par défaut Page XAML, tout élément XAML qui possède un x:Name ou Name génère des références de champs qui sont finalement remplies par InitializeComponent lorsque le code XAML est chargé. Les références de champs activent un modèle de programmation qui permet aux objets d'être directement référencés par un nom dans le code-behind spécifique à la page lorsque l'arborescence d'objets XAML est chargée dans une page ou une application.

Les noms doivent être uniques dans une portée de nom XAML. En général, la portée de nom XAML est définie par la page XAML, mais certaines fonctionnalités comme les modèles ou les appels aux API telles que XamlReader.Load peuvent définir des portées de nom XAML distinctes. Pour plus d'informations, consultez la section Espaces de noms XAML.

Name ne doit jamais être localisé. Name est utilisé comme variable de nom de champ en code-behind. Un tel code est généralement inaccessible au localiseur, qui peut avoir accès aux fichiers XAML qui définissent l'interface utilisateur, bien que cela dépende de vos procédures de localisation et modèle de déploiement. C'est une des raisons pour lesquelles vous ne devez pas afficher les chaînes provenant de Name dans l'interface utilisateur de votre application.

Scénarios pour Name

La définition de x:Name ou Name dans le code XAML qui définit les éléments d'interface utilisateur prend en charge plusieurs scénarios majeurs :

  • Ciblage d'animation Pour appliquer une animation à une propriété d'objet, vous devez cibler une instance spécifique. Pour ce faire, définissez la propriété jointe Storyboard.TargetName sur toute Timeline. La valeur que vous définissez ici est la chaîne que vous avez assignée comme x:Name ou Name. Pour plus d'informations, consultez Démarrage rapide : animation de votre interface utilisateur.
  • Parties d'un modèle de contrôle Pour prendre en charge le modèle d'état visuel et l'initialisation de contrôle, les auteurs de contrôle doivent spécifier des valeurs Name pour les parties clés d'un contrôle basé sur un modèle. Pour plus d'informations, consultez Quickstart: Control templates.
  • Interaction au moment de l'exécution générale Par exemple, le code dans un gestionnaire d'événements peut gérer un événement sur un objet qui fournit l'interface utilisateur de modification, mais la modification apportée aux propriétés se produit sur un autre élément d'interface utilisateur proche. La méthode la plus simple pour écrire le code dans cette situation consiste à utiliser la référence de champ générée à partir d'un Name.

FindName

La méthode utilitaire FindName, qui est disponible sur tout FrameworkElement, peut rechercher des objets par leur nom dans l'arborescence d'objets à condition qu'ils se trouvent dans la portée de nom XAML actuelle. FindName effectue une recherche dans l'intégralité de l'arborescence d'objets de création XAML. Techniquement, ce que le FindName recherche réellement est la portée de nom XAML, qui ne conserve pas la métaphore d'arborescence, mais est représentée sous forme d'une table de hachage de noms. FindName ne peut pas trouver les noms qui sont définis dans les modèles appliqués. Pour rechercher des éléments dans les modèles appliqués, utilisez VisualTreeHelper.GetChild pour obtenir l'objet racine du modèle appliqué. Ensuite, vous pouvez appeler la méthode FindName sur cet objet racine, et vous rechercherez dans la portée de nom XAML du modèle plutôt que dans la page supérieure.

Liaisons de noms et de données

Vous ne pouvez pas utiliser la valeur de chaîne de Name comme valeur source directe pour une source de liaison de données. Si vous devez afficher la même valeur de chaîne que Name dans l'interface utilisateur avec la liaison, vous devez répliquer la même valeur sur la propriété Tag, qui peut être utilisée comme source de liaison de propriété. De plus, n'utilisez pas Name comme cible de liaison.

La valeur de x:Name ou Name est l'identificateur que vous utilisez pour identifier l'élément source pour une liaison ElementName. Pour plus d'informations, consultez Liaison de données.

Définition du nom dans le code

Vous pouvez donner la valeur de Name à un objet au moment de l'exécution, mais il existe certaines considérations et limitations importantes que vous devez connaître.

Modifier la valeur de Name dans le code au moment de l'exécution, si l'objet avait une valeur Name précédente définie en XAML, n'est généralement pas recommandé. Cela provient du fait que, si un nom est défini une fois que l'arborescence d'objets a été chargée, le nom d'identification de la référence de champ équivalente ne sera pas créé ou modifié. S'il existe déjà une référence de champ parce que x:Name est fourni dans le balisage initial, et que vous modifiez ensuite la valeur de Name, le champ et le nom que vous devez utiliser pour rechercher l'objet via FindName sont maintenant différents car le champ est conservé en tant que nom défini dans le balisage.

La définition d'une valeur de Name pour un objet créé dans le code et qui n'a donc jamais eu de valeur Name définie en XAML est appropriée pour certains scénarios. Cela peut être le cas si vous souhaitez rechercher dans l'arborescence des objets créés dans XAML ou dans le code en utilisant FindName comme fonction utilitaire commune. Pour que ce scénario fonctionne, Windows Runtime continue à utiliser et à ajouter à la portée de nom XAML la représentation de la table de hachage au moment de l'exécution. Si vous tentez d'ajouter de nouveaux objets nommés à une arborescence d'objets de création XAML existante, les noms doivent être uniques, sinon une exception relative aux noms en double se produit. L'exception de nom dupliqué peut ne pas se produire lors de la tentative de définition de Name. Tant que vous ne tentez pas d'ajouter l'objet du même nom dans l'arborescence d'objets principal, le nouvel objet possède sa propre portée de nom XAML autonome. Ce n'est qu'au moment où vous connectez l'objet à une arborescence d'objets plus grande que la condition de nom en double peut être détectée. Ou, l'exception peut se produire lors de l'opération de connexion des objets de l'arborescence, par exemple lors d'un appel à la méthode Add d'une collection qui se connecte à l'arborescence d'objets principale.

Il peut s'avérer difficile de déterminer les valeurs Name déjà existantes dans la portée de nom XAML auxquelles vous ajouterez ultérieurement le nouvel objet. Il n'existe aucune API spécifique qui signale la table de hachage complète des noms existants dans une portée de nom XAML. Si vous définissez des valeurs Name dans le code de manière importante, vous pouvez avoir besoin d'une technique pour générer des chaînes de noms uniques pour une utilisation au moment de l'exécution, ou vous peut-être inclure des appels qui ajoutent des objets récemment nommés dans un bloc try-catch pour intercepter les exceptions qui peuvent se produire à la suite d'un nom en double. Ou vous pouvez ajouter votre propre code à l'implémentation InitializeComponent qui lit les valeurs de nom générées en XAML.

Notez que vous ne pouvez définir que Name au moment de l'exécution pour les objets de type FrameworkElement ou Inline. Si un objet n'a pas de propriété Name, et que la définition du nom en XAML nécessite l'utilisation de l'attribut x:Name, plutôt que Name, il n'existe aucune API d'exécution disponible pour définir le nom d'un tel objet à l'exécution.

Exemples

Cet exemple obtient une valeur pour Name à partir d'un objet existant et utilise ce nom pour recibler une animation. Vous ciblez une animation en définissant la propriété jointe 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();
}


Configuration requise

Client minimal pris en charge

Windows 8

Serveur minimal pris en charge

Windows Server 2012

Espace de noms

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Métadonnées

Windows.winmd

Voir aussi

FrameworkElement
x:Name
FindName
Storyboard.TargetName
XAML, portées de nom
XAML, vue d'ensemble

 

 

Afficher:
© 2014 Microsoft