XAML-Formatvorlagen

2025-04-30

Sie können die Darstellung Ihrer Apps auf vielfältige Weise mithilfe des XAML-Frameworks anpassen. Mit Stilen können Sie Steuerelementeigenschaften festlegen und diese Einstellungen für eine einheitliche Darstellung über mehrere Steuerelemente hinweg wiederverwenden.

WinUI und Stile

Ab WinUI 2.2 haben wir WinUI verwendet, um neue Aktualisierungen des visuellen Stils in unseren UI-Komponenten bereitzustellen. Wenn Sie feststellen, dass ihre Benutzeroberfläche nicht auf die neuesten Stile aktualisiert wird, müssen Sie unbedingt auf das neueste WinUI NuGet-Paket aktualisieren.

Ab WinUI 2.6 bieten wir neue Stile für die meisten Steuerelemente und ein neues Versionsverwaltungssystem, das Sie bei Bedarf auf die vorherigen Steuerelementstile zurücksetzen können. Wir empfehlen Ihnen, die neuen Stile zu verwenden, da sie besser mit der Entwurfsrichtung von Windows übereinstimmen. Wenn Ihr Szenario die neuen Formatvorlagen nicht unterstützen kann, sind die vorherigen Versionen jedoch weiterhin verfügbar.

Sie können die Stilversion ändern, indem Sie die ControlsResourcesVersion-Eigenschaft in der XamlControlsResources festlegen, die Sie in Ihre Application.Resources einschließen, wenn Sie die WinUI-Version 2 verwenden. ControlsResourcesVersion nimmt standardmäßig den Enum-Wert Version2an.

Wenn Sie diesen Wert auf Version1 festlegen, werden XamlControlsResources die vorherigen Formatvorlagenversionen anstelle der neuen Formatvorlagen laden, die von der neuesten WinUI-Version verwendet werden. Das Ändern dieser Eigenschaft zur Laufzeit wird nicht unterstützt, und die Hot-Reload-Funktion von VisualStudio funktioniert nicht. Nachdem Sie jedoch die Anwendung neu erstellt haben, ändern sich die Steuerelementstile.

<Application.Resources>
    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" 
                           ControlsResourcesVersion="Version1"/>
</Application.Resources>

Stilgrundlagen

Verwenden Sie Stile, um visuelle Eigenschaften in wiederverwendbare Ressourcen zu extrahieren. Hier sehen Sie ein Beispiel, das drei Schaltflächen zeigt, deren Stil die Eigenschaften BorderBrush, BorderThickness und Foreground festlegt. Wenn Sie eine Formatvorlage anwenden, können Sie festlegen, dass die Steuerelemente gleich angezeigt werden, ohne diese Eigenschaften für jedes Steuerelement separat festlegen zu müssen.

Screenshot von drei formatierten Schaltflächen, die nebeneinander angeordnet sind.

Sie können eine Formatvorlage direkt im XAML-Code für ein Steuerelement definieren oder als wiederverwendbare Ressource erstellen. Definieren Sie Ressourcen in der XAML-Datei einer einzelnen Seite, in der Datei "App.xaml" oder in einer separaten XAML-Datei des Ressourcenwörterbuchs. Eine XAML-Datei des Ressourcenwörterbuchs kann über Apps hinweg freigegeben werden, und mehrere Ressourcenwörterbücher können in einer einzelnen App zusammengeführt werden. Wo die Ressource definiert ist, bestimmt den Bereich, in dem sie verwendet werden kann. Ressourcen auf Seitenebene sind nur auf der Seite verfügbar, auf der sie definiert sind. Wenn Ressourcen mit demselben Schlüssel sowohl in "App.xaml" als auch auf einer Seite definiert sind, überschreibt die Ressource auf der Seite die Ressource in "App.xaml". Wenn eine Ressource in einer separaten Ressourcenwörterbuchdatei definiert ist, wird ihr Bereich durch den Ort bestimmt, an dem auf das Ressourcenwörterbuch verwiesen wird.

