XAML-Steuerelemente; an eine C++/WinRT-Eigenschaft binden

Eine Eigenschaft, die effektiv an ein XAML-Steuerelement gebunden werden kann, wird als Observable-Eigenschaft bezeichnet. Diese Idee basiert auf dem Softwaredesignmuster, das als Beobachtermuster bezeichnet wird. In diesem Thema wird gezeigt, wie Observable-Eigenschaften in C++/WinRT implementiert werden, und wie XAML-Steuerelemente an sie gebunden werden (informationen zu Hintergrundinformationen finden Sie unter "Datenbindung").

Was bedeutet observable für eine Eigenschaft?

Angenommen, eine Laufzeitklasse mit dem Namen BookSku hat eine Eigenschaft namens Title. Wenn BookSku das INotifyPropertyChanged::P ropertyChanged-Ereignis auslöst, wenn sich der Wert von Title ändert, bedeutet dies, dass Title eine feststellbare Eigenschaft ist. Es ist das Verhalten von BookSku (Auslösen oder Nicht auslösen des Ereignisses), das bestimmt, welche, falls vorhanden, deren Eigenschaften feststellbar sind.

Ein XAML-Textelement oder -Steuerelement kann an diese Ereignisse gebunden und behandelt werden. Ein solches Element oder Steuerelement behandelt das Ereignis durch Abrufen der aktualisierten Werte und aktualisiert sich dann, um den neuen Wert anzuzeigen.

Erstellen einer leeren App (Bookstore)

Beginnen Sie damit, ein neues Projekt in Microsoft Visual Studio zu erstellen. Erstellen Sie eine leere App, verpackt (WinUI 3 in Desktop) für C++-Projekt, und nennen Sie sie "Bookstore". Stellen Sie sicher, dass "Projektmappe und Projekt in demselben Verzeichnis platzieren" deaktiviert ist. Richten Sie sich auf die neueste allgemein verfügbare (d. h. keine Vorschau)-Version des Windows SDK.

Wir werden eine neue Klasse erstellen, um ein Buch darzustellen, das über eine feststellbare Titeleigenschaft verfügt. Wir erstellen und verwenden die Klasse innerhalb derselben Kompilierungseinheit. Wir möchten jedoch in der Lage sein, eine Bindung an diese Klasse aus XAML zu erstellen, und aus diesem Grund wird es sich um eine Laufzeitklasse handeln. Und wir werden C++/WinRT verwenden, um sie zu erstellen und zu nutzen.

Der erste Schritt beim Erstellen einer neuen Laufzeitklasse besteht darin, dem Projekt ein neues Midl File -Element (IDL) hinzuzufügen. Benennen Sie das neue Element BookSku.idl. Löschen Sie den Standardinhalt von BookSku.idl, und fügen Sie diese Laufzeitklassendeklaration ein.

// BookSku.idl
namespace Bookstore
{
    runtimeclass BookSku : Microsoft.UI.Xaml.Data.INotifyPropertyChanged
    {
        BookSku(String title);
        String Title;
    }
}

Speichern Sie die Datei, und erstellen Sie das Projekt. Der Build wird zwar noch nicht vollständig erfolgreich abgeschlossen, aber er wird einige notwendige Schritte für uns ausführen. Insbesondere wird während des Buildprozesses das Tool midl.exe ausgeführt, um eine Windows-Runtime-Metadatendatei zu erstellen, die die Runtimeklasse beschreibt (die Datei wird unter \Bookstore\Debug\Bookstore\Unmerged\BookSku.winmd auf dem Datenträger abgelegt). Anschließend wird das cppwinrt.exe Tool ausgeführt, um Quellcodedateien zu generieren, die Sie beim Erstellen und Verwenden ihrer Laufzeitklasse unterstützen. Diese Dateien enthalten Stubs, die Ihnen den Einstieg in die Implementierung der BookSku-Laufzeitklasse erleichtern, die Sie in Ihrer IDL deklariert haben. Wir werden sie gleich auf der Festplatte finden, aber diese Stubs sind \Bookstore\Bookstore\Generated Files\sources\BookSku.h und BookSku.cpp.

