FrameworkElement.Name Propriété

  • Référence

Définition

Espace de noms:
Windows.UI.Xaml
Modifier

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

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"/>

Valeur de propriété

String

Platform::String

winrt::hstring

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

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();
}

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

Remarques

L’utilisation la plus courante de cette propriété consiste à spécifier l’attribut x:Name pour un objet dans le balisage XAML ou à lire cette valeur telle qu’elle a été définie dans le balisage. Dans la plupart des cas, l’attribut x:Name et la propriété Name sont équivalents. Sur n’importe quel é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 à la fois x:Name et Name sur le même élément objet dans le balisage, une erreur d’analyseur est générée.

Lorsque vous utilisez les actions de génération page par défaut pour XAML, tout élément XAML qui a un attribut x:Name ou Name génère des références de champ qui sont finalement remplies par InitializeComponent lors du chargement du CODE XAML. Les références de champ activent un modèle de programmation dans lequel les objets peuvent être directement référencés par leur nom dans votre code-behind spécifique à la page, une fois l’arborescence d’objets XAML chargée dans une page ou une application.

Les noms doivent être uniques dans un namescope XAML. En règle générale, l’étendue de nom XAML est définie par la page XAML, mais certaines fonctionnalités telles que les modèles ou les appels à l’API, comme XamlReader.Load , peuvent définir des namescopes XAML distincts. Pour plus d’informations, voir Namescopes XAML.

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

Scénarios pour le nom

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 principaux : + Ciblage d’animation Pour appliquer une animation à une propriété d’objet, vous devez cibler un instance spécifique. Pour ce faire, définissez la propriété jointe Storyboard.TargetName sur n’importe quelle chronologie. La valeur que vous définissez ici est la chaîne que vous avez affectée en tant que x:Name ou Name. Pour plus d’informations, voir Animations dans une table de montage séquentiel.

  • Parties d’un modèle de contrôle Pour prendre en charge le modèle d’état visuel et l’initialisation du contrôle, les auteurs de contrôles doivent spécifier des valeurs de nom pour les parties clés d’un contrôle modélisé. Pour plus d’informations , consultez Démarrage rapide : Modèles de contrôle.
  • Interaction générale au moment de l’exécution 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 des propriétés se produit sur un autre élément d’interface utilisateur proche. Le moyen le plus simple d’écrire du code pour cette situation consiste à utiliser la référence de champ générée à partir d’un nom.

FindName

La méthode utilitaire FindName, qui est disponible à partir de n’importe quel FrameworkElement, peut rechercher des objets par nom dans l’arborescence d’objets tant qu’ils se trouvent dans l’étendue de nom XAML actuelle. FindName recherche l’arborescence d’objets créée par XAML dans son intégralité. Techniquement, ce que FindName recherche en fait est l’étendue de nom XAML, qui ne conserve pas la métaphore de l’arborescence et est plutôt représentée sous la forme d’une table de hachage de noms. FindName ne peut pas trouver les noms 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é. Vous pouvez ensuite appeler FindName sur cet objet racine, et vous allez rechercher l’étendue de nom XAML du modèle plutôt que la page supérieure.

Liaison de nom et de données

Vous ne pouvez pas utiliser la valeur de chaîne name comme valeur de 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 liaison, vous devez répliquer la même valeur dans la propriété Tag , qui peut être utilisée comme source de liaison de propriété. N’utilisez pas non plus Name comme cible de liaison.

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

Définition du nom dans le code

Vous pouvez définir la valeur Name d’un objet au moment de l’exécution, mais il existe des considérations et des limitations importantes que vous devez connaître.

Il n’est généralement pas recommandé de 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. Cela est dû au fait que la définition d’un nom après le chargement de l’arborescence d’objets ne crée pas ou ne modifie pas le nom d’identification de la référence de champ équivalente. Si une référence de champ existe déjà parce que x:Name est fourni dans le balisage initial et que vous modifiez la valeur de Name, le champ et le nom que vous devez utiliser pour rechercher l’objet via FindName sont désormais différents, car le champ reste en tant que nom défini par le balisage.

La définition d’une valeur Name pour un objet qui a été créé dans le code et qui n’a donc jamais eu de valeur Name définie par XAML est appropriée pour certains scénarios. L’un de ces scénarios est si vous souhaitez être en mesure de trouver des objets créés par XAML ou créés par code dans l’arborescence en utilisant FindName comme fonction utilitaire commune. Pour que ce scénario fonctionne, le Windows Runtime continue à utiliser et à ajouter à la représentation de table de hachage xaml au moment de l’exécution. Si vous tentez d’ajouter de nouveaux objets nommés à une arborescence d’objets en grande partie créée par XAML, les noms doivent être uniques, sinon une exception de nom en double se produit. L’exception de nom en double peut ne pas se produire lors de la tentative de définition de Nom. Tant que vous n’avez pas tenté d’ajouter l’objet nommé en double à l’arborescence d’objets main, le nouvel objet a son propre namescope XAML autonome. C’est seulement 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 bien, l’exception peut se produire sur l’opération qui a connecté des objets dans l’arborescence, par exemple lors d’un appel à la méthode Add d’une collection qui se connecte à l’arborescence d’objets main.

Il peut être difficile de savoir quelles valeurs name existent déjà dans l’étendue de noms XAML à laquelle 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 un namescope XAML. Si vous définissez largement les valeurs name dans le code, vous aurez peut-être besoin d’une technique pour générer des chaînes de noms propres à votre utilisation au moment de l’exécution, ou vous devrez peut-être encapsuler des appels qui ajoutent des objets nouvellement nommés dans un bloc try-catch pour intercepter les exceptions qui pourraient résulter d’un nom en double. Vous pouvez également ajouter votre propre code à l’implémentation InitializeComponent qui lit les valeurs de nom générées par XAML.

Notez que vous ne pouvez définir Name qu’au moment de l’exécution pour les objets qui sont un FrameworkElement ou un Inline. Si un objet n’a pas de propriété Name et que la définition du nom en XAML aurait nécessité l’utilisation de l’attribut x:Name plutôt que name, aucune API d’exécution n’est disponible pour définir le nom d’exécution d’un tel objet.

S’applique à

Voir aussi