Metadados da propriedade Framework (WPF .NET)

  • Artigo

Você pode definir opções de metadados de propriedade de estrutura para propriedades de dependência no nível de estrutura do Windows Presentation Foundation (WPF). A designação de nível de estrutura do WPF se aplica quando APIs de apresentação e executáveis do WPF manipulam renderização e associação de dados. APIs de apresentação e executáveis consultam o FrameworkPropertyMetadata de uma propriedade de dependência.

Importante

A documentação do Guia da Área de Trabalho para .NET 7 e .NET 6 está em construção.

Pré-requisitos

O artigo pressupõe um conhecimento básico das propriedades de dependência e que você leu Visão geral das propriedades de dependência. Para seguir os exemplos neste artigo, é útil se você estiver familiarizado com XAML (Extensible Application Markup Language) e souber como escrever aplicativos WPF.

Categorias de metadados de propriedade do Framework

FrameworkPropertyMetadata enquadra-se nestas categorias:

  • Metadados que afetam o layout de um elemento, especificamente os AffectsArrangesinalizadores , AffectsMeasuree AffectsRender metadados. Você pode definir esses sinalizadores se sua implementação de propriedade de dependência afetar um aspecto visual e você estiver implementando MeasureOverride ou ArrangeOverride em sua classe. Os MeasureOverride métodos e fornecem informações de renderização e ArrangeOverride comportamento específicos da implementação para o sistema de layout. Quando AffectsArrange, , ou AffectsRender são definidos como true nos metadados de uma propriedade de dependência e seu valor efetivo é alterado, AffectsMeasureo sistema de propriedades WPF iniciará uma solicitação para invalidar os elementos visuais do elemento para disparar um redesenho.

  • Metadados que afetam o layout do elemento pai de um elemento, especificamente os AffectsParentArrange sinalizadores e AffectsParentMeasure metadados. Exemplos de propriedades de dependência do WPF que definem esses sinalizadores são FixedPage.Left e Paragraph.KeepWithNext.

  • Metadados de herança de valor de propriedade, especificamente os Inherits sinalizadores e OverridesInheritanceBehavior metadados. Por padrão, as propriedades de dependência não herdam valores. OverridesInheritanceBehavior permite que o caminho da herança também viaje para uma árvore visual, o que é necessário para alguns cenários de composição de controle. Para obter mais informações, consulte Herança de valor de propriedade.

    Observação

    O termo "herda" no contexto de valores de propriedade é específico para propriedades de dependência e não se relaciona diretamente a tipos de código gerenciado e herança de membro por meio de tipos derivados. No contexto das propriedades de dependência, isso significa que os elementos filho podem herdar valores de propriedade de dependência de elementos pai.

  • Metadados de vinculação de dados, especificamente os BindsTwoWayByDefault sinalizadores e IsNotDataBindable metadados. Por padrão, as propriedades de dependência na estrutura WPF oferecem suporte à vinculação unidirecional. Considere definir a vinculação bidirecional como padrão para propriedades que relatam estado e são modificáveis por ação do usuário, por exemplo IsSelected. Além disso, considere definir a vinculação bidirecional como padrão quando os usuários de um controle esperam que uma propriedade a implemente, por exemplo , TextBox.Text. BindsTwoWayByDefault afeta apenas o modo de vinculação padrão. Para editar a direção do fluxo de dados de uma associação, defina Binding.Mode. Você pode usar IsNotDataBindable para desabilitar a vinculação de dados quando não houver nenhum caso de uso para isso. Para obter mais informações sobre associações de dados, consulte Visão geral da vinculação de dados.

  • Registro no diário de metadados, especificamente o sinalizador de Journal metadados. O valor padrão do sinalizador é apenas true para algumas propriedades de Journal dependência, como SelectedIndex. Os controles de entrada do usuário devem definir o Journal sinalizador para propriedades cujos valores contêm seleções de usuário que precisam ser armazenadas. O Journal sinalizador é lido por aplicativos ou serviços que oferecem suporte ao registro no diário, incluindo serviços de registro no diário do WPF. Para obter informações sobre como armazenar etapas de navegação, consulte Visão geral da navegação.

FrameworkPropertyMetadata deriva diretamente do UIPropertyMetadata, e implementa os sinalizadores discutidos aqui. A menos que definido especificamente, FrameworkPropertyMetadata os sinalizadores têm um valor padrão de false.

Leitura do FrameworkPropertyMetadata

