Metadados de propriedade da dependênciaDependency Property Metadata

O Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) sistema de propriedade inclui um sistema de relatórios de metadados que vai além do que pode ser relatado sobre uma propriedade através de reflexão ou características gerais de tempo de execução da linguagem comum (CLR).The Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) property system includes a metadata reporting system that goes beyond what can be reported about a property through reflection or general common language runtime (CLR) characteristics. Os metadados de uma propriedade de dependência também podem ser atribuídos exclusivamente pela classe que define uma propriedade de dependência, podem ser alterados quando a propriedade de dependência é adicionada a uma classe diferente e podem ser substituídos especificamente por todas as classes derivadas que herdam a propriedade de dependência da classe base de definição.Metadata for a dependency property can also be assigned uniquely by the class that defines a dependency property, can be changed when the dependency property is added to a different class, and can be specifically overridden by all derived classes that inherit the dependency property from the defining base class.

Pré-requisitosPrerequisites

Este tópico pressupõe que você entende as propriedades de dependência da perspectiva de um consumidor de propriedades de dependência existentes nas classes Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) e que leu a Visão geral das propriedades de dependência.This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) classes, and have read the Dependency Properties Overview. Para seguir os exemplos deste tópico, você também deve ter noções básicas de XAMLXAML e saber como escrever aplicativos do WPFWPF.In order to follow the examples in this topic, you should also understand XAMLXAML and know how to write WPFWPF applications.

Como os metadados de propriedade de dependência são usadosHow Dependency Property Metadata is Used

Os metadados de propriedade de dependência existem como um objeto que pode ser consultado para examinar as características de uma propriedade de dependência.Dependency property metadata exists as an object that can be queried to examine the characteristics of a dependency property. Esses metadados também são acessados frequentemente pelo sistema de propriedades enquanto ele processa qualquer propriedade de dependência.This metadata is also accessed frequently by the property system as it processes any given dependency property. O objeto de metadados de uma propriedade de dependência pode conter os seguintes tipos de informações:The metadata object for a dependency property can contain the following types of information:

  • Valor padrão para a propriedade de dependência, se nenhum outro valor pode ser determinado para a propriedade de dependência por valor local, estilo, herança, etc. Para uma discussão minuciosa sobre como os valores padrão participam da precedência usada pelo sistema de propriedades ao atribuir valores para propriedades de dependência, consulte Precedênciade Valor de Propriedade de Dependência .Default value for the dependency property, if no other value can be determined for the dependency property by local value, style, inheritance, etc. For a thorough discussion of how default values participate in the precedence used by the property system when assigning values for dependency properties, see Dependency Property Value Precedence.

  • Referências às implementações de retorno de chamada que afetam os comportamentos de coerção ou de notificação de alteração com base no tipo de proprietário.References to callback implementations that affect coercion or change-notification behaviors on a per-owner-type basis. Observe que esses retornos de chamada são frequentemente definidos com um nível de acesso não público, de modo que obter as referências reais dos metadados geralmente não é possível, a menos que as referências estejam dentro de seu escopo de acesso permitido.Note that these callbacks are often defined with a nonpublic access level, so obtaining the actual references from metadata is generally not possible unless the references are within your permitted access scope. Para obter mais informações sobre os retornos de chamada de propriedade de dependência, consulte Retornos de chamada de propriedade de dependência e validação.For more information on dependency property callbacks, see Dependency Property Callbacks and Validation.

  • Se a propriedade de dependência em questão for considerada uma propriedade de nível de estrutura do WPF, os metadados poderão conter características das propriedades de dependência no nível da estrutura do WPF, que relatam informações e estados de serviço como a lógica da herança de propriedade e do mecanismo de layout no nível da estrutura do WPF.If the dependency property in question is considered to be a WPF framework-level property, the metadata might contain WPF framework-level dependency property characteristics, which report information and state for services such as the WPF framework-level layout engine and property inheritance logic. Para obter mais informações sobre este aspecto dos metadados de propriedade de dependência, consulte Metadados de propriedade de estrutura.For more information on this aspect of dependency property metadata, see Framework Property Metadata.

APIs de metadadosMetadata APIs

