Framework-Eigenschaftenmetadaten (WPF .NET)

Sie können Metadatenoptionen für Frameworkeigenschaften für Abhängigkeitseigenschaften auf WPF-Frameworkebene (Windows Presentation Foundation) festlegen. Die WPF-Frameworkebenenbezeichnung gilt, wenn WPF-Präsentations-APIs und ausführbare Dateien Rendering und Datenbindung verarbeiten. Präsentations-APIs und ausführbare Dateien fragen die FrameworkPropertyMetadata einer Abhängigkeitseigenschaft ab.

Wichtig

Der Desktopleitfaden zu .NET 7 und .NET 6 ist in Bearbeitung.

Voraussetzungen

Im Artikel wird davon ausgegangen, dass sie grundlegende Kenntnisse über Abhängigkeitseigenschaften haben und eine Übersicht über Abhängigkeitseigenschaften gelesen haben. Um den Beispielen in diesem Artikel zu folgen, ist es hilfreich, wenn Sie mit Extensible Application Markup Language (XAML) vertraut sind und wissen, wie WPF-Anwendungen geschrieben werden.

Metadatenkategorien für Frameworkeigenschaften

FrameworkPropertyMetadata fällt in diese Kategorien:

  • Metadaten, die sich auf das Layout eines Elements auswirken, insbesondere die AffectsArrange-, AffectsMeasure- und AffectsRender-Metadatenflags. Möglicherweise legen Sie diese Flags fest, wenn sich die Implementierung der Abhängigkeitseigenschaft auf einen visuellen Aspekt auswirkt, und Sie implementieren MeasureOverride oder ArrangeOverride in Ihrer Klasse. Die MeasureOverride- und ArrangeOverride-Methoden bieten implementierungsspezifische Verhalten und Renderinginformationen für das Layoutsystem an. Wenn AffectsArrange, AffectsMeasure, oder AffectsRender in den Metadaten einer Abhängigkeitseigenschaft festgelegt als true sind und der effektive Wert geändert wird, initiiert das WPF-Eigenschaftssystem eine Anforderung, um die Visuellen des Elements zu ungültig zu machen, um eine Redrawierung auszulösen.

  • Metadaten, die sich auf das Layout des übergeordneten Elements eines Elements auswirken, insbesondere die AffectsParentArrange- und AffectsParentMeasure-Metadatenflags. Beispiele für WPF-Abhängigkeitseigenschaften, die diese Flags festlegen, sind FixedPage.Left und Paragraph.KeepWithNext.

  • Eigenschaftenwert-Vererbungsmetadaten, insbesondere die Inherits- und OverridesInheritanceBehavior-Metadatenflags. Standardmäßig erben Abhängigkeitseigenschaften keine Werte. OverridesInheritanceBehavior ermöglicht es dem Vererbungspfad, auch in eine visuelle Struktur zu gelangen. Dies ist für einige Szenarios zum Zusammenlegen von Steuerelementen erforderlich. Weitere Informationen finden Sie unter Vererbung von Eigenschaftswerten.

    Hinweis

    Der Begriff "erbt" im Kontext von Eigenschaftenwerten ist spezifisch für Abhängigkeitseigenschaften und bezieht sich nicht direkt auf verwaltete Codetypen und Membervererbung durch abgeleitete Typen. Im Kontext von Abhängigkeitseigenschaften bedeutet dies, dass untergeordnete Elemente Abhängigkeitseigenschaftswerte von übergeordneten Elementen erben können.

  • Datenbindungsmetadaten, insbesondere die BindsTwoWayByDefault- und IsNotDataBindable- Metadatenflags. Abhängigkeitseigenschaften im WPF-Framework unterstützen standardmäßig eine einseitige Bindung. Berücksichtigen Sie die Einstellung der bidirektionale Bindung als Standard für Eigenschaften, die den Status melden und durch Benutzeraktion geändert werden können, z. B. IsSelected. Denken Sie außerdem daran, die Zwei-Wege-Bindung als Standard festzulegen, wenn Benutzer eines Steuerelements erwarten, dass eine Eigenschaft implementiert wird, z. B. TextBox.Text. BindsTwoWayByDefault wirkt sich nur auf den Standardbindungsmodus aus. Um die Datenflussrichtung einer Bindung zu bearbeiten, legen Sie Binding.Mode fest. Sie können die IsNotDataBindable-Datenbindung deaktivieren, wenn es keinen Einsatzfall für sie gibt. Weitere Informationen zur Datenbindung finden Sie in der Übersicht über die Datenbindung.

  • Journalmetadaten, insbesondere das Journal-Metadatenflag. Der Standardwert des Journal-Flags ist nur true für einige Abhängigkeitseigenschaften wie z. B. SelectedIndex. Benutzereingabesteuerelemente sollten das Journal-Flag für Eigenschaften festlegen, deren Werte Benutzerauswahlen enthalten, die gespeichert werden müssen. Das Journal-Flag wird von Anwendungen oder Diensten gelesen, die Journalerstellung unterstützen, einschließlich WPF-Journaldienste. Informationen zum Speichern von Navigationsschritten finden Sie unter Navigationsübersicht.

FrameworkPropertyMetadata leitet direkt von UIPropertyMetadata, und implementiert die hier beschriebenen Flags. Sofern nicht ausdrücklich festgelegt, verfügen FrameworkPropertyMetadata-Flags über einen Standardwert von false.

Lesen von FrameworkPropertyMetadata

Um Metadaten für eine Abhängigkeitseigenschaft abzurufen, rufen Sie GetMetadata im DependencyProperty-Bezeichner auf. Der GetMetadata-Aufruf gibt ein PropertyMetadata-Objekt zurück. Wenn Sie Framework-Metadatenwerte abfragen müssen, wandeln Sie PropertyMetadata in FrameworkPropertyMetadata um.

