Metadati delle proprietà framework (WPF .NET)

  • Articolo

È possibile impostare le opzioni dei metadati delle proprietà del framework framework per le proprietà di dipendenza a livello di framework Windows Presentation Foundation (WPF). La designazione del livello del framework WPF si applica quando le API di presentazione WPF e i file eseguibili gestiscono il rendering e il data binding. Le API di presentazione e i file eseguibili eseguono query su FrameworkPropertyMetadata di una proprietà di dipendenza.

Importante

La documentazione di Desktop Guide per .NET 7 e .NET 6 è in fase di costruzione.

Prerequisiti

L'articolo presuppone una conoscenza di base delle proprietà di dipendenza e che si abbia letto Panoramica delle proprietà di dipendenza. Per seguire gli esempi in questo articolo, è utile se si ha familiarità con Extensible Application Markup Language (XAML) e si sa come scrivere applicazioni WPF.

Categorie di metadati delle proprietà del framework

FrameworkPropertyMetadata rientra in queste categorie:

  • Metadati che influiscono sul layout di un elemento, in particolare i AffectsArrangeflag di metadati , AffectsMeasuree AffectsRender . È possibile impostare questi flag se l'implementazione della proprietà di dipendenza influisce su un aspetto visivo e si sta implementando MeasureOverride o ArrangeOverride nella classe. I MeasureOverride metodi e ArrangeOverride forniscono informazioni sul comportamento specifico dell'implementazione e sul rendering nel sistema di layout. Quando AffectsArrange, AffectsMeasureo AffectsRender sono impostati su true nei metadati di una proprietà di dipendenza e il relativo valore effettivo cambia, il sistema di proprietà WPF avvierà una richiesta di invalidare gli oggetti visivi dell'elemento per attivare una ridisegna.

  • Metadati che influiscono sul layout dell'elemento padre di un elemento, in particolare i AffectsParentArrange flag di metadati e AffectsParentMeasure . Esempi di proprietà di dipendenza WPF che impostano questi flag sono FixedPage.Left e Paragraph.KeepWithNext.

  • Metadati di ereditarietà dei valori della proprietà, in particolare i Inherits flag di metadati e OverridesInheritanceBehavior . Per impostazione predefinita, le proprietà di dipendenza non ereditano i valori. OverridesInheritanceBehavior consente al percorso di ereditarietà di spostarsi anche in una struttura ad albero visuale, necessaria per alcuni scenari di composizione dei controlli. Per altre informazioni, vedere Ereditarietà dei valori delle proprietà.

    Nota

    Il termine "eredita" nel contesto dei valori delle proprietà è specifico delle proprietà di dipendenza e non è direttamente correlato ai tipi di codice gestito e all'ereditarietà dei membri tramite tipi derivati. Nel contesto delle proprietà di dipendenza, significa che gli elementi figlio possono ereditare i valori delle proprietà di dipendenza dagli elementi padre.

  • Metadati di data binding, in particolare i BindsTwoWayByDefault flag di metadati e IsNotDataBindable . Per impostazione predefinita, le proprietà di dipendenza nel framework WPF supportano l'associazione unidirezionale. È consigliabile impostare l'associazione bidirezionale come predefinita per le proprietà che segnalano lo stato e sono modificabili dall'azione dell'utente, ad esempio IsSelected. È inoltre consigliabile impostare l'associazione bidirezionale come predefinita quando gli utenti di un controllo prevedono l'implementazione di una proprietà, ad esempio TextBox.Text. BindsTwoWayByDefault influisce solo sulla modalità di associazione predefinita. Per modificare la direzione del flusso di dati di un'associazione, impostare Binding.Mode. È possibile usare IsNotDataBindable per disabilitare il data binding quando non è presente alcun caso d'uso. Per altre informazioni sui data binding, vedere Panoramica del data binding.

  • Inserimento nel journal dei metadati, in particolare il flag di Journal metadati. Il valore predefinito del Journal flag è solo true per alcune proprietà di dipendenza, ad esempio SelectedIndex. I controlli di input utente devono impostare il Journal flag per le proprietà i cui valori contengono selezioni utente che devono essere archiviate. Il Journal flag viene letto da applicazioni o servizi che supportano l'inserimento nel journal, inclusi i servizi di journaling WPF. Per informazioni sull'archiviazione dei passaggi di spostamento, vedere Panoramica della navigazione.

FrameworkPropertyMetadata deriva direttamente da UIPropertyMetadatae implementa i flag descritti qui. A meno che non vengano impostati in modo specifico, FrameworkPropertyMetadata i flag hanno un valore predefinito .false

Lettura di FrameworkPropertyMetadata