In der Definition Style benötigen Sie ein TargetType--Attribut und eine Auflistung mit mindestens einem Setter--Element. Das TargetType-Attribut ist eine Zeichenfolge, die einen FrameworkElement-Typ angibt, auf den der Stil angewendet werden soll. Der TargetType--Wert muss einen FrameworkElement-abgeleiteten Typ angeben, der von der Windows-Runtime oder einem benutzerdefinierten Typ definiert wird, der in einer referenzierten Assembly verfügbar ist. Wenn Sie versuchen, eine Formatvorlage auf ein Steuerelement anzuwenden und der Typ des Steuerelements nicht mit dem TargetType-Attribut der Formatvorlage übereinstimmt, die Sie anwenden möchten, tritt eine Ausnahme auf.

Für jedes Setter--Element ist ein Property- und ein Value-erforderlich. Diese Eigenschafteneinstellungen geben an, auf welche Steuerelementeigenschaft die Einstellung angewendet wird, und den Wert, der für diese Eigenschaft festgelegt werden soll. Sie können den Wert von Setter.Value entweder durch Attribut- oder Eigenschaftselement-Syntax festlegen. Der XAML-Code zeigt die Formatvorlage, die auf die zuvor gezeigten Schaltflächen angewendet wurde. In diesem XAML verwenden die ersten beiden Setter--Elemente die Attributsyntax, während der letzte Setter-für die BorderBrush--Eigenschaft die Eigenschaftselementsyntax verwendet. Im Beispiel wird das x:Key-Attribut nicht verwendet, sodass der Stil implizit auf die Schaltflächen angewendet wird. Das Anwenden von Stilen, implizit oder explizit, wird im nächsten Abschnitt erläutert.

<Page.Resources>
    <Style TargetType="Button">
        <Setter Property="BorderThickness" Value="5" />
        <Setter Property="Foreground" Value="Black" />
        <Setter Property="BorderBrush" >
            <Setter.Value>
                <LinearGradientBrush StartPoint="0.5,0" EndPoint="0.5,1">
                    <GradientStop Color="Yellow" Offset="0.0" />
                    <GradientStop Color="Red" Offset="0.25" />
                    <GradientStop Color="Blue" Offset="0.75" />
                    <GradientStop Color="LimeGreen" Offset="1.0" />
                </LinearGradientBrush>
            </Setter.Value>
        </Setter>
    </Style>
</Page.Resources>

<StackPanel Orientation="Horizontal">
    <Button Content="Button"/>
    <Button Content="Button"/>
    <Button Content="Button"/>
</StackPanel>

Anwenden eines impliziten oder expliziten Stils

Wenn Sie einen Stil als Ressource definieren, gibt es zwei Möglichkeiten, ihn auf Ihre Steuerelementen anzuwenden:

Implizit durch Angeben eines TargetType- für die Style-.
Explizit durch Angeben eines TargetType- und eines x:Key-Attributs für den Style- und anschließend durch das Festlegen der Style--Eigenschaft des Zielsteuerelements mit einem {StaticResource}-Markuperweiterungs- Verweis, der den expliziten Schlüssel verwendet.

Wenn eine Formatvorlage das x:Key-Attributenthält, können Sie sie nur auf ein Steuerelement anwenden, indem Sie die eigenschaft Style des Steuerelements auf die Formatvorlage mit Schlüssel festlegen. Im Gegensatz dazu wird ein Stil ohne ein x:Key-Attribut automatisch auf jedes Steuerelement des Zieltyps angewendet, das nicht anderweitig eine explizite Stileinstellung besitzt.

Hier sind zwei Schaltflächen, die implizite und explizite Stile veranschaulichen.

implizit und explizit gestylte Schaltflächen.

In diesem Beispiel weist die erste Formatvorlage ein x:Key-Attribut auf, und der Zieltyp ist ein Button. Die Style-Eigenschaft der ersten Schaltfläche wird auf diesen Schlüssel gesetzt, sodass dieser Stil explizit angewendet wird. Die zweite Stilvorlage wird implizit auf die zweite Schaltfläche angewendet, da der Zieltyp Button ist und die Stilvorlage kein x:Key-Attribut hat.