O tipo que relata a maioria das informações de PropertyMetadata metadados usadas pelo sistema de propriedade é a classe.The type that reports most of the metadata information used by the property system is the PropertyMetadata class. Instâncias de metadados são especificadas opcionalmente quando as propriedades de dependência são registradas no sistema de propriedades e podem ser especificadas novamente para tipos adicionais que se adicionarem como proprietários ou substituírem os metadados que eles herdam da definição de propriedade de dependência da classe base.Metadata instances are optionally specified when dependency properties are registered with the property system, and can be specified again for additional types that either add themselves as owners or override metadata they inherit from the base class dependency property definition. (Para os casos em que um registro PropertyMetadata de propriedade não especifica metadados, um padrão é criado com valores padrão para essa classe.) Os metadados registrados são PropertyMetadata retornados como GetMetadata quando você chama as várias sobrecargas DependencyObject que recebem metadados de uma propriedade de dependência em uma instância.(For cases where a property registration does not specify metadata, a default PropertyMetadata is created with default values for that class.)The registered metadata is returned as PropertyMetadata when you call the various GetMetadata overloads that get metadata from a dependency property on a DependencyObject instance.

A PropertyMetadata classe é então derivada para fornecer metadados mais específicos para divisões arquitetônicas, como as classes de nível de estrutura wpf.The PropertyMetadata class is then derived from to provide more specific metadata for architectural divisions such as the WPF framework-level classes. UIPropertyMetadataadiciona relatórios FrameworkPropertyMetadata de animação e fornece as propriedades de nível de estrutura do WPF mencionadas na seção anterior.UIPropertyMetadata adds animation reporting, and FrameworkPropertyMetadata provides the WPF framework-level properties mentioned in the previous section. Quando as propriedades de dependência são registradas, PropertyMetadata elas podem ser registradas nessas classes derivadas.When dependency properties are registered, they can be registered with these PropertyMetadata derived classes. Quando os metadados são examinados, o tipo base PropertyMetadata pode potencialmente ser lançado para as classes derivadas para que você possa examinar as propriedades mais específicas.When the metadata is examined, the base PropertyMetadata type can potentially be cast to the derived classes so that you can examine the more specific properties.

Observação

As características da propriedade que FrameworkPropertyMetadata podem ser especificadas são às vezes referidas nesta documentação como "bandeiras".The property characteristics that can be specified in FrameworkPropertyMetadata are sometimes referred to in this documentation as "flags". Quando você cria novas instâncias de metadados para uso em registros de propriedades de dependência FrameworkPropertyMetadataOptions ou substituições de metadados, você especifica esses FrameworkPropertyMetadata valores usando a enumeração flagwise e, em seguida, fornece valores possivelmente concatenados da enumeração ao construtor.When you create new metadata instances for use in dependency property registrations or metadata overrides, you specify these values using the flagwise enumeration FrameworkPropertyMetadataOptions and then you supply possibly concatenated values of the enumeration to the FrameworkPropertyMetadata constructor. No entanto, uma vez construídas, FrameworkPropertyMetadata essas características de opção são expostas dentro de uma série de propriedades booleanas em vez do valor de enumeração de construção.However, once constructed, these option characteristics are exposed within a FrameworkPropertyMetadata as a series of Boolean properties rather than the constructing enumeration value. As propriedades boolianas permitem que você verifique cada condicional, em vez de exigirem que você aplique uma máscara a um valor de enumeração sinalizadora para obter as informações que lhe interessam.The Boolean properties enable you to check each conditional, rather than requiring you to apply a mask to a flagwise enumeration value to get the information you are interested in. O construtor usa o concatenado FrameworkPropertyMetadataOptions para manter razoável o comprimento da assinatura do construtor, enquanto os metadados construídos reais expõem as propriedades discretas para tornar a consulta dos metadados mais intuitiva.The constructor uses the concatenated FrameworkPropertyMetadataOptions in order to keep the length of the constructor signature reasonable, whereas the actual constructed metadata exposes the discrete properties to make querying the metadata more intuitive.

Quando substituir metadados, quando derivar uma classeWhen to Override Metadata, When to Derive a Class

O sistema de propriedades WPFWPF estabeleceu capacidades para alterar algumas características das propriedades de dependência sem exigir que elas sejam totalmente reimplementadas.The WPFWPF property system has established capabilities for changing some characteristics of dependency properties without requiring them to be entirely re-implemented. Isso é feito construindo uma instância diferente dos metadados de propriedade para a propriedade de dependência conforme ela existe em um tipo específico.This is accomplished by constructing a different instance of property metadata for the dependency property as it exists on a particular type. Observe que a maioria das propriedades de dependência existentes não são propriedades virtuais, assim, "reimplementá-las" literalmente nas classes herdadas somente pode ser feito sombreando o membro existente.Note that most existing dependency properties are not virtual properties, so strictly speaking "re-implementing" them on inherited classes could only be accomplished by shadowing the existing member.