Klicken Sie nun mit der rechten Maustaste auf den Projektknoten in Visual Studio, und klicken Sie im Datei-Explorer auf "Ordner öffnen". Dadurch wird der Projektordner im Datei-Explorer geöffnet. Jetzt sollten Sie sich den Inhalt des \Bookstore\Bookstore\ Ordners ansehen. Navigieren Sie von dort aus in den \Generated Files\sources\ Ordner, und kopieren Sie die Stubdateien BookSku.h und BookSku.cpp in die Zwischenablage. Navigieren Sie zurück zum Projektordner (\Bookstore\Bookstore\), und fügen Sie die beiden Dateien ein, die Sie gerade kopiert haben. Stellen Sie abschließend in Projektmappen-Explorer mit ausgewähltem Projektknoten sicher, dass Alle Dateien anzeigen aktiviert ist. Klicken Sie mit der rechten Maustaste auf die kopierten Stubdateien, und klicken Sie auf Include In Project.

Implementieren von BookSku

Lassen Sie uns nun unsere Laufzeitklasse öffnen \Bookstore\Bookstore\BookSku.h und BookSku.cpp implementieren. Zuerst sehen Sie oben auf BookSku.h und BookSku.cpp ein static_assert, das Sie entfernen müssen.

Nehmen Sie als Nächstes in BookSku.h diese Änderungen vor.

• Ändern Sie = default im Standardkonstruktor zu = delete. Das liegt daran, dass wir keinen Standardkonstruktor wünschen.
• Fügen Sie ein privates Mitglied hinzu, um den Titel-String zu speichern. Beachten Sie, dass ein Konstruktor vorhanden ist, der einen winrt::hstring-Wert akzeptiert. Dieser Wert ist der Titeltext.
• Fügen Sie ein weiteres privates Member für das Ereignis hinzu, das wir auslösen, wenn sich der Titel ändert.

Nachdem Sie diese Änderungen vorgenommen haben, sehen Sie BookSku.h wie folgt aus.

// BookSku.h
#pragma once
#include "BookSku.g.h"

namespace winrt::Bookstore::implementation
{
    struct BookSku : BookSkuT<BookSku>
    {
        BookSku() = delete;
        BookSku(winrt::hstring const& title);

        winrt::hstring Title();
        void Title(winrt::hstring const& value);
        winrt::event_token PropertyChanged(Microsoft::UI::Xaml::Data::PropertyChangedEventHandler const& value);
        void PropertyChanged(winrt::event_token const& token);
    
    private:
        winrt::hstring m_title;
        winrt::event<Microsoft::UI::Xaml::Data::PropertyChangedEventHandler> m_propertyChanged;
    };
}
namespace winrt::Bookstore::factory_implementation
{
    struct BookSku : BookSkuT<BookSku, implementation::BookSku>
    {
    };
}

Implementieren Sie die Funktionen in BookSku.cpp wie folgt.

// BookSku.cpp
#include "pch.h"
#include "BookSku.h"
#include "BookSku.g.cpp"

namespace winrt::Bookstore::implementation
{
    BookSku::BookSku(winrt::hstring const& title) : m_title{ title }
    {
    }

    winrt::hstring BookSku::Title()
    {
        return m_title;
    }

    void BookSku::Title(winrt::hstring const& value)
    {
        if (m_title != value)
        {
            m_title = value;
            m_propertyChanged(*this, Microsoft::UI::Xaml::Data::PropertyChangedEventArgs{ L"Title" });
        }
    }

    winrt::event_token BookSku::PropertyChanged(Microsoft::UI::Xaml::Data::PropertyChangedEventHandler const& handler)
    {
        return m_propertyChanged.add(handler);
    }