<Page.Resources>
    <Style x:Key="PurpleStyle" TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="Foreground" Value="Purple"/>
    </Style>

    <Style TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="RenderTransform">
            <Setter.Value>
                <RotateTransform Angle="25"/>
            </Setter.Value>
        </Setter>
        <Setter Property="BorderBrush" Value="Green"/>
        <Setter Property="BorderThickness" Value="2"/>
        <Setter Property="Foreground" Value="Green"/>
    </Style>
</Page.Resources>

<Grid x:Name="LayoutRoot">
    <Button Content="Button" Style="{StaticResource PurpleStyle}"/>
    <Button Content="Button"/>
</Grid>

Auf Vorlage basierende Stile verwenden

Sie können Formatvorlagen erstellen, die von anderen Formatvorlagen erben, um die Wartung der Formatvorlagen zu erleichtern und die Wiederverwendung der Formatvorlagen zu optimieren. Sie verwenden die BasedOn-Eigenschaft, um geerbte Formatvorlagen zu erstellen. ** Formatvorlagen, die von anderen Formatvorlagen erben, müssen auf denselben Steuerelementtyp oder ein Steuerelement abzielen, das von dem Typ abgeleitet ist, auf den die ursprüngliche Formatvorlage abzielt. Beispielsweise, wenn ein Basisstil auf ContentControlabzielt, können die darauf basierenden Stile auf ContentControl oder auf von ContentControl abgeleitete Typen abzielen, wie z. B. Button und ScrollViewer. Wenn ein Wert nicht in der zugrunde liegenden Formatvorlage festgelegt ist, wird er von der Basisformatvorlage übernommen. Um einen Wert aus der Basisformatvorlage zu ändern, überschreibt die abgeleitete Formatvorlage diesen Wert. Das nächste Beispiel zeigt einen Button- und eine CheckBox- mit Formatvorlagen, die von derselben Basisformatvorlage erben.

formatierte Schaltflächen basierend auf Formatvorlagen.

Die Basisformatvorlage zielt auf ContentControl-ab und legt die Eigenschaften Heightund Width fest. Die auf diesem Stil basierenden Stile CheckBox und Button, die von ContentControlabgeleitet sind. Die basierenden Formatvorlagen legen unterschiedliche Farben für die Eigenschaften BorderBrush und Foreground fest. (Normalerweise verwenden Sie keinen Rahmen um ein CheckBox. Hier demonstrieren wir die Effekte des Stils.)

<Page.Resources>
    <Style x:Key="BasicStyle" TargetType="ContentControl">
        <Setter Property="Width" Value="130" />
        <Setter Property="Height" Value="30" />
    </Style>

    <Style x:Key="ButtonStyle" TargetType="Button"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Orange" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Red" />
    </Style>

    <Style x:Key="CheckBoxStyle" TargetType="CheckBox"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Blue" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Green" />
    </Style>
</Page.Resources>

<StackPanel>
    <Button Content="Button" Style="{StaticResource ButtonStyle}" Margin="0,10"/>
    <CheckBox Content="CheckBox" Style="{StaticResource CheckBoxStyle}"/>
</StackPanel>

Verwenden Sie Tools, um einfach mit Formatvorlagen zu arbeiten.

Eine schnelle Möglichkeit zum Anwenden von Formatvorlagen auf Ihre Steuerelemente besteht darin, mit der rechten Maustaste auf ein Steuerelement auf der XAML-Entwurfsoberfläche von Microsoft Visual Studio zu klicken und Formatvorlagen bearbeiten oder Vorlage bearbeiten (je nach Steuerelement, auf das Sie mit der rechten Maustaste klicken), auszuwählen. Anschließend können Sie eine vorhandene Formatvorlage anwenden, indem Sie Ressource anwenden oder eine neue Formatvorlage definieren, indem Sie Leerenauswählen. Wenn Sie eine leere Formatvorlage erstellen, haben Sie die Möglichkeit, sie auf der Seite, in der Datei "App.xaml" oder in einem separaten Ressourcenverzeichnis zu definieren.

