Ámbitos de nombres XAML de WPFWPF XAML Namescopes

Los ámbitos de nombres XAML son un concepto que identifica objetos que se definen en XAML.XAML namescopes are a concept that identifies objects that are defined in XAML. Los nombres de un ámbito de nombres XAML se pueden usar para establecer relaciones entre los nombres de objetos definidos por XAML y sus equivalentes de instancia en un árbol de objetos.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. Normalmente, los ámbitos de nombres XAML del código administrado de WPFWPF se crean al cargar las distintas raíces de página XAML de una aplicación XAML.Typically, XAML namescopes in WPFWPF managed code are created when loading the individual XAML page roots for a XAML application. Los ámbitos de código XAML como el objeto de programación INameScope se definen mediante la interfaz y también se implementan mediante la clase NameScopepráctica.XAML namescopes as the programming object are defined by the INameScope interface and are also implemented by the practical class NameScope.

Ámbitos de nombres en las aplicaciones XAML cargadasNamescopes in Loaded XAML Applications

En un contexto de programación o de informática más amplio, los conceptos de programación suelen incluir el principio de un identificador o nombre único que se puede usar para obtener acceso a un objeto.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. Para los sistemas que usan identificadores o nombres, el ámbito de nombres define los límites en los que buscará un proceso o técnica si se solicita un objeto con ese nombre, o bien los límites en los que se aplica la unicidad de la identificación de nombres.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. En los ámbitos de nombres XAML se aplican los siguientes principios generales.These general principles are true for XAML namescopes. En WPF, los ámbitos de nombres XAML se crean en el elemento raíz de una página XAML cuando esta se carga.In WPF, XAML namescopes are created on the root element for a XAML page when the page is loaded. Todos los nombres especificados dentro de la página XAML a partir de la raíz de la página se agregan a un ámbito de nombres XAML pertinente.Each name specified within the XAML page starting at the page root is added to a pertinent XAML namescope.

En XAML de WPF, los elementos que son elementos raíz comunes ( Pagecomo y Window) controlan siempre un ámbito de nombres XAML.In WPF XAML, elements that are common root elements (such as Page, and Window) always control a XAML namescope. Si un elemento como FrameworkElement o FrameworkContentElement es el elemento raíz de la página en el marcado, un XAMLXAML procesador Page agrega implícitamente una Page raíz para que pueda proporcionar un ámbito de nombres XAML funcional.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.

Nota

Las acciones de compilación de WPF crean un ámbito de nombres XAML para la producción de XAML, aunque no haya ningún atributo Name o x:Name definido en ningún elemento del marcado de 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 intenta usar el mismo nombre dos veces en cualquier ámbito de nombres XAML, se producirá una excepción.If you try to use the same name twice in any XAML namescope, an exception is raised. Para el XAML de WPF que tiene código subyacente y forma parte de una aplicación compilada, la excepción se produce en tiempo de compilación mediante acciones de compilación de WPF, al crear la clase generada para la página durante la compilación inicial del marcado.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. Para el XAML que no está compilado por el marcado mediante ninguna acción de compilación, las excepciones relacionadas con algún error de ámbito de nombres XAML podrían producirse al cargar el 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. Los diseñadores de XAML también pueden prever los errores de ámbito de nombres XAML en tiempo de diseño.XAML designers might also anticipate XAML namescope issues at design time.

Agregar objetos a los árboles de objetos en tiempo de ejecuciónAdding Objects to Runtime Object Trees

El momento en que se analiza el XAML representa el momento en el que se crea y se define un ámbito de nombres XAML de WPF.The moment that XAML is parsed represents the moment in time that a WPF XAML namescope is created and defined. Si agrega un objeto a un árbol de objetos después de haber analizado el XAML que generó el árbol, los valores Name o x:Name del objeto nuevo no actualizarán automáticamente la información de un ámbito de nombres 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. Para agregar un nombre a un objeto en un ámbito de nombres XAML de WPF después de cargar XAML, debe llamar a la RegisterName implementación adecuada de en el objeto que define el ámbito de nombres XAML, que suele ser la raíz de la página 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 el nombre no está registrado, no se puede hacer referencia al objeto agregado por nombre a través de FindNamemétodos como, y no se puede usar ese nombre para el destino de la animación.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.

El escenario más común para los desarrolladores de aplicaciones es que RegisterName usará para registrar nombres en el ámbito de nombres XAML en la raíz actual de la página.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. RegisterNameforma parte de un escenario importante para los guiones gráficos que tienen como destino objetos para animaciones.RegisterName is part of an important scenario for storyboards that target objects for animations. Para obtener más información, consulte Información general sobre objetos Storyboard.For more information, see Storyboards Overview.

