Portées de nom XAML WPFWPF XAML Namescopes

Les portées de nom XAML correspondent à un concept qui identifie des objets définis en XAML.XAML namescopes are a concept that identifies objects that are defined in XAML. Les noms dans une portée de nom XAML peuvent être utilisés pour établir des relations entre les noms définis en XAML des objets et leurs instances équivalentes dans une arborescence d’objets.The names in a XAML namescope can be used to establish relationships between the XAML-defined names of objects and their instance equivalents in an object tree. En règle générale, les portées de nom XAML dans du code managé WPFWPF sont créées lors du chargement des racines d’une page XAML spécifique pour une application XAML.Typically, XAML namescopes in WPFWPF managed code are created when loading the individual XAML page roots for a XAML application. Les portées de code XAML, comme l’objet de programmation, sont définies par l' INameScope interface et sont également implémentées par la classe pratique NameScope .XAML namescopes as the programming object are defined by the INameScope interface and are also implemented by the practical class NameScope.

Portées de nom dans les applications XAML chargéesNamescopes in Loaded XAML Applications

Dans un contexte plus large de programmation ou d’informatique, les concepts de programmation incluent souvent le principe d’un identificateur ou d’un nom unique, qui peut être utilisé pour accéder à un objet.In a broader programming or computer science context, programming concepts often include the principle of a unique identifier or name that can be used to access an object. Pour les systèmes qui utilisent des identificateurs ou des noms, la portée de nom définit les limites à l’intérieur desquelles un processus ou une technique recherche si un objet de ce nom est demandé, ou les limites dans lesquelles l’unicité des noms qui identifient est appliquée.For systems that use identifiers or names, the namescope defines the boundaries within which a process or technique will search if an object of that name is requested, or the boundaries wherein uniqueness of identifying names is enforced. Ces principes généraux sont vrais pour les portées de nom XAML.These general principles are true for XAML namescopes. Dans WPF, les portées de nom XAML sont créées sur l’élément racine d’une page XAML quand la page est chargée.In WPF, XAML namescopes are created on the root element for a XAML page when the page is loaded. Chaque nom spécifié dans la page XAML en commençant à la racine de la page est ajouté à une portée de nom XAML pertinente.Each name specified within the XAML page starting at the page root is added to a pertinent XAML namescope.

Dans le XAML WPF, les éléments qui sont des éléments racines courants (tels que Page et Window ) contrôlent toujours une portée de code XAML.In WPF XAML, elements that are common root elements (such as Page, and Window) always control a XAML namescope. Si un élément tel que FrameworkElement ou FrameworkContentElement est l’élément racine de la page dans le balisage, un XAMLXAML processeur ajoute une Page racine implicitement afin que le Page puisse fournir une portée de code XAML opérationnelle.If an element such as FrameworkElement or FrameworkContentElement is the root element of the page in markup, a XAMLXAML processor adds a Page root implicitly so that the Page can provide a working XAML namescope.

Notes

Les actions de génération WPF créent une portée de nom XAML pour une production XAML même si aucun attribut Name ou x:Name n’est défini sur les éléments dans la balisage XAMLXAML.WPF build actions create a XAML namescope for a XAML production even if no Name or x:Name attributes are defined on any elements in the XAMLXAML markup.

Si vous essayez d’utiliser deux fois le même nom dans une portée de nom XAML, une exception est levée.If you try to use the same name twice in any XAML namescope, an exception is raised. Pour du XAML WPF qui a du code-behind et qui fait partie d’une application compilée, l’exception est levée au moment de la génération par les actions de génération WPF, lors de la création de la classe générée pour la page pendant la compilation initiale du balisage.For WPF XAML that has code-behind and is part of a compiled application, the exception is raised at build time by WPF build actions, when creating the generated class for the page during the initial markup compile. Pour le XAML qui n’est compilé par balisage par aucune action de génération, des exceptions liées aux problèmes de portée de nom XAML peuvent être déclenchées lors du chargement du XAML.For XAML that is not markup-compiled by any build action, exceptions related to XAML namescope issues might be raised when the XAML is loaded. Les concepteurs XAML peuvent également anticiper les problèmes de portée de nom XAML au moment du design.XAML designers might also anticipate XAML namescope issues at design time.

Ajout d’objets à des arborescences d’objets d’exécutionAdding Objects to Runtime Object Trees