Leichtgewichtige Gestaltung

Das Überschreiben der Systempinsel erfolgt in der Regel auf App- oder Seitenebene, und in beiden Fällen wirkt sich die Farbüberschreibung auf alle Steuerelemente aus, die auf diesen Pinsel verweisen – und in XAML können viele Steuerelemente auf denselben Systempinsel verweisen.

<Page.Resources>
    <ResourceDictionary>
        <ResourceDictionary.ThemeDictionaries>
            <ResourceDictionary x:Key="Light">
                 <SolidColorBrush x:Key="ButtonBackground" Color="Transparent"/>
                 <SolidColorBrush x:Key="ButtonForeground" Color="MediumSlateBlue"/>
                 <SolidColorBrush x:Key="ButtonBorderBrush" Color="MediumSlateBlue"/>
            </ResourceDictionary>
        </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>
</Page.Resources>

Für Zustände wie PointerOver (mauszeigert über die Schaltfläche), PointerPressed (Schaltfläche wurde aufgerufen) oder deaktiviert (Schaltfläche ist nicht interagierbar). Diese Endungen werden an die ursprünglichen Lightweight-Formatnamen angefügt: ButtonBackgroundPointerOver, ButtonForegroundPressed, ButtonBorderBrushDisabledusw. Wenn Sie diese Pinselstriche auch ändern, stellen Sie sicher, dass Ihre Steuerelemente dem Design Ihrer App entsprechen.

Wenn Sie diese Pinselüberschreibungen auf der App.Resources--Ebene platzieren, werden alle Schaltflächen der gesamten App anstelle einer einzelnen Seite verändert.

Stilgestaltung pro Steuerelement

In anderen Fällen ist es wünschenswert, ein einzelnes Steuerelement auf einer Seite so zu ändern, dass es auf eine bestimmte Weise aussieht, ohne andere Versionen dieses Steuerelements zu verändern.

Screenshot von drei gestalteten Schaltflächen, die übereinander gestapelt sind.

<CheckBox Content="Normal CheckBox" Margin="5"/>
<CheckBox Content="Special CheckBox" Margin="5">
    <CheckBox.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary x:Key="Light">
                    <SolidColorBrush x:Key="CheckBoxForegroundUnchecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxForegroundChecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckGlyphForegroundChecked"
                        Color="White"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundStrokeChecked"  
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundFillChecked"
                        Color="Purple"/>
                </ResourceDictionary>
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </CheckBox.Resources>
</CheckBox>
<CheckBox Content="Normal CheckBox" Margin="5"/>

Dies würde nur das eine spezielle Kontrollkästchen auf der Seite betreffen, auf der dieses Steuerelement existierte.

Benutzerdefinierte Steuerelemente

Wenn Sie Ihre eigenen benutzerdefinierten Steuerelemente erstellen, die möglicherweise optisch und/oder funktionell mit unseren integrierten Steuerelementen übereinstimmen, sollten Sie die Verwendung impliziter Formatierungs- und leichter Formatierungsressourcen in Betracht ziehen, um Ihre benutzerdefinierten Inhalte zu definieren. Sie können die Ressourcen entweder direkt verwenden oder einen neuen Alias für die Ressource erstellen.

Direkte Nutzung von Steuerungsressourcen

Wenn Sie beispielsweise ein Steuerelement erstellen, das wie eine Schaltfläche aussieht, kann Ihr Steuerelement direkt auf die Schaltflächenressourcen zugreifen, so:

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource ButtonBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource ButtonBorderBrush}" />
</Style>

Umbenennung von Kontrollressourcen für neue Namen

Alternativ, wenn Sie Ihre eigenen Ressourcen erstellen möchten, sollten Sie diese benutzerdefinierten Namen unseren voreingestellten Leichtgewicht-Stilressourcen zuordnen.

