x:Name, directivex:Name Directive

Identifie de façon unique les éléments définis dans XAML dans une portée de nom XAML.Uniquely identifies XAML-defined elements in a XAML namescope. Portées de nom XAML et de leurs modèles d’unicité peuvent être appliquées aux objets instanciés, lorsque les infrastructures fournissent des API ou implémentent les comportements qui accèdent au graphique d’objets créé en XAML en cours d’exécution.XAML namescopes and their uniqueness models can be applied to the instantiated objects, when frameworks provide APIs or implement behaviors that access the XAML-created object graph at run time.

Utilisation d'attributs XAMLXAML Attribute Usage

<object x:Name="XAMLNameValue".../>  

Valeurs XAMLXAML Values

XAMLNameValue Chaîne qui est conforme aux restrictions de la XamlName, grammaire.A string that conforms to the restrictions of the XamlName Grammar.

NotesRemarks

Après avoir x:Name est appliqué à une infrastructure de stockage du modèle de programmation, le nom est équivalent à la variable qui contient une référence d’objet ou une instance, telle que retournée par un constructeur.After x:Name is applied to a framework's backing programming model, the name is equivalent to the variable that holds an object reference or an instance as returned by a constructor.

La valeur d’un x:Name utilisation de la directive doit être unique dans une portée de nom XAML.The value of an x:Name directive usage must be unique within a XAML namescope. Par défaut lorsqu’il est utilisé par les API des Services XAML .NET Framework, la portée de nom XAML principale est définie à l’élément racine XAML d’une production XAML unique et comprend les éléments qui sont contenus dans cette production XAML.By default when used by .NET Framework XAML Services API, the primary XAML namescope is defined at the XAML root element of a single XAML production, and encompasses the elements that are contained in that XAML production. Portées de nom XAML supplémentaires discrètes qui peuvent se produire dans une production XAML unique peuvent être définies par les infrastructures pour résoudre des scénarios spécifiques.Additional discrete XAML namescopes that might occur within a single XAML production can be defined by frameworks to address specific scenarios. Par exemple, dans WPF, nouvelles portées de nom XAML sont définies et créées par n’importe quel modèle est également défini sur cette production XAML.For example, in WPF, new XAML namescopes are defined and created by any template that is also defined on that XAML production. Pour plus d’informations sur les portées de nom XAML (écrites pour WPF mais pertinents pour de nombreux concepts de portée de nom XAML), consultez portées de nom XAML WPF.For more information about XAML namescopes (written for WPF but relevant for many XAML namescope concepts), see WPF XAML Namescopes.

En règle générale, x:Name ne doit pas être appliqué dans les situations qui utilisent également x:Key.In general, x:Name should not be applied in situations that also use x:Key. Les implémentations XAML par les infrastructures spécifiques existantes ont introduit des concepts de substitution entre x:Key et x:Name, mais ce n’est pas une pratique recommandée.XAML implementations by specific existing frameworks have introduced substitution concepts between x:Key and x:Name, but that is not a recommended practice. Les Services XAML .NET framework ne prend pas en charge ces concepts de substitution lors de la gestion des informations de nom/clé tels que INameScope ou DictionaryKeyPropertyAttribute..NET Framework XAML Services does not support such substitution concepts when handling name/key information such as INameScope or DictionaryKeyPropertyAttribute.

Règles d’autorisation de x:Name , ainsi que la mise en œuvre de l’unicité de nom sont définies potentiellement par des infrastructures d’implémentation spécifiques.Rules for permittance of x:Name as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. Toutefois, pour être utilisables avec les Services XAML .NET Framework, les définitions de framework d’unicité de portée de nom XAML doivent être cohérentes avec la définition de INameScope informations contenues dans cette documentation et doivent utiliser les mêmes règles sur les endroits où le informations sont appliquées.However, to be usable with .NET Framework XAML Services, the framework definitions of XAML namescope uniqueness should be consistent with the definition of INameScope information in this documentation, and should use the same rules regarding where the information is applied. Par exemple, le Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) implémentation divise les différents éléments de balisage en distinct NameScope plages d’adresses, telles que des dictionnaires de ressources, l’arborescence logique par le niveau de la page XAML, modèles et d’autres différée contenu créé et applique ensuite XAML unicité des noms dans chacun de ces portées de nom XAML.For example, the Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) implementation divides various markup elements into separate NameScope ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, and other deferred content, and then enforces XAML name uniqueness within each of those XAML namescopes.