Si llama RegisterName a en un objeto que no es el objeto que define el ámbito de nombres XAML, el nombre todavía se registra en el ámbito de nombres XAML en el que se mantiene el objeto que RegisterName realiza la llamada, como si hubiera llamado en el objeto que define el ámbito de nombres XAML.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.

Ámbitos de nombres XAML en el códigoXAML Namescopes in Code

Puede crear y usar ámbitos de nombres XAML en el código.You can create and then use XAML namescopes in code. Las API y los conceptos implicados en la creación de ámbitos de nombres XAML son los mismos, incluso para un uso de código puro, ya que el procesador XAML de WPFWPF usa estas API y estos conceptos cuando procesa el XAML.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. Los conceptos y las API existen principalmente para poder buscar objetos por nombre dentro de un árbol de objetos que se suele definir parcial o completamente 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.

En el caso de las aplicaciones que se crean mediante programación y no desde XAML cargado, el objeto que define un ámbito INameScopede nombres XAML debe FrameworkElement implementar FrameworkContentElement , o ser una clase derivada, para admitir la creación de un ámbito de nombres XAML en su Stance.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.

Además, para cualquier elemento que no se haya cargado y procesado con un procesador XAML, el ámbito de nombres XAML del objeto no se crea ni se inicializa de forma predeterminada.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. Debe crear explícitamente un ámbito de nombres XAML para cualquier objeto en el que después vaya a registrar nombres.You must explicitly create a new XAML namescope for any object that you intend to register names into subsequently. Para crear un ámbito de nombres XAML, se llama SetNameScope al método estático.To create a XAML namescope, you call the static SetNameScope method. Especifique el objeto que lo poseerá como dependencyObject parámetro y una nueva NameScope llamada de constructor como value parámetro.Specify the object that will own it as the dependencyObject parameter, and a new NameScope constructor call as the value parameter.

Si el objeto proporcionado como dependencyObject para SetNameScope no es una INameScope implementación de FrameworkElement , FrameworkContentElemento, RegisterName la llamada a en cualquier elemento secundario no tendrá ningún efecto.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 no se puede crear el nuevo ámbito de nombres XAML explícitamente, RegisterName las llamadas a producirán una excepción.If you fail to create the new XAML namescope explicitly, then calls to RegisterName will raise an exception.

Para ver un ejemplo de cómo usar las API de ámbito de nombres XAML en el código, consulte Definir un ámbito de nombres.For an example of using XAML namescope APIs in code, see Define a Name Scope.

Ámbitos de nombres XAML en estilos y plantillasXAML Namescopes in Styles and Templates

Los estilos y las plantillas de WPFWPF ofrecen la posibilidad de reutilizar y volver a aplicar el contenido de una manera sencilla,Styles and templates in WPFWPF provide the ability to reuse and reapply content in a straightforward way. aunque también pueden incluir elementos con nombres XAML definidos en el nivel de la plantilla.However, styles and templates might also include elements with XAML names defined at the template level. Esa misma plantilla se puede usar varias veces en una página.That same template might be used multiple times in a page. Por este motivo, tanto los estilos como las plantillas definen sus propios ámbitos de nombres XAML, independientemente de la ubicación en un árbol de objetos en la que se aplique el estilo o plantilla.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.

Considere el ejemplo siguiente: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>

En este caso, se aplica la misma plantilla a dos botones diferentes.Here, the same template is applied to two different buttons. Si las plantillas no tuvieran ámbitos de nombres XAML discretos, el nombre TheBorder usado en la plantilla provocaría un conflicto de nombres en el ámbito de nombres 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. Todas las instancias de la plantilla tienen su propio ámbito de nombres XAML, por lo que, en este ejemplo, el ámbito de nombres XAML de todas las plantillas de instancia contendrían exactamente un nombre.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.

Los estilos también definen su propio ámbito de nombres XAML, sobre todo para que las partes de los guiones gráficos puedan tener asignados nombres concretos.Styles also define their own XAML namescope, mostly so that parts of storyboards can have particular names assigned. Estos nombres permiten que haya comportamientos específicos de controles destinados a elementos con ese nombre, incluso si la plantilla se ha vuelto a definir como parte de la personalización de controles.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.