Le moment où le XAML est analysé correspond au moment une portée de nom XAML WPF est créée et définie.The moment that XAML is parsed represents the moment in time that a WPF XAML namescope is created and defined. Si vous ajoutez un objet à une arborescence d’objets après l’analyse du code XAML ayant généré cette arborescence, une valeur Name ou x:Name sur le nouvel objet ne met pas automatiquement à jour les informations contenues dans une portée de nom XAML.If you add an object to an object tree at a point in time after the XAML that produced that tree was parsed, a Name or x:Name value on the new object does not automatically update the information in a XAML namescope. Pour ajouter un nom pour un objet dans une portée de nom XAML WPF après le chargement du code XAML, vous devez appeler l’implémentation appropriée de RegisterName sur l’objet qui définit la portée de nom XAML, qui est généralement la racine de la page XAML.To add a name for an object into a WPF XAML namescope after XAML is loaded, you must call the appropriate implementation of RegisterName on the object that defines the XAML namescope, which is typically the XAML page root. Si le nom n’est pas inscrit, l’objet ajouté ne peut pas être référencé par nom via des méthodes telles que FindName , et vous ne pouvez pas utiliser ce nom pour le ciblage d’animation.If the name is not registered, the added object cannot be referenced by name through methods such as FindName, and you cannot use that name for animation targeting.

Le scénario le plus courant pour les développeurs d’applications est que vous allez utiliser RegisterName pour enregistrer des noms dans la portée de nom XAML sur la racine actuelle de la page.The most common scenario for application developers is that you will use RegisterName to register names into the XAML namescope on the current root of the page. RegisterName fait partie d’un scénario important pour les storyboards qui ciblent des objets pour les animations.RegisterName is part of an important scenario for storyboards that target objects for animations. Pour plus d’informations, consultez Vue d’ensemble des plans conceptuels.For more information, see Storyboards Overview.

Si vous appelez RegisterName sur un objet autre que l’objet qui définit la portée de nom XAML, le nom est toujours inscrit dans la portée de nom XAML dans laquelle l’objet appelant est conservé, comme si vous aviez appelé RegisterName sur la portée de nom XAML définissant l’objet.If you call RegisterName on an object other than the object that defines the XAML namescope, the name is still registered to the XAML namescope that the calling object is held within, as if you had called RegisterName on the XAML namescope defining object.

Portées de nom XAML dans du codeXAML Namescopes in Code

Vous pouvez créer et ensuite utiliser des portées de nom XAML dans du code.You can create and then use XAML namescopes in code. Les API et les concepts impliqués dans la création de portée de nom XAML sont les mêmes, même pour une utilisation du code pure, car le processeur XAML pour WPFWPF utilise ces API et concepts quand il traite le XAML lui-même.The APIs and the concepts involved in XAML namescope creation are the same even for a pure code usage, because the XAML processor for WPFWPF uses these APIs and concepts when it processes XAML itself. Les concepts et l’API existent principalement pour pouvoir rechercher des objets par nom dans une arborescence d’objets définie partiellement ou entièrement en XAML.The concepts and API exist mainly for the purpose of being able to find objects by name within an object tree that is typically defined partially or entirely in XAML.

Pour les applications créées par programme et non à partir du XAML chargé, l’objet qui définit une portée de code XAML doit implémenter INameScope , ou être une FrameworkElement FrameworkContentElement classe ou dérivée, afin de prendre en charge la création d’une portée de code XAML sur ses instances.For applications that are created programmatically, and not from loaded XAML, the object that defines a XAML namescope must implement INameScope, or be a FrameworkElement or FrameworkContentElement derived class, in order to support creation of a XAML namescope on its instances.

De même, pour tout élément qui n’est pas chargé et traité par un processeur XAML, la portée de nom XAML pour l’objet n’est pas créée ou initialisée par défaut.Also, for any element that is not loaded and processed by a XAML processor, the XAML namescope for the object is not created or initialized by default. Vous devez créer explicitement une nouvelle portée de nom XAML pour tout objet dans lequel vous prévoyez d’inscrire des noms par la suite.You must explicitly create a new XAML namescope for any object that you intend to register names into subsequently. Pour créer une portée de code XAML, vous appelez la SetNameScope méthode statique.To create a XAML namescope, you call the static SetNameScope method. Spécifiez l’objet qui le possédera comme dependencyObject paramètre et un nouvel NameScope appel de constructeur comme value paramètre.Specify the object that will own it as the dependencyObject parameter, and a new NameScope constructor call as the value parameter.

Si l’objet fourni comme dependencyObject pour SetNameScope n’est pas une INameScope implémentation, ou si l' FrameworkElement FrameworkContentElement appel RegisterName de sur n’importe quel élément enfant n’aura aucun effet.If the object provided as dependencyObject for SetNameScope is not a INameScope implementation, FrameworkElement or FrameworkContentElement, calling RegisterName on any child elements will have no effect. Si vous ne parvenez pas à créer la nouvelle portée de code XAML explicitement, les appels à RegisterName lèveront une exception.If you fail to create the new XAML namescope explicitly, then calls to RegisterName will raise an exception.