Pour les types personnalisés qui utilisent les writers d’objet XAML de Services XAML .NET Framework, une propriété qui est mappée à x:Name sur un type peut être établi ou modifié.For custom types that use .NET Framework XAML Services XAML object writers, a property that maps to x:Name on a type can be established or changed. Vous définissez ce comportement en référençant le nom de la propriété à mapper avec le RuntimeNamePropertyAttribute dans le code de définition de type.You define this behavior by referencing the name of the property to map with the RuntimeNamePropertyAttribute in the type definition code. RuntimeNamePropertyAttribute est un attribut au niveau du type.RuntimeNamePropertyAttribute is a type-level attribute.

Using.NET XAML Services Framework, et la logique de stockage pour la prise en charge de la portée de nom XAML peut être définies d’une façon indépendante du framework en implémentant le INameScope interface.Using.NET Framework XAML Services, the backing logic for XAML namescope support can be defined in a framework-neutral way by implementing the INameScope interface.

Remarques sur l’utilisation WPFWPF Usage Notes

Sous la configuration de build standard pour un WPFWPF application qui utilise XAML, les classes partielles et les code-behind, spécifié x:Name devient le nom d’un champ qui est créé dans sous-jacent le code lorsque XAMLXAML est traité par un balisage tâche de génération de compilation et que ce champ contient une référence à l’objet.Under the standard build configuration for a WPFWPF application that uses XAML, partial classes, and code-behind, the specified x:Name becomes the name of a field that is created in the underlying code when XAMLXAML is processed by a markup compilation build task, and that field holds a reference to the object. Par défaut, le champ créé est interne.By default, the created field is internal. Vous pouvez modifier l’accès à un champ en spécifiant le attribut x : FieldModifier.You can change field access by specifying the x:FieldModifier attribute. Dans WPF et Silverlight, la séquence est que la compilation de balisage définit et noms de champ dans une classe partielle, mais la valeur est initialement vide.In WPF and Silverlight, the sequence is that the markup compile defines and names the field in a partial class, but the value is initially empty. Ensuite, une méthode générée nommée InitializeComponent est appelée à partir du constructeur de classe.Then, a generated method named InitializeComponent is called from within the class constructor. InitializeComponent se compose de FindName appelle à l’aide de chacun de la x:Name entrer des valeurs qui existent dans la partie définie en XAML de la classe partielle en tant que chaînes.InitializeComponent consists of FindName calls using each of the x:Name values that exist in the XAML-defined part of the partial class as input strings. Les valeurs de retour sont ensuite affectées à la référence de champ pour remplir les valeurs de champ avec des objets qui ont été créés à partir de XAML à l’analyse.The return values are then assigned to the like-named field reference to fill the field values with objects that were created from XAML parsing. L’exécution de InitializeComponent rendent possible le graphique d’objet moment de l’exécution à l’aide de référence le x:Name / nom du champ directement, plutôt que de devoir appeler FindName explicitement chaque fois que vous devez une référence à un objet défini par XAML.The execution of InitializeComponent make it possible to reference the run time object graph using the x:Name / field name directly, rather than having to call FindName explicitly any time you need a reference to a XAML-defined object.

Pour un WPF application qui utilise Microsoft Visual Basic cible et inclut des fichiers XAML avec Page action de génération, une propriété de référence distincte est créée pendant la compilation qui ajoute le WithEvents mot clé à tous les éléments qui ont un x:Name, pour prendre en charge Handles syntaxe pour les délégués de gestionnaire d’événements.For a WPF application that uses the Microsoft Visual Basic targets and includes XAML files with Page build action, a separate reference property is created during compilation that adds the WithEvents keyword to all elements that have an x:Name, to support Handles syntax for event handler delegates. Cette propriété est toujours publique.This property is always public. Pour plus d’informations, consultez Gestion des événements Visual Basic et WPF.For more information, see Visual Basic and WPF Event Handling.

x:Name est utilisé par le processeur WPF XAML pour inscrire un nom dans une portée de nom XAML au moment du chargement, même pour les cas où la page n’est pas compilé par balisage par les actions de génération (par exemple, un XAML libre d’un dictionnaire de ressources).x:Name is used by the WPF XAML processor to register a name into a XAML namescope at load time, even for cases where the page is not markup-compiled by build actions (for example, loose XAML of a resource dictionary). L’une des raisons de ce comportement sont, car le x:Name est potentiellement nécessaire pour ElementName liaison.One reason for this behavior is because the x:Name is potentially needed for ElementName binding. Pour plus d’informations, consultez vue d’ensemble de la liaison de données.For details, see Data Binding Overview.