Per recuperare i metadati per una proprietà di dipendenza, chiamare GetMetadata sull'identificatore DependencyProperty . La GetMetadata chiamata restituisce un PropertyMetadata oggetto . Se è necessario eseguire query sui valori dei metadati del framework per eseguire il cast PropertyMetadata a FrameworkPropertyMetadata.

Specifica di FrameworkPropertyMetadata

Quando si registra una proprietà di dipendenza, è possibile creare e assegnare metadati. L'oggetto metadati assegnato può essere PropertyMetadata o una delle relative classi derivate, ad esempio FrameworkPropertyMetadata. Scegliere FrameworkPropertyMetadata per le proprietà di dipendenza che si basano sulle API di presentazione WPF e sui file eseguibili per il rendering e il data binding. Un'opzione più avanzata consiste nel derivare da FrameworkPropertyMetadata per creare una classe di report di metadati personalizzata con più flag. In alternativa, è possibile usare UIPropertyMetadata per le proprietà non del framework che influiscono sul rendering dell'interfaccia utente.

Anche se le opzioni dei metadati vengono in genere impostate durante la registrazione di una nuova proprietà di dipendenza, è possibile specificarle in OverrideMetadata o AddOwner chiamate. Quando si esegue l'override dei metadati, eseguire sempre l'override con lo stesso tipo di metadati usato durante la registrazione delle proprietà.

Le caratteristiche delle proprietà esposte da FrameworkPropertyMetadata vengono talvolta definite flag. Se si crea un'istanza FrameworkPropertyMetadata di , è possibile popolare i valori dei flag in due modi:

  1. Impostare i flag in un'istanza del FrameworkPropertyMetadataOptions tipo di enumerazione. FrameworkPropertyMetadataOptions consente di specificare i flag di metadati in combinazione OR bit per bit. FrameworkPropertyMetadata Creare quindi un'istanza usando un costruttore con un FrameworkPropertyMetadataOptions parametro e passare l'istanzaFrameworkPropertyMetadataOptions. Per modificare i flag di metadati dopo il FrameworkPropertyMetadataOptions passaggio al FrameworkPropertyMetadata costruttore, modificare la proprietà corrispondente nella nuova FrameworkPropertyMetadata istanza. Ad esempio, se si imposta il FrameworkPropertyMetadataOptions.NotDataBindable flag , è possibile annullare tale flag impostando FrameworkPropertyMetadata.IsNotDataBindable su false.

  2. FrameworkPropertyMetadata Creare un'istanza usando un costruttore che non ha un FrameworkPropertyMetadataOptions parametro e quindi impostare i flag applicabili Boolean su FrameworkPropertyMetadata. Impostare i valori dei flag prima di associare l'istanza FrameworkPropertyMetadata a una proprietà di dipendenza. In caso contrario, si otterrà un oggetto InvalidOperationException.

Comportamento di override dei metadati

Quando si esegue l'override dei metadati delle proprietà del framework, i valori dei metadati modificati sostituiscono o vengono uniti con i valori originali:

  • Per un PropertyChangedCallbackoggetto , la logica di unione predefinita mantiene i valori precedenti PropertyChangedCallback in una tabella e tutti vengono richiamati in una modifica della proprietà. L'ordine di callback è determinato dalla profondità della classe, in cui viene eseguito un callback registrato dalla classe di base nella gerarchia. I callback ereditati vengono eseguiti una sola volta e sono di proprietà della classe che le ha aggiunte ai metadati.

  • Per , DefaultValueil nuovo valore sostituirà il valore predefinito esistente. Se non si specifica un oggetto DefaultValue nei metadati di override e se il Inherits flag esistente FrameworkPropertyMetadata è impostato, il valore predefinito proviene dal predecessore più vicino specificato DefaultValue nei metadati.

  • Per un CoerceValueCallbackoggetto , il nuovo valore sostituirà un valore esistente CoerceValueCallback . Se non si specifica un oggetto CoerceValueCallback nei metadati di override, il valore proviene dal predecessore più vicino nella catena di ereditarietà che ha specificato un oggetto CoerceValueCallback.

  • Per FrameworkPropertyMetadata i flag non ereditati, è possibile eseguire l'override del valore predefinito false con un true valore . Tuttavia, è possibile eseguire l'override di un true valore solo con un false valore per Inherits, JournalOverridesInheritanceBehavior, e SubPropertiesDoNotAffectRender.

Nota

La logica di unione predefinita viene implementata dal Merge metodo . È possibile specificare la logica di unione personalizzata in una classe derivata che eredita una proprietà di dipendenza eseguendo l'override Merge in tale classe.

Vedi anche