Pour obtenir un exemple d’utilisation des API de portée de nom XAML dans du code, consultez Définir une portée de nom.For an example of using XAML namescope APIs in code, see Define a Name Scope.

Portées de nom XAML dans les styles et les modèlesXAML Namescopes in Styles and Templates

Les styles et les modèles dans WPFWPF permettent de réutiliser et de réappliquer le contenu d’une manière simple.Styles and templates in WPFWPF provide the ability to reuse and reapply content in a straightforward way. Toutefois, les styles et les modèles peuvent également inclure des éléments avec des noms XAML définis au niveau d’un modèle.However, styles and templates might also include elements with XAML names defined at the template level. Ce même modèle peut être utilisé plusieurs fois dans une page.That same template might be used multiple times in a page. Pour cette raison, les styles et les modèles définissent tous deux leurs propres portées de nom XAML, indépendamment de l’emplacement où le style ou le modèle est appliqué dans une arborescence d’objets.For this reason, styles and templates both define their own XAML namescopes, independent of whatever location in an object tree where the style or template is applied.

Prenons l’exemple suivant :Consider the following example:

<Page
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  >
  <Page.Resources>
    <ControlTemplate x:Key="MyButtonTemplate" TargetType="{x:Type Button}">
      <Border BorderBrush="Red" Name="TheBorder" BorderThickness="2">
        <ContentPresenter/>
      </Border>      
    </ControlTemplate>
  </Page.Resources>
  <StackPanel>
    <Button Template="{StaticResource MyButtonTemplate}">My first button</Button>
    <Button Template="{StaticResource MyButtonTemplate}">My second button</Button>
  </StackPanel>
</Page>

Ici, le même modèle est appliqué à deux boutons différents.Here, the same template is applied to two different buttons. Si les modèles n’avaient pas de portées de nom XAML discrètes, le nom TheBorder utilisé dans le modèle provoquerait un conflit de noms dans la portée de nom XAML.If templates did not have discrete XAML namescopes, the TheBorder name used in the template would cause a name collision in the XAML namescope. Chaque instanciation du modèle a sa propre portée de nom XAML. Ainsi, dans cet exemple, la portée de nom XAML de chaque modèle instancié contient un et un seul nom.Each instantiation of the template has its own XAML namescope, so in this example each instantiated template's XAML namescope would contain exactly one name.

Les styles définissent également leur propre portée de nom XAML, principalement pour que des noms particuliers puissent être affectés aux différentes parties des plans conceptuels.Styles also define their own XAML namescope, mostly so that parts of storyboards can have particular names assigned. Ces noms activent des comportements spécifiques des contrôles qui ciblent les éléments de ce nom, même si le modèle a été redéfini dans le cadre de la personnalisation du contrôle.These names enable control specific behaviors that will target elements of that name, even if the template was re-defined as part of control customization.

En raison des portées de nom XAML distinctes, rechercher des éléments nommés dans un modèle est plus difficile que rechercher dans une page un élément nommé non basé sur un modèle.Because of the separate XAML namescopes, finding named elements in a template is more challenging than finding a non-templated named element in a page. Vous devez d’abord déterminer le modèle appliqué, en obtenant la Template valeur de propriété du contrôle où le modèle est appliqué.You first need to determine the applied template, by getting the Template property value of the control where the template is applied. Ensuite, vous appelez la version de modèle de FindName , en passant le contrôle où le modèle a été appliqué comme deuxième paramètre.Then, you call the template version of FindName, passing the control where the template was applied as the second parameter.

Si vous êtes un auteur de contrôle et que vous générez une Convention où un élément nommé particulier dans un modèle appliqué est la cible d’un comportement défini par le contrôle lui-même, vous pouvez utiliser la GetTemplateChild méthode à partir du code d’implémentation de votre contrôle.If you are a control author and you are generating a convention where a particular named element in an applied template is the target for a behavior that is defined by the control itself, you can use the GetTemplateChild method from your control implementation code. La GetTemplateChild méthode est protégée, donc seul l’auteur du contrôle y a accès.The GetTemplateChild method is protected, so only the control author has access to it.

Si vous travaillez à partir d’un modèle et que vous devez accéder à la portée de code XAML où le modèle est appliqué, récupérez la valeur de TemplatedParent , puis appelez FindName ici.If you are working from within a template, and need to get to the XAML namescope where the template is applied, get the value of TemplatedParent, and then call FindName there. Un exemple de travail à l’intérieur du modèle est l’écriture de l’implémentation du gestionnaire d’événements là où l’événement est déclenché à partir d’un élément dans un modèle appliqué.An example of working within the template would be if you are writing the event handler implementation where the event will be raised from an element in an applied template.