Se o cenário que você está tentando habilitar para uma propriedade de dependência em um tipo não pode ser realizado modificando as características das propriedades de dependência existentes, talvez seja necessário criar uma classe derivada e, em seguida, declarar uma propriedade de dependência personalizada na sua classe derivada.If the scenario you are trying to enable for a dependency property on a type cannot be accomplished by modifying characteristics of existing dependency properties, it might then be necessary to create a derived class, and then to declare a custom dependency property on your derived class. Uma propriedade de dependência personalizada se comporta de forma WPFWPF idêntica às propriedades de dependência definidas pelas APIs.A custom dependency property behaves identically to dependency properties defined by the WPFWPF APIs. Para obter mais detalhes sobre propriedades de dependência personalizadas, consulte Propriedades de dependência personalizadas.For more details about custom dependency properties, see Custom Dependency Properties.

Uma característica notável de uma propriedade de dependência que você não pode substituir é seu tipo de valor.One notable characteristic of a dependency property that you cannot override is its value type. Se você estiver herdando uma propriedade de dependência que tenha o comportamento próximo do necessário, mas precisar de um tipo diferente para ela, será necessário implementar uma propriedade de dependência personalizada e talvez vincular as propriedades por meio de conversão de tipos ou outra implementação em sua classe personalizada.If you are inheriting a dependency property that has the approximate behavior you require, but you require a different type for it, you will have to implement a custom dependency property and perhaps link the properties through type conversion or other implementation on your custom class. Além disso, você não ValidateValueCallbackpode substituir um existente, porque esse retorno de chamada existe no próprio campo de registro e não dentro de seus metadados.Also, you cannot replace an existing ValidateValueCallback, because this callback exists in the registration field itself and not within its metadata.

Cenários de alteração de metadados existentesScenarios for Changing Existing Metadata

Se você estiver trabalhando com os metadados de uma propriedade de dependência existente, um cenário comum para alterar os metadados de propriedade de dependência é alterar o valor padrão.If you are working with metadata of an existing dependency property, one common scenario for changing dependency property metadata is to change the default value. Alterar ou adicionar retornos de chamada do sistema de propriedades é um cenário mais avançado.Changing or adding property system callbacks is a more advanced scenario. Você talvez queira fazer isso se sua implementação de uma classe derivada tiver diferentes inter-relações entre as propriedades de dependência.You might want to do this if your implementation of a derived class has different interrelationships between dependency properties. Uma das condicionais de ter um modelo de programação que dá suporte a código e uso declarativo é que as propriedades devem permitir serem definidas em qualquer ordem.One of the conditionals of having a programming model that supports both code and declarative usage is that properties must enable being set in any order. Assim, todas as propriedades dependentes precisam ser definidas Just-In-Time sem contexto e não podem depender de conhecer uma ordem de configuração como pode ser encontrada em um construtor.Thus any dependent properties need to be set just-in-time without context and cannot rely on knowing a setting order such as might be found in a constructor. Para obter mais informações sobre esse aspecto do sistema de propriedades, consulte Retornos de chamada de propriedade de dependência e validação.For more information on this aspect of the property system, see Dependency Property Callbacks and Validation. Observe que os retornos de chamada de validação não fazem parte dos metadados; eles fazem parte do identificador de propriedade de dependência.Note that validation callbacks are not part of the metadata; they are part of the dependency property identifier. Portanto, os retornos de chamada de validação não podem ser alterados substituindo os metadados.Therefore, validation callbacks cannot be changed by overriding the metadata.