Para recuperar metadados de uma propriedade de dependência, chame GetMetadata o DependencyProperty identificador. A GetMetadata chamada retorna um PropertyMetadata objeto. Se você precisar consultar os valores de metadados da estrutura convertidos PropertyMetadata em FrameworkPropertyMetadata.

Especificando FrameworkPropertyMetadata

Ao registrar uma propriedade de dependência, você tem a opção de criar e atribuir metadados a ela. O objeto de metadados que você atribui pode ser PropertyMetadata ou uma de suas classes derivadas, como FrameworkPropertyMetadata. Escolha FrameworkPropertyMetadata propriedades de dependência que dependem de APIs de apresentação WPF e executáveis para renderização e associação de dados. Uma opção mais avançada é derivar de para criar uma classe de relatório de FrameworkPropertyMetadata metadados personalizada com mais sinalizadores. Ou, você pode usar UIPropertyMetadata para propriedades não estrutural que afetam a renderização da interface do usuário.

Embora as opções de metadados sejam normalmente definidas durante o registro de uma nova propriedade de dependência, você pode reespecificá-las em OverrideMetadata ou AddOwner chamadas. Ao substituir metadados, sempre substitua pelo mesmo tipo de metadados que foi usado durante o registro de propriedade.

As características de propriedade que são expostas por FrameworkPropertyMetadata às vezes são chamadas de sinalizadores. Se você estiver criando uma FrameworkPropertyMetadata instância, há duas maneiras de preencher valores de sinalizador:

  1. Defina os sinalizadores em uma instância do FrameworkPropertyMetadataOptions tipo de enumeração. FrameworkPropertyMetadataOptions permite especificar sinalizadores de metadados na combinação OR bit a bit. Em seguida, instancie FrameworkPropertyMetadata usando um construtor que tenha um FrameworkPropertyMetadataOptions parâmetro e passe em sua FrameworkPropertyMetadataOptions instância. Para alterar sinalizadores de metadados depois de passar FrameworkPropertyMetadataOptions para o FrameworkPropertyMetadata construtor, altere a propriedade correspondente na nova FrameworkPropertyMetadata instância. Por exemplo, se você definir o FrameworkPropertyMetadataOptions.NotDataBindable sinalizador, poderá desfazer isso definindo FrameworkPropertyMetadata.IsNotDataBindable como false.

  2. Instancie FrameworkPropertyMetadata usando um construtor que não tenha um FrameworkPropertyMetadataOptions parâmetro e defina os sinalizadores aplicáveis Boolean em FrameworkPropertyMetadata. Defina valores de sinalizador antes de associar sua FrameworkPropertyMetadata instância a uma propriedade de dependência, caso contrário, você obterá um InvalidOperationExceptionarquivo .

Comportamento de substituição de metadados

Quando você substitui os metadados da propriedade da estrutura, os valores de metadados alterados substituem ou são mesclados com os valores originais:

  • Para um PropertyChangedCallback, a lógica de mesclagem padrão retém valores anteriores PropertyChangedCallback em uma tabela e todos são invocados em uma alteração de propriedade. A ordem de retorno de chamada é determinada pela profundidade da classe, onde um retorno de chamada registrado pela classe base na hierarquia seria executado primeiro. Os retornos de chamada herdados são executados apenas uma vez e pertencem à classe que os adicionou aos metadados.

  • Para um DefaultValue, o novo valor substituirá o valor padrão existente. Se você não especificar um DefaultValue nos metadados de substituição e se o existente FrameworkPropertyMetadata tiver o Inherits sinalizador definido, o valor padrão virá do ancestral mais próximo especificado DefaultValue nos metadados.

  • Para um , o novo valor substituirá um CoerceValueCallbackvalor existente CoerceValueCallback . Se você não especificar um nos metadados de substituição, o valor virá do ancestral mais próximo na cadeia de herança que especificou um CoerceValueCallbackCoerceValueCallback.

  • Para FrameworkPropertyMetadata sinalizadores não herdados, você pode substituir o valor padrão false por um true valor. No entanto, você só pode substituir um valor por um falsetrue valor para Inherits, Journal, OverridesInheritanceBehaviore SubPropertiesDoNotAffectRender.

Observação

A lógica de mesclagem padrão é implementada Merge pelo método. Você pode especificar a lógica de mesclagem personalizada em uma classe derivada que herda uma propriedade de dependência, substituindo Merge essa classe.

Confira também