Die Formatvorlage Ihres benutzerdefinierten Steuerelements kann beispielsweise spezielle Ressourcendefinitionen enthalten:

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource MyCustomControlBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource MyCustomControlBorderBrush}"/>
</Style>

In Ihrem Ressourcenwörterbuch oder Ihrer Hauptdefinition würden Sie die leichten Formatierungsressourcen mit Ihren benutzerdefinierten Ressourcen verknüpfen:

<ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>        
    <ResourceDictionary x:Key="Light">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>

Es ist erforderlich, dass Sie eine ThemeDictionary verwenden, die dreimal dupliziert wird, um die drei verschiedenen Themenänderungen ordnungsgemäß zu behandeln (Default, Light, HighContrast).

Vorsicht

Wenn Sie einem neuen Alias eine Ressource für eine leichte Formatierung zuweisen und auch die Ressource für die leichte Formatierung neu definieren, wird Ihre Anpassung möglicherweise nicht angewendet, wenn die Ressourcensuche nicht in der richtigen Reihenfolge erfolgt. Wenn Sie z. B. ButtonBackground an einer Stelle außer Kraft setzen, die durchsucht wird, bevor MyCustomControlBackground gefunden wird, wird die Außerkraftsetzung verpasst.

Vermeiden Sie das Restyling von Steuerelementen

WinUI 2.2 oder höher enthält neue Stile und Vorlagen für WinUI- und Systemsteuerelemente.

Die beste Möglichkeit, mit unseren neuesten visuellen Stilen auf dem Laufenden zu bleiben, besteht darin, das neueste WinUI 2-Paket zu verwenden und benutzerdefinierte Stile und Vorlagen (auch als Neutemplating bezeichnet) zu vermeiden. Stile sind immer noch eine bequeme Möglichkeit, eine Reihe von Werten konsistent über Steuerelemente in Ihrer App anzuwenden. Stellen Sie dabei sicher, dass Sie unsere neuesten Stile berücksichtigen.

Für Systemsteuerelemente, die WinUI-Stile (Windows.UI.Xaml.Controls Namespace) verwenden, legen Sie fest BasedOn="{StaticResource Default<ControlName>Style}", wo <ControlName> der Name des Steuerelements steht. Beispiel:

<Style TargetType="TextBox" BasedOn="{StaticResource DefaultTextBoxStyle}">
    <Setter Property="Foreground" Value="Blue"/>
</Style>

Für WinUI 2-Steuerelemente (Microsoft.UI.Xaml.Controls Namespace) wird der Standardstil in den Metadaten definiert, also weglassen BasedOn.

Abgeleitete Steuerelemente

Wenn Sie ein benutzerdefiniertes Steuerelement von einem vorhandenen XAML-Steuerelement ableiten, werden die WinUI 2-Formatvorlagen standardmäßig nicht übernommen. So wenden Sie die WinUI 2-Formatvorlagen an:

Erstellen Sie ein neues Style-, dessen TargetType- auf Ihr benutzerdefiniertes Steuerelement festgelegt ist.
Basieren Sie die Formatvorlage auf der Standardformatvorlage des Steuerelements, von dem Sie es abgeleitet haben.

Ein häufiges Szenario hierfür ist es, ein neues Steuerelement von ContentDialogabzuleiten. In diesem Beispiel wird gezeigt, wie Sie eine neue Formatvorlage erstellen, die DefaultContentDialogStyle auf Ihr benutzerdefiniertes Dialogfeld anwendet.

<ContentDialog
    x:Class="ExampleApp.SignInContentDialog"
    ... >

    <ContentDialog.Resources>
        <Style TargetType="local:SignInContentDialog" BasedOn="{StaticResource DefaultContentDialogStyle}"/>
        ...
    </ContentDialog.Resources> 
    <!-- CONTENT -->
</ContentDialog>

Die Vorlageneigenschaft

Ein Stil-Setter kann für die Template--Eigenschaft eines Controlverwendet werden, und tatsächlich bilden er die Mehrheit der typischen XAML-Stile und der XAML-Ressourcen einer App. Dies wird im Thema Steuerungsvorlagenausführlicher besprochen.