Festlegen von FrameworkPropertyMetadata

Wenn Sie eine Abhängigkeitseigenschaft registrieren, haben Sie die Möglichkeit, Metadaten zu erstellen und ihr zuzuweisen. Das Metadatenobjekt, das Sie zuweisen, kann PropertyMetadata oder eine seiner abgeleiteten Klassen sein, z. B. FrameworkPropertyMetadata. Wählen Sie FrameworkPropertyMetadata für Abhängigkeitseigenschaften aus, die von WPF-Präsentations-APIs und ausführbaren Dateien zum Rendern und Datenbindung abhängig sind. Eine erweiterte Option besteht in der Ableitung von FrameworkPropertyMetadata, um eine benutzerdefinierte Metadatenberichterstattungsklasse mit weiteren Flags zu erstellen. Sie können UIPropertyMetadata auch für Nicht-Framework-Eigenschaften verwenden, die sich auf das Rendern der Benutzeroberfläche auswirken.

Obwohl Metadatenoptionen während der Registrierung einer neuen Abhängigkeitseigenschaft in der Regel festgelegt werden, können Sie diese in OverrideMetadata- oder AddOwner-Aufrufen erneut angeben. Überschreiben Sie beim Überschreiben von Metadaten immer mit demselben Metadatentyp, der während der Eigenschaftenregistrierung verwendet wurde.

Die Eigenschafteneigenschaften, die Ihnen von FrameworkPropertyMetadata verfügbar gemacht werden, werden manchmal als Flags bezeichnet. Wenn Sie eine FrameworkPropertyMetadata-Instanz erstellen, gibt es zwei Möglichkeiten zum Auffüllen von Flagwerten:

  1. Legen Sie die Flags in einer Instanz des FrameworkPropertyMetadataOptions-Enumerationstyps fest. FrameworkPropertyMetadataOptions ermöglicht Ihnen die Angabe von Metadaten-Flags in bitzeiger ODER-Kombination. Instanziieren Sie dann FrameworkPropertyMetadata mit einem Konstruktor mit einem FrameworkPropertyMetadataOptions-Parameter und übergeben Sie in Ihrer FrameworkPropertyMetadataOptions-Instanz. Um Metadaten-Flags nach der Übergabe von FrameworkPropertyMetadataOptions an den FrameworkPropertyMetadata-Konstruktor zu ändern, ändern Sie die entsprechende Eigenschaft in der neuen FrameworkPropertyMetadata-Instanz. Wenn Sie z. B. das FrameworkPropertyMetadataOptions.NotDataBindable-Flag festlegen, können Sie dies rückgängig machen, indem Sie FrameworkPropertyMetadata.IsNotDataBindable auf false setzen.

  2. Instanziieren Sie FrameworkPropertyMetadata mit einem Konstruktor, der keinen FrameworkPropertyMetadataOptions-Parameter enthält, und legen Sie dann die anwendbaren Boolean Flags auf FrameworkPropertyMetadata fest. Legen Sie Flagwerte fest, bevor Sie Ihre FrameworkPropertyMetadata-Instanz mit einer Abhängigkeitseigenschaft verknüpfen, andernfalls erhalten Sie eine InvalidOperationException.

Verhalten der Metadaten außer Kraft setzen

Wenn Sie Metadaten der Frameworkeigenschaft überschreiben, ersetzen geänderte Metadatenwerte entweder oder werden mit den ursprünglichen Werten zusammengeführt:

  • Für eine PropertyChangedCallback-Tabelle behält die Standarddrucklogik frühere PropertyChangedCallback-Werte in einer Tabelle bei, und alle werden auf einer Eigenschaftsänderung aufgerufen. Die Rückrufreihenfolge wird durch Die Klassentiefe bestimmt, wobei ein Rückruf, der von der Basisklasse in der Hierarchie registriert wurde, zuerst ausgeführt wird. Geerbte Rückrufe werden nur einmal ausgeführt und befinden sich im Besitz der Klasse, die sie den Metadaten hinzugefügt hat.

  • Für einen DefaultValue-Wert ersetzt der neue Wert den vorhandenen Standardwert. Wenn Sie keinen DefaultValue-Wert in den Außerkraftsetzungsmetadaten angeben und wenn für das vorhandene FrameworkPropertyMetadata das Inherits-Flag festgelegt ist, stammt der Standardwert aus dem nächstgelegenen Vorgänger, der in DefaultValue-Metadaten angegeben ist.

  • Für einen CoerceValueCallback-Wert ersetzt der neue Wert einen vorhandenen CoerceValueCallback-Wert. Wenn Sie keinen CoerceValueCallback-Wert in den Außerkraftsetzungsmetadaten angeben, stammt der Wert aus dem nächsten Vorgänger in der Vererbungskette, die eine CoerceValueCallback angegeben hat.

  • Bei nicht von FrameworkPropertyMetadata geerbten Flags können Sie den Standardwert false mit einem true-Wert außer Kraft setzen. Sie können jedoch nur einen true-Wert mit einem false-Wert für Inherits, Journal, OverridesInheritanceBehavior und SubPropertiesDoNotAffectRender außer Kraft setzen.

Hinweis

Die Standardzusammenführungslogik wird von der Merge-Methode implementiert. Sie können die benutzerdefinierte Zusammenführungslogik in einer abgeleiteten Klasse angeben, die eine Abhängigkeitseigenschaft erbt, indem Sie die Merge dieser Klasse außer Kraft setzen.

Weitere Informationen