FrameworkElement a FindName RegisterName les UnregisterName méthodes et.FrameworkElement has FindName, RegisterName and UnregisterName methods. Si l’objet sur lequel vous appelez ces méthodes a une portée de nom XAML, les méthodes font les appels au sein des méthodes de la portée de nom XAML appropriée.If the object you call these methods on owns a XAML namescope, the methods call into the methods of the relevant XAML namescope. Sinon, l’élément parent est vérifié pour voir s’il détient une portée de nom XAML, et ce processus continue de manière récursive jusqu’à ce qu’une portée de nom XAML soit trouvée (en raison du comportement du processeur XAML, la présence d’une portée de nom XAML à la racine est garantie).Otherwise, the parent element is checked to see if it owns a XAML namescope, and this process continues recursively until a XAML namescope is found (because of the XAML processor behavior, there is guaranteed to be a XAML namescope at the root). FrameworkContentElement a des comportements analogues, à l’exception du fait qu’aucune n' FrameworkContentElement aura jamais une portée de code XAML.FrameworkContentElement has analogous behaviors, with the exception that no FrameworkContentElement will ever own a XAML namescope. Les méthodes existent sur FrameworkContentElement afin que les appels puissent être transférés finalement à un FrameworkElement élément parent.The methods exist on FrameworkContentElement so that the calls can be forwarded eventually to a FrameworkElement parent element.

SetNameScope est utilisé pour mapper une nouvelle portée de code XAML à un objet existant.SetNameScope is used to map a new XAML namescope to an existing object. Vous pouvez appeler SetNameScope plusieurs fois pour réinitialiser ou effacer la portée de code XAML, mais cela n’est pas une utilisation courante.You can call SetNameScope more than once in order to reset or clear the XAML namescope, but that is not a common usage. En outre, GetNameScope n’est généralement pas utilisé à partir du code.Also, GetNameScope is not typically used from code.

Implémentations de portée de nom XAMLXAML Namescope Implementations

Les classes suivantes implémentent INameScope directement :The following classes implement INameScope directly:

ResourceDictionary n’utilise pas de noms ou de portées de nom XAML ; elle utilise à la place des clés, car il s’agit d’une implémentation de dictionnaire.ResourceDictionary does not use XAML names or namescopes ; it uses keys instead, because it is a dictionary implementation. La seule raison ResourceDictionary pour laquelle implémente est de pouvoir INameScope lever des exceptions au code utilisateur qui permettent de clarifier la distinction entre une véritable portée de code XAML et la manière dont un ResourceDictionary gère les clés, ainsi que de s’assurer que les portées de code XAML ne sont pas appliquées à un ResourceDictionary par éléments parents.The only reason that ResourceDictionary implements INameScope is so it can raise exceptions to user code that help clarify the distinction between a true XAML namescope and how a ResourceDictionary handles keys, and also to assure that XAML namescopes are not applied to a ResourceDictionary by parent elements.

FrameworkTemplate et Style implémentent INameScope via des définitions d’interface explicites.FrameworkTemplate and Style implement INameScope through explicit interface definitions. Les implémentations explicites permettent à ces portées de code XAML de se comporter de façon conventionnelle quand elles sont accessibles via l' INameScope interface, ce qui explique comment les portées de code XAML sont communiquées par les WPFWPF processus internes.The explicit implementations allow these XAML namescopes to behave conventionally when they are accessed through the INameScope interface, which is how XAML namescopes are communicated by WPFWPF internal processes. Toutefois, les définitions d’interface explicites ne font pas partie de la surface d’API conventionnelle de FrameworkTemplate et Style , parce que vous devez rarement appeler les INameScope méthodes sur FrameworkTemplate et Style directement, et utiliser à la place une autre API telle que GetTemplateChild .But the explicit interface definitions are not part of the conventional API surface of FrameworkTemplate and Style, because you seldom need to call the INameScope methods on FrameworkTemplate and Style directly, and instead would use other API such as GetTemplateChild.

Les classes suivantes définissent leur propre portée de code XAML, en utilisant la System.Windows.NameScope classe d’assistance et en se connectant à son implémentation de portée de code XAML par le biais de la NameScope.NameScope propriété jointe :The following classes define their own XAML namescope, by using the System.Windows.NameScope helper class and connecting to its XAML namescope implementation through the NameScope.NameScope attached property:

Voir aussiSee also