Em alguns casos, também convém alterar as opções de metadados de propriedade de nível de estrutura do WPF nas propriedades de dependência existentes.In some cases you might also want to alter the WPF framework-level property metadata options on existing dependency properties. Essas opções comunicam determinadas condicionais conhecidas sobre as propriedades de nível de estrutura do WPF para outros processos de nível de estrutura do WPF, como o sistema de layout.These options communicate certain known conditionals about WPF framework-level properties to other WPF framework-level processes such as the layout system. A definição das opções geralmente é feita apenas ao registrar uma nova propriedade de dependência, mas também é OverrideMetadata AddOwner possível alterar os metadados de propriedade de nível de estrutura do WPF como parte de uma ou chamada.Setting the options is generally done only when registering a new dependency property, but it is also possible to change the WPF framework-level property metadata as part of a OverrideMetadata or AddOwner call. Para obter os valores específicos a serem usados e mais informações, consulte Metadados de propriedade de estrutura.For the specific values to use and more information, see Framework Property Metadata. Para obter mais informações sobre como essas opções devem ser definidas para uma propriedade de dependência recém-registrada, consulte Propriedades de dependência personalizadas.For more information that is pertinent to how these options should be set for a newly registered dependency property, see Custom Dependency Properties.

Substituindo metadadosOverriding Metadata

A finalidade da substituição de metadados é principalmente que você tenha a oportunidade de alterar os vários comportamentos derivados de metadados que são aplicados à propriedade de dependência conforme ela existe no seu tipo.The purpose of overriding metadata is primarily so that you have the opportunity to change the various metadata-derived behaviors that are applied to the dependency property as it exists on your type. As razões para isso são explicadas em mais detalhes na seção Metadados.The reasons for this are explained in more detail in the Metadata section. Para obter mais informações incluindo alguns exemplos de código, consulte Substituir metadados para uma propriedade de dependência.For more information including some code examples, see Override Metadata for a Dependency Property.

Os metadados de propriedade podem ser fornecidosRegisterpara uma propriedade de dependência durante a chamada de registro ( ).Property metadata can be supplied for a dependency property during the registration call (Register). No entanto, em muitos casos, convém fornecer os metadados específicos do tipo da sua classe quando ela herda essa propriedade de dependência.However, in many cases, you might want to provide type-specific metadata for your class when it inherits that dependency property. Você pode fazer isso OverrideMetadata chamando o método.You can do this by calling the OverrideMetadata method. Por exemplo, WPFWPF as APIs, a FrameworkElement classe é o Focusable tipo que registra primeiro a propriedade de dependência.For an example from the WPFWPF APIs, the FrameworkElement class is the type that first registers the Focusable dependency property. Mas Control a classe substitui metadados para que a propriedade de dependência false forneça trueseu próprio valor padrão Focusable inicial, alterando-o de para , e de outra forma reutiliza a implementação original.But the Control class overrides metadata for the dependency property to provide its own initial default value, changing it from false to true, and otherwise re-uses the original Focusable implementation.

Quando você substitui metadados, as diferentes características dos metadados são mescladas ou substituídas.When you override metadata, the different metadata characteristics are either merged or replaced.

Esse comportamento é Mergeimplementado por , e pode ser substituído em classes de metadados derivadas.This behavior is implemented by Merge, and can be overridden on derived metadata classes.

Substituindo metadados de propriedade anexadaOverriding Attached Property Metadata

No WPFWPF, as propriedades anexadas são implementadas como propriedades de dependência.In WPFWPF, attached properties are implemented as dependency properties. Isso significa que elas também têm metadados de propriedade, que as classes individuais podem substituir.This means that they also have property metadata, which individual classes can override. As considerações de escopo para WPFWPF uma propriedade anexada são geralmente que qualquer DependencyObject um pode ter uma propriedade anexada sobre eles.The scoping considerations for an attached property in WPFWPF are generally that any DependencyObject can have an attached property set on them. Portanto, qualquer DependencyObject classe derivada pode substituir os metadados de qualquer propriedade anexada, pois pode ser definido em uma instância da classe.Therefore, any DependencyObject derived class can override the metadata for any attached property, as it might be set on an instance of the class. Você pode substituir os valores padrão, os retornos de chamada ou as propriedades de relatório de características de nível de estrutura do WPF.You can override default values, callbacks, or WPF framework-level characteristic-reporting properties. Se a propriedade anexada for definida em uma instância da sua classe, aquelas características de metadados de propriedade de substituição serão aplicadas.If the attached property is set on an instance of your class, those override property metadata characteristics apply. Por exemplo, você pode substituir o valor padrão, de modo que o valor de substituição seja relatado como o valor da propriedade anexada nas instâncias da sua classe, sempre que a propriedade não é definida de outra forma.For instance, you can override the default value, such that your override value is reported as the value of the attached property on instances of your class, whenever the property is not otherwise set.