Debido a los ámbitos de nombres XAML independientes, resulta más difícil buscar elementos con nombre en una plantilla que buscar un elemento con nombre y sin plantilla en una página.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. En primer lugar, debe determinar la plantilla aplicada, obteniendo el Template valor de propiedad del control al que se aplica la plantilla.You first need to determine the applied template, by getting the Template property value of the control where the template is applied. A continuación, se llama a la versión FindNamede plantilla de, pasando el control en el que se aplicó la plantilla como segundo parámetro.Then, you call the template version of FindName, passing the control where the template was applied as the second parameter.

Si es un autor de controles y está generando una Convención en la que un elemento con nombre determinado en una plantilla aplicada es el destino de un comportamiento definido por el propio control, puede usar el GetTemplateChild método desde el código de implementación del control.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. El GetTemplateChild método está protegido, por lo que solo el autor del control tiene acceso a él.The GetTemplateChild method is protected, so only the control author has access to it.

Si está trabajando desde dentro de una plantilla, y necesita obtener acceso al ámbito de nombres XAML donde se aplica la plantilla, obtenga el valor TemplatedParentde y, a FindName continuación, llame a ahí.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 ejemplo de trabajo dentro de la plantilla sería escribir la implementación del controlador de eventos donde se generará el evento desde un elemento de una plantilla aplicada.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.

FrameworkElementtiene FindNamelos RegisterName métodos UnregisterName , y.FrameworkElement has FindName, RegisterName and UnregisterName methods. Si el objeto en el que llama a estos métodos tiene un ámbito de nombres XAML, los métodos llaman a los métodos del ámbito de nombres XAML relevante.If the object you call these methods on owns a XAML namescope, the methods call into the methods of the relevant XAML namescope. De lo contrario, se comprueba el elemento primario para ver si tiene un ámbito de nombres XAML. Este proceso continúa de forma recursiva hasta que se encuentra un ámbito de nombres XAML (debido al comportamiento del procesador XAML, se garantiza que haya un ámbito de nombres XAML en la raíz).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). FrameworkContentElementtiene comportamientos análogos, con la excepción de FrameworkContentElement que nunca tendrá un ámbito de nombres XAML.FrameworkContentElement has analogous behaviors, with the exception that no FrameworkContentElement will ever own a XAML namescope. Los métodos existen en FrameworkContentElement para que las llamadas se puedan reenviar finalmente a un FrameworkElement elemento primario.The methods exist on FrameworkContentElement so that the calls can be forwarded eventually to a FrameworkElement parent element.

SetNameScopese utiliza para asignar un nuevo ámbito de nombres XAML a un objeto existente.SetNameScope is used to map a new XAML namescope to an existing object. Puede llamar SetNameScope a más de una vez para restablecer o borrar el ámbito de nombres XAML, pero esto no es un uso común.You can call SetNameScope more than once in order to reset or clear the XAML namescope, but that is not a common usage. Además, GetNameScope no se suele usar desde el código.Also, GetNameScope is not typically used from code.

Implementaciones de ámbito de nombres XAMLXAML Namescope Implementations

Las clases siguientes implementan INameScope directamente:The following classes implement INameScope directly:

ResourceDictionaryno utiliza nombres o ámbitos de nombres XAML. en su lugar, utiliza claves, ya que es una implementación de diccionario.ResourceDictionary does not use XAML names or namescopes ; it uses keys instead, because it is a dictionary implementation. El único motivo por ResourceDictionary el que INameScope implementa es que puede generar excepciones al código de usuario que ayuden a clarificar la distinción entre un ámbito de ResourceDictionary nombres XAML verdadero y cómo controla las claves, además de garantizar que los ámbitos de nombres XAML no se aplican a un ResourceDictionary por elementos primarios.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.

FrameworkTemplatee Style implementan INameScope a través de definiciones de interfaz explícitas.FrameworkTemplate and Style implement INameScope through explicit interface definitions. Las implementaciones explícitas permiten que estos ámbitos de código XAML se comporten de forma convencional INameScope cuando se accede a ellos a través de la interfaz, WPFWPF que es la forma en que los procesos internos comunican los ámbitos de código XAML.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. Sin embargo, las definiciones de interfaz explícitas no forman parte de la FrameworkTemplate superficie Stylede la API convencional de y, porque INameScope rara vez es Style necesario llamar a los métodos en FrameworkTemplate y directamente, y en su lugar usaría otra API GetTemplateChildcomo.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.

Las siguientes clases definen su propio ámbito de nombres XAML, mediante System.Windows.NameScope el uso de la clase auxiliar y la conexión a su implementación NameScope.NameScope del ámbito de nombres XAML a través de la propiedad adjunta: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:

Vea tambiénSee also