    void BookSku::PropertyChanged(winrt::event_token const& token)
    {
        m_propertyChanged.remove(token);
    }
}

In der Funktion "Titel mutator" überprüfen wir, ob ein Wert festgelegt wird, der sich von dem aktuellen Wert unterscheidet. Und wenn ja, aktualisieren wir den Titel und lösen außerdem das Ereignis INotifyPropertyChanged::PropertyChanged mit einem Argument aus, das dem Namen der Eigenschaft entspricht, die sich geändert hat. Dies ist so, dass die Benutzeroberfläche erkennt, welcher Eigenschaftswert erneut abzufragen ist.

Das Projekt wird jetzt erneut erstellt, wenn Sie dies überprüfen möchten.

Deklarieren und Implementieren von BookstoreViewModel

Unsere HAUPT-XAML-Seite wird an ein Hauptansichtsmodell gebunden. Und dieses Ansichtsmodell verfügt über mehrere Eigenschaften, einschließlich eines vom Typ "BookSku". In diesem Schritt deklarieren und implementieren wir die Laufzeitklasse unseres Haupt-ViewModels.

Fügen Sie ein neues Midl File (.idl) -Element mit dem Namen hinzu BookstoreViewModel.idl. Sehen Sie sich aber auch Factoring-Laufzeitklassen in Midl-Dateien (IDL) an.

// BookstoreViewModel.idl
import "BookSku.idl";

namespace Bookstore
{
    runtimeclass BookstoreViewModel
    {
        BookstoreViewModel();
        BookSku BookSku{ get; };
    }
}

Speichern und Erstellen (der Build ist noch nicht vollständig erfolgreich, aber der Grund, warum wir erstellen, besteht darin, Stubdateien erneut zu generieren).

Kopieren Sie BookstoreViewModel.h und BookstoreViewModel.cpp aus dem Ordner Generated Files\sources in den Projektordner, und binden Sie sie in das Projekt ein. Öffnen Sie diese Dateien (entfernen Sie die static_assert Datei erneut), und implementieren Sie die Laufzeitklasse wie unten dargestellt. Beachten Sie, dass wir in BookstoreViewModel.hdiesem Beispiel den BookSku.hImplementierungstyp für BookSku deklarieren (was winrt::Bookstore::implementation::BookSku ist). Und wir entfernen = default aus dem Standardkonstruktor.

// BookstoreViewModel.h
#pragma once
#include "BookstoreViewModel.g.h"
#include "BookSku.h"

namespace winrt::Bookstore::implementation
{
    struct BookstoreViewModel : BookstoreViewModelT<BookstoreViewModel>
    {
        BookstoreViewModel();

        Bookstore::BookSku BookSku();

    private:
        Bookstore::BookSku m_bookSku{ nullptr };
    };
}
namespace winrt::Bookstore::factory_implementation
{
    struct BookstoreViewModel : BookstoreViewModelT<BookstoreViewModel, implementation::BookstoreViewModel>
    {
    };
}

// BookstoreViewModel.cpp
#include "pch.h"
#include "BookstoreViewModel.h"
#include "BookstoreViewModel.g.cpp"

namespace winrt::Bookstore::implementation
{
    BookstoreViewModel::BookstoreViewModel()
    {
        m_bookSku = winrt::make<Bookstore::implementation::BookSku>(L"Atticus");
    }

    Bookstore::BookSku BookstoreViewModel::BookSku()
    {
        return m_bookSku;
    }
}

Das Projekt wird jetzt erneut erstellt.

Hinzufügen einer Eigenschaft vom Typ "BookstoreViewModel " zu "MainPage"

Öffnen Sie MainPage.idl, das die Runtimeklasse deklariert, die unsere Haupt-UI-Seite darstellt.