Observação

A Inherits propriedade não é relevante para propriedades anexadas.The Inherits property is not relevant for attached properties.

Adicionando uma classe como um proprietário de uma propriedade de dependência existenteAdding a Class as an Owner of an Existing Dependency Property

Uma classe pode se adicionar como proprietária de um imóvel de dependência AddOwner que já foi registrado, usando o método.A class can add itself as an owner of a dependency property that has already been registered, by using the AddOwner method. Isso permite que a classe use uma propriedade de dependência que foi registrada originalmente para um tipo diferente.This enables the class to use a dependency property that was originally registered for a different type. A classe adicionada, normalmente, não é uma classe derivada do tipo que registrou primeiro essa propriedade de dependência como proprietária.The adding class is typically not a derived class of the type that first registered that dependency property as owner. Na verdade, isso permite que sua classe e suas classes derivadas "herdem" uma implementação de propriedade de dependência sem que a classe proprietária original e a classe adicionada estejam na mesma hierarquia de classe verdadeira.Effectively, this allows your class and its derived classes to "inherit" a dependency property implementation without the original owner class and the adding class being in the same true class hierarchy. Além disso, a classe adicionada (e também as classes derivadas) pode fornecer metadados específicos para o tipo da propriedade de dependência original.In addition, the adding class (and all derived classes as well) can then provide type-specific metadata for the original dependency property.

Além de adicionar-se como proprietária por meio de métodos de utilitário do sistema de propriedades, a classe adicionada deve declarar membros públicos adicionais em si mesma para tornar a propriedade de dependência um participante completo do sistema de propriedades com exposição em código e marcação.As well as adding itself as owner through the property system utility methods, the adding class should declare additional public members on itself in order to make the dependency property] a full participant in the property system with exposure to both code and markup. Uma classe que adiciona uma propriedade de dependência existente tem as mesmas responsabilidades que expor o modelo de objeto para essa propriedade de dependência como uma classe que define uma nova propriedade de dependência personalizada.A class that adds an existing dependency property has the same responsibilities as far as exposing the object model for that dependency property as does a class that defines a new custom dependency property. O primeiro membro a ser exposto é um campo identificador de propriedade de dependência.The first such member to expose is a dependency property identifier field. Este campo deve public static readonly ser DependencyPropertyum campo de tipo, que AddOwner é atribuído ao valor de retorno da chamada.This field should be a public static readonly field of type DependencyProperty, which is assigned to the return value of the AddOwner call. O segundo membro a definir é a propriedade "wrapper" de tempo de execução de idioma comum (CLR).The second member to define is the common language runtime (CLR) "wrapper" property. O invólucro torna muito mais conveniente manipular sua propriedade SetValue de dependência em código (você evita chamadas para cada vez, e pode fazer essa chamada apenas uma vez no próprio invólucro).The wrapper makes it much more convenient to manipulate your dependency property in code (you avoid calls to SetValue each time, and can make that call only once in the wrapper itself). O wrapper é implementado igual seria implementado se você estivesse registrando uma propriedade de dependência personalizada.The wrapper is implemented identically to how it would be implemented if you were registering a custom dependency property. Para obter mais informações de como implementar uma propriedade de dependência, consulte Propriedades de dependência personalizadas e Adicionar um tipo de proprietário para uma propriedade de dependência.For more information about implementing a dependency property, see Custom Dependency Properties and Add an Owner Type for a Dependency Property.

AddOwner e propriedades anexadasAddOwner and Attached Properties

Você pode AddOwner solicitar uma propriedade de dependência definida como uma propriedade anexada pela classe proprietário.You can call AddOwner for a dependency property that is defined as an attached property by the owner class. Geralmente o motivo para isso é expor a propriedade anexada anteriormente como uma propriedade de dependência não anexada.Generally the reason for doing this is to expose the previously attached property as a non-attached dependency property. Em seguida, AddOwner você exporá public static readonly o valor de retorno como um campo para uso como identificador de propriedade de dependência e definirá propriedades apropriadas de "invólucro" para que a propriedade apareça na tabela de membros e suporte um uso de propriedade não anexado em sua classe.You then will expose the AddOwner return value as a public static readonly field for use as the dependency property identifier, and will define appropriate "wrapper" properties so that the property appears in the members table and supports a non-attached property usage in your class.

Confira tambémSee also