Comme mentionné précédemment, x:Name (ou Name) ne doit pas être appliqué dans les situations qui utilisent également x:Key.As mentioned previously, x:Name (or Name) should not be applied in situations that also use x:Key. Le WPFWPF ResourceDictionary a un comportement spécial de se définir lui-même comme une portée de nom XAML, mais retourner non implémenté ou des valeurs null pour INameScope API comme une méthode pour appliquer ce comportement.The WPFWPF ResourceDictionary has a special behavior of defining itself as a XAML namescope but returning Not Implemented or null values for INameScope APIs as a way to enforce this behavior. Si l’analyseur WPF XAML rencontre Name ou x:Name dans un XAML définis par le ResourceDictionary, le nom n’est pas ajouté à une portée de nom XAML.If the WPF XAML parser encounters Name or x:Name in a XAML-defined ResourceDictionary, the name is not added to any XAML namescope. Une tentative de recherche de ce nom à partir d’une portée de nom XAML et le FindName méthodes ne retournera pas de résultats valides.Attempting to find that name from any XAML namescope and the FindName methods will not return valid results.

x : Name et le nomx:Name and Name

Nombreux scénarios d’application WPF peuvent éviter toute utilisation de la x:Name d’attribut, car le Name propriété de dépendance comme spécifié dans la valeur par défaut espace de noms XAML pour plusieurs des classes de base importantes telles que FrameworkElement et FrameworkContentElement est conforme à cette même fin.Many WPF application scenarios can avoid any use of the x:Name attribute, because the Name dependency property as specified in the default XAML namespace for several of the important base classes such as FrameworkElement and FrameworkContentElement satisfies this same purpose. Il existe toujours des scénarios XAML et WPF courants où les accès à un élément sans nécessiter de code Name propriété au niveau de l’infrastructure est importante.There are still some common XAML and WPF scenarios where code access to an element with no Name property at the framework level is important. Par exemple, certaines classes de prise en charge de l’animation et table de montage séquentiel ne prennent pas en charge un Name propriété, mais ils doivent souvent être référencées dans le code afin de contrôler l’animation.For example, certain animation and storyboard support classes do not support a Name property, but they often need to be referenced in code in order to control the animation. Vous devez spécifier x:Name en tant qu’attribut sur des chronologies et transformations créées dans XAML, si vous avez l’intention de faire référence ultérieurement à partir du code.You should specify x:Name as an attribute on timelines and transforms that are created in XAML, if you intend to reference them from code later.

Si Name est disponible en tant que propriété sur la classe, Name et x:Name peuvent être utilisés indifféremment en tant qu’attributs, mais une exception d’analyse se produit si les deux sont sur le même élément.If Name is available as a property on the class, Name and x:Name can be used interchangeably as attributes, but a parse exception will result if both are specified on the same element. Si le XAML est compilé par balisage, l’exception se produira sur la compilation de balisage, sinon il se produit lors du chargement.If the XAML is markup compiled, the exception will occur on the markup compile, otherwise it occurs on load.

Name peut être définie à l’aide de la syntaxe d’attribut XAML et à l’aide de code SetValue; Notez toutefois ce paramètre la Name propriété dans le code ne crée pas de référence de champ représentative dans la portée de nom XAML dans la plupart des cas où le XAML est déjà chargé.Name can be set using XAML attribute syntax, and in code using SetValue; note however that setting the Name property in code does not create the representative field reference within the XAML namescope in most circumstances where the XAML is already loaded. Au lieu de la tentative de définition Name dans le code, utilisez NameScope méthodes à partir de code, par rapport à la portée de nom appropriée.Instead of attempting to set Name in code, use NameScope methods from code, against the appropriate namescope.

Name peut également être définie à l’aide de la syntaxe d’élément de propriété avec du texte interne, mais qui est rare.Name can also be set using property element syntax with inner text, but that is uncommon. En revanche, x:Name ne peut pas être définie dans la syntaxe d’élément de propriété XAML, ou dans le code à l’aide SetValue; elle peut uniquement être définie à l’aide de syntaxe d’attribut sur les objets car il s’agit d’une directive.In contrast, x:Name cannot be set in XAML property element syntax, or in code using SetValue; it can only be set using attribute syntax on objects because it is a directive.

Remarques sur l’utilisation de SilverlightSilverlight Usage Notes

x:Name pour Silverlight est documenté séparément.x:Name for Silverlight is documented separately. Pour plus d’informations, consultez XAML Namespace (x :)) Fonctionnalités de langage (Silverlight).For more information, see XAML Namespace (x:) Language Features (Silverlight).

Voir aussiSee also