• Fügen Sie zum Importieren von BookstoreViewModel.idl eine import-Anweisung hinzu.
• Fügen Sie eine schreibgeschützte Eigenschaft namens MainViewModel, vom Typ BookstoreViewModel, hinzu.
• Entfernen Sie die MyProperty-Eigenschaft .

// MainPage.idl
import "BookstoreViewModel.idl";

namespace Bookstore
{
    runtimeclass MainPage : Microsoft.UI.Xaml.Controls.Page
    {
        MainPage();
        BookstoreViewModel MainViewModel{ get; };
    }
}

Speichern Sie die Datei. Das Projekt lässt sich zwar noch nicht vollständig erfolgreich erstellen, aber ein Build jetzt ist dennoch sinnvoll, weil dabei die Quellcodedateien regeneriert werden, in denen die Laufzeitklasse MainPage implementiert ist (\Bookstore\Bookstore\Generated Files\sources\MainPage.h und MainPage.cpp). Also fahren Sie fort, und erstellen Sie jetzt. Der Buildfehler, den Sie in dieser Phase erwarten können, ist "MainViewModel": ist kein Mitglied von 'winrt::Bookstore::implementation::MainPage'.

Wenn Sie die Include-Anweisung für BookstoreViewModel.idl weglassen (siehe die Auflistung von MainPage.idl oben), wird die Fehlermeldung < in der Nähe von "MainViewModel" erwartet angezeigt. Ein weiterer Tipp besteht darin, sicherzustellen, dass Sie alle Typen im selben Namespace belassen – der Namespace, der in den Codeauflistungen angezeigt wird.

Um den Fehler zu beheben, den wir erwartungsgemäß sehen, müssen Sie jetzt die Accessor-Stubs für die MainViewModel-Eigenschaft aus den generierten Dateien (\Bookstore\Bookstore\Generated Files\sources\MainPage.h und MainPage.cpp) in \Bookstore\Bookstore\MainPage.h und MainPage.cpp kopieren. Die Schritte dazu werden im Folgenden beschrieben.

Führen Sie in \Bookstore\Bookstore\MainPage.h die folgenden Schritte aus.

• Fügen Sie BookstoreViewModel.h ein, das den Implementierungstyp für BookstoreViewModel deklariert (nämlich winrt::Bookstore::implementation::BookstoreViewModel).
• Fügen Sie ein privates Mitglied hinzu, um das Ansichtsmodell zu speichern. Beachten Sie, dass die Eigenschaftszugriffsfunktion (und das Member m_mainViewModel) auf Grundlage des projizierten Typs von BookstoreViewModel implementiert ist (also Bookstore::BookstoreViewModel).
• Der Implementierungstyp befindet sich in demselben Projekt (Kompilierungseinheit) wie die Anwendung. Daher erstellen wir m_mainViewModel über die Konstruktorüberladung, die "std::nullptr_t" verwendet.
• Entfernen Sie die MyProperty-Eigenschaft .

// MainPage.h
...
#include "BookstoreViewModel.h"
...
namespace winrt::Bookstore::implementation
{
    struct MainPage : MainPageT<MainPage>
    {
        MainPage();

        Bookstore::BookstoreViewModel MainViewModel();

        void ClickHandler(Windows::Foundation::IInspectable const&, Microsoft::UI::Xaml::RoutedEventArgs const&);

    private:
        Bookstore::BookstoreViewModel m_mainViewModel{ nullptr };
    };
}
...

In \Bookstore\Bookstore\MainPage.cpp, wie in der nachstehenden Auflistung gezeigt, nehmen Sie die folgenden Änderungen vor.

• Rufen Sie winrt::make (mit dem BookstoreViewModel-Implementierungstyp) auf, um m_mainViewModel eine neue Instanz des projizierten BookstoreViewModel-Typs zuzuweisen. Wie wir oben gesehen haben, erstellt der BookstoreViewModel-Konstruktor ein neues BookSku-Objekt als privates Datenelement, wobei der Titel anfangs auf L"Atticus" gesetzt wird.
• Aktualisieren Sie im Ereignishandler der Schaltfläche (ClickHandler) den Titel des Buchs auf den veröffentlichten Titel.
• Implementieren Sie den Accessor für die MainViewModel-Eigenschaft .
• Entfernen Sie die MyProperty-Eigenschaft .

// MainPage.cpp
#include "pch.h"
#include "MainPage.h"
#include "MainPage.g.cpp"

using namespace winrt;
using namespace Microsoft::UI::Xaml;

namespace winrt::Bookstore::implementation
{
    MainPage::MainPage()
    {
        m_mainViewModel = winrt::make<Bookstore::implementation::BookstoreViewModel>();
        InitializeComponent();
    }

    void MainPage::ClickHandler(Windows::Foundation::IInspectable const& /* sender */, Microsoft::UI::Xaml::RoutedEventArgs const& /* args */)
    {
        MainViewModel().BookSku().Title(L"To Kill a Mockingbird");
    }

    Bookstore::BookstoreViewModel MainPage::MainViewModel()
    {
        return m_mainViewModel;
    }
}

Einheitliche Konstruktion

Um eine einheitliche Konstruktion anstelle von winrt::make zu verwenden, MainPage.h deklarieren und initialisieren Sie m_mainViewModel in nur einem Schritt, wie unten dargestellt.

// MainPage.h
...
#include "BookstoreViewModel.h"
...
struct MainPage : MainPageT<MainPage>
{
    ...
private:
    Bookstore::BookstoreViewModel m_mainViewModel;
};
...

Und dann wird im MainPage-Konstruktor in MainPage.cpp der Code m_mainViewModel = winrt::make<Bookstore::implementation::BookstoreViewModel>(); nicht benötigt.

Weitere Informationen zur einheitlichen Konstruktion und Codebeispielen finden Sie unter "Opt in to uniform construction" und "Direct Implementation Access".

Binden der Schaltfläche an die Title-Eigenschaft

Öffne MainPage.xaml. Darin befindet sich das XAML-Markup für unsere UI-Hauptseite. Wie in der nachstehenden Auflistung gezeigt, entfernen Sie den Namen aus der Schaltfläche, und ändern Sie den Wert der Inhaltseigenschaft von einem Literal in einen Bindungsausdruck. Beachten Sie die Mode=OneWay-Eigenschaft in dem Bindungsausdruck (einseitig vom Ansichtsmodell zur Benutzeroberfläche). Ohne diese Eigenschaft reagiert die Benutzeroberfläche nicht auf Eigenschaftsänderungsereignisse.

<Button Click="ClickHandler" Content="{x:Bind MainViewModel.BookSku.Title, Mode=OneWay}"/>

Erstellen Sie nun das Projekt und führen Sie es aus. Klicken Sie auf die Schaltfläche, um den Click-Event-Handler auszuführen. Dieser Handler ruft die Titelmutatorfunktion des Buchs auf; dieser Mutator löst ein Ereignis aus, um die Benutzeroberfläche darüber zu informieren, dass sich die Title-Eigenschaft geändert hat; und die Schaltfläche fragt den Wert dieser Eigenschaft erneut ab, um seinen eigenen Inhaltswert zu aktualisieren.

Verwenden der {Binding}-Markuperweiterung mit C++/WinRT

Für die derzeit veröffentlichte Version von C++/WinRT müssen Sie die Schnittstellen ICustomPropertyProvider und ICustomProperty implementieren, um die {Binding}-Markuperweiterung verwenden zu können.

Element-zu-Element-Bindung

Sie können die Eigenschaft eines XAML-Elements an die Eigenschaft eines anderen XAML-Elements binden. Hier ist ein Beispiel dafür, wie das im Markup aussieht.

<TextBox x:Name="myTextBox" />
<TextBlock Text="{x:Bind myTextBox.Text, Mode=OneWay}" />

Sie müssen die XAML-Entität mit Namen myTextBox in Ihrer MIDL-Datei (.idl) als schreibgeschützte Eigenschaft deklarieren.

// MainPage.idl
runtimeclass MainPage : Microsoft.UI.Xaml.Controls.Page
{
    MainPage();
    Microsoft.UI.Xaml.Controls.TextBox myTextBox{ get; };
}

Dies ist der Grund für diese Notwendigkeit. Alle Typen, die der XAML-Compiler überprüfen muss (einschließlich derjenigen, die in {x:Bind}verwendet werden), werden aus Windows Metadaten (WinMD) gelesen. Sie müssen Ihrer MIDL-Datei lediglich die Eigenschaft „read-only“ hinzufügen. Implementieren Sie dies nicht, da der automatisch generierte XAML-Code-Behind die Implementierung für Sie übernimmt.

Verwenden von Objekten aus XAML-Markup

Alle Entitäten, die bei Verwendung der XAML-{x:Bind}-Markuperweiterung genutzt werden, müssen in IDL öffentlich verfügbar gemacht werden. Wenn xaml-Markup außerdem einen Verweis auf ein anderes Element enthält, das sich auch im Markup befindet, muss der Getter für dieses Markup in IDL vorhanden sein.

<Page x:Name="MyPage">
    <StackPanel>
        <CheckBox x:Name="UseCustomColorCheckBox" Content="Use custom color"
             Click="UseCustomColorCheckBox_Click" />
        <Button x:Name="ChangeColorButton" Content="Change color"
            Click="{x:Bind ChangeColorButton_OnClick}"
            IsEnabled="{x:Bind UseCustomColorCheckBox.IsChecked.Value, Mode=OneWay}"/>
    </StackPanel>
</Page>

Das ChangeColorButton-Element verweist über bindung auf das UseCustomColorCheckBox-Element . Daher muss die IDL für diese Seite eine schreibgeschützte Eigenschaft namens UseCustomColorCheckBox deklarieren, damit sie für das Binding zugänglich ist.

Der Delegat für den Click-Ereignishandler von UseCustomColorCheckBox verwendet die klassische XAML-Delegatsyntax, daher ist kein Eintrag in der IDL erforderlich; er muss in Ihrer Implementierungsklasse lediglich öffentlich sein. Andererseits verfügt ChangeColorButton ebenfalls über einen {x:Bind} Klick-Ereignishandler, der ebenfalls in die IDL aufgenommen werden muss.

runtimeclass MyPage : Microsoft.UI.Xaml.Controls.Page
{
    MyPage();

    // These members are consumed by binding.
    void ChangeColorButton_OnClick();
    Microsoft.UI.Xaml.Controls.CheckBox UseCustomColorCheckBox{ get; };
}

Sie müssen keine Implementierung für die UseCustomColorCheckBox-Eigenschaft bereitstellen. Der XAML-Codegenerator führt dies für Sie aus.

Bindung an Boolean

Sie können dies in einem Diagnosemodus tun:

<TextBlock Text="{Binding CanPair}"/>

Das wird in C++/CX als true oder false angezeigt; in C++/WinRT jedoch als Windows.Foundation.IReference`1<Boolean>.

Verwenden Sie x:Bind stattdessen beim Binden an einen booleschen Wert.

<TextBlock Text="{x:Bind CanPair}"/>

Verwenden der Windows Implementierungsbibliotheken (WIL)

Die Windows Implementation Libraries (WIL) bieten Hilfsfunktionen, um das Schreiben bindbarer Eigenschaften zu erleichtern. Siehe Benachrichtigen von Eigenschaften in der WIL-Dokumentation.

Wichtige APIs

• INotifyPropertyChanged::PropertyChanged
• Funktionsvorlage winrt::make

Zugehörige Themen

• Verwenden von APIs mit C++/WinRT
• APIs mit C++/WinRT erstellen