Titelleiste

Das TitleBar-Steuerelement bietet eine vereinfachte Möglichkeit zum Erstellen einer benutzerdefinierten Titelleiste für Ihre App. Die Titelleiste ist eine grundlegende Komponente der Benutzeroberfläche einer Windows App, die die App über das Symbol und den Titel identifiziert, die Systembeschriftungsschaltflächen enthält, mit denen ein Benutzer das Fenster schließen, maximieren, minimieren und wiederherstellen kann und ein Benutzer das Fenster über den Bildschirm ziehen kann.

Sie können eine benutzerdefinierte Titelleiste verwenden, um den Titelleistenbereich besser in die App-UI zu integrieren. Die Titelleiste kann so angepasst werden, dass sie dem visuellen Stil der App mit dem Mica-Design entspricht. Sie kann andere relevante Informationen enthalten, z. B. einen Dokumenttitel oder den aktuellen Status (z. B. "Bearbeiten", "Anzeigen" usw.). Sie kann auch andere WinUI 3-Steuerelemente hosten, z. B. AutoSuggestBox und PersonPicture, die eine einheitliche Benutzeroberfläche für Ihre App bieten.

Ist dies das richtige Steuerelement?

Verwenden Sie das TitleBar-Steuerelement, wenn Sie den Titelleistenbereich mithilfe von Anpassungen wie Untertiteln, Mica-Design und Integrationen mit WinUI-Steuerelementen in die App-Benutzeroberfläche integrieren möchten.

Anatomie

Standardmäßig zeigt die Titelleiste nur die Beschriftungsschaltflächen des Systems an. Andere Teile der Titelleiste werden je nach den zugehörigen Eigenschafteneinstellungen angezeigt oder ausgeblendet.

Die Titelleiste ist in diese Bereiche unterteilt:

• Zurück-Schaltfläche:IsBackButtonEnabled, IsBackButtonVisible, BackRequested – Eine integrierte Zurück-Schaltfläche für die Navigation.
• Umschaltfläche:IsPaneToggleButtonVisible, PaneToggleRequested – Diese Schaltfläche ist zur Verwendung in Verbindung mit dem NavigationView-Steuerelement gedacht.
• Linke Kopfzeile:LeftHeader
• Icon:IconSource
• Titel:Titel
• Untertitel:Untertitel
• Inhalt:Inhalt
• Rechte Kopfzeile:RightHeader
• Mindestziehbereich: Dieser Bereich ist neben den Beschriftungsschaltflächen des Systems reserviert, sodass der Benutzer immer einen Ort zum Ziehen des Fensters hat.
• Schaltflächen für Systembeschriftung: Diese Schaltflächen sind nicht Teil des Steuerelements der Titelleiste – es weist einfach Platz dafür zu, wo die Beschriftungs-Schaltflächen angezeigt werden, je nach RTL- oder LTR-Einstellungen. Beschriftungsschaltflächen und Anpassungen werden von der AppWindowTitleBar behandelt.

Das Layout wird umgedreht, wenn die FlowDirectionRightToLeftist.

Erstellen einer Titelleiste

Die WinUI 3 Gallery-App enthält interaktive Beispiele für WinUI-Steuerelemente und -Features. Rufen Sie die App aus dem Microsoft Store ab, oder durchsuchen Sie den Quellcode auf GitHub.

In diesem Beispiel wird eine einfache Titelleiste erstellt, die die Systemtitelleiste ersetzt. Es hat einen Titel, ein Symbol und ein Mica-Design.

<Window
    ...  >
    <Window.SystemBackdrop>
        <MicaBackdrop Kind="Base"/>
    </Window.SystemBackdrop>

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>

        <TitleBar x:Name="SimpleTitleBar"
                  Title="My App">
            <TitleBar.IconSource>
                <FontIconSource Glyph="&#xF4AA;"/>
            </TitleBar.IconSource>
        </TitleBar>

        <!-- App content -->
        <Frame x:Name="RootFrame" Grid.Row="1"/>
    </Grid>
</Window>

public MainWindow()
{
    this.InitializeComponent();

    // Hides the default system title bar.
    ExtendsContentIntoTitleBar = true;
    // Replace system title bar with the WinUI TitleBar control. 
    SetTitleBar(SimpleTitleBar); 
}

Integration in NavigationView

Die Navigationsansicht verfügt über einen integrierten Zurück-Button und einen Umschalt-Button für das Fenster. Fluent Designleitfaden empfiehlt, dass diese Steuerelemente in der Titelleiste platziert werden, wenn eine benutzerdefinierte Titelleiste verwendet wird.

In diesem Beispiel wird veranschaulicht, wie Sie das TitleBar-Steuerelement mit dem NavigationView-Steuerelement integrieren, indem Sie die Zurück-Schaltfläche und die Bereichsumschaltfläche in der Navigationsansicht ausblenden und stattdessen die entsprechenden Schaltflächen in der Titelleiste verwenden.

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition Height="*" />
    </Grid.RowDefinitions>

    <TitleBar Title="My App"
              IsBackButtonVisible="True"
              IsBackButtonEnabled="{x:Bind RootFrame.CanGoBack, Mode=OneWay}"
              BackRequested="TitleBar_BackRequested"
              IsPaneToggleButtonVisible="True"
              PaneToggleRequested="TitleBar_PaneToggleRequested">
    </TitleBar>

    <NavigationView x:Name="RootNavigationView" Grid.Row="1"
                    IsBackButtonVisible="Collapsed"
                    IsPaneToggleButtonVisible="False">
        <Frame x:Name="RootFrame" />
    </NavigationView>
</Grid>

private void TitleBar_BackRequested(TitleBar sender, object args)
{
    if (RootFrame.CanGoBack)
    {
        RootFrame.GoBack();
    }
}

private void TitleBar_PaneToggleRequested(TitleBar sender, object args)
{
    RootNavigationView.IsPaneOpen = !RootNavigationView.IsPaneOpen;
}

Ziehbereiche anpassen

Benutzer verschieben ein Fenster, indem sie die Titelleiste ziehen. Das TitleBar-Steuerelement bestimmt, welche Teile des Inhaltsbereichs Benutzer ziehen können und welche Teile Zeigereingaben erhalten, z. B. Klicks.

Ab Windows App SDK 2.1.3 untersucht das TitleBar-Steuerelement die Elemente im Inhalt und schließt nur interaktive Steuerelemente wie Schaltflächen, Textfelder und Kombinationsfelder aus dem Ziehbereich aus. Leerraum und nicht interaktive Elemente, z. B. TextBlock, können standardmäßig gezogen werden, sodass Sie Ihr Markup nicht ändern müssen. In früheren Versionen konnte leerer Platz im Inhaltsbereich das Ziehen des Fensters blockieren. Dieses Standardverhalten ist die Änderung an der TitleBar_ContentDragRegions Laufzeitkompatibilität. Weitere Informationen finden Sie unter RuntimeCompatibilityOptions.DisabledChanges.

Das folgende Beispiel basiert auf dem WinUI 3 Gallery-Beispiel. Der Inhalt der Titelleiste ist ein Grid, das eine AutoSuggestBox und eine Schaltfläche enthält. Beide Steuerelemente können geklickt werden, und der leere Platz daneben ist verschiebbar.

<TitleBar x:Name="AppTitleBar" Title="My App">
    <TitleBar.Resources>
        <!-- Stretch the content across the available width of the title bar. -->
        <HorizontalAlignment x:Key="TitleBarContentHorizontalAlignment">Stretch</HorizontalAlignment>
    </TitleBar.Resources>
    <TitleBar.Content>
        <Grid ColumnSpacing="8">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*" />
                <ColumnDefinition Width="Auto" />
            </Grid.ColumnDefinitions>

            <AutoSuggestBox MaxWidth="580"
                            VerticalAlignment="Center"
                            PlaceholderText="Search..."
                            QueryIcon="Find" />

            <StackPanel x:Name="RightPanel"
                        Grid.Column="1"
                        Orientation="Horizontal"
                        Spacing="8"
                        VerticalAlignment="Center">
                <Button x:Name="StatusButton"
                        Content="Status"
                        Click="StatusButton_Click" />
            </StackPanel>
        </Grid>
    </TitleBar.Content>
</TitleBar>

Überschreiben des Ziehverhaltens eines Elements

Um das Standardverhalten für ein Element im Titelleisteninhalt außer Kraft zu setzen, legen Sie die angefügte TitleBar.IsDragRegion-Eigenschaft fest. Die Eigenschaft ist ein boolescher Wert, der NULL zulassen kann.

Sie können die Eigenschaft für ein Panel festlegen, z. B. ein StackPanel:

• Wenn Sie ihn auf False festlegen, ist der gesamte Bereich des Panels anklickbar, einschließlich des Abstands zwischen den untergeordneten Elementen.
• Wenn Sie sie auf True festlegen, können das Panel und die untergeordneten Elemente gezogen werden, mit Ausnahme von untergeordneten Elementen, bei denen Sie die Eigenschaft auf False festlegen.

Legen Sie die Eigenschaft für das kleinste Element fest, das sie benötigt, damit nicht versehentlich ein großer Bereich der Titelleiste ziehbar oder anklickbar wird.

In diesem Beispiel wird eine Gruppe von Formatierungssteuerelementen als Ganzes anklickbar gemacht, sodass Benutzer das Fenster nicht ziehen, wenn sie auf den Bereich zwischen den Steuerelementen klicken.

<StackPanel Orientation="Horizontal" Spacing="8" TitleBar.IsDragRegion="False">
    <ComboBox PlaceholderText="Font" />
    <ComboBox PlaceholderText="Size" />
    <ToggleButton Content="Bold" />
</StackPanel>

Rufen Sie im Code SetIsDragRegion auf, um den Wert festzulegen, und rufen Sie ClearValue mit IsDragRegionProperty auf, um zum Standardverhalten zurückzukehren. Rufen Sie GetIsDragRegion auf, um den Wert zu lesen. null wird zurückgegeben, wenn die Eigenschaft nicht festgelegt ist. Wenn sich der Wert ändert, aktualisiert das TitleBar-Steuerelement seine Ziehbereiche.

// Make the button draggable. Users can't click it.
TitleBar.SetIsDragRegion(StatusButton, true);

// Make the button clickable.
TitleBar.SetIsDragRegion(StatusButton, false);

// Clear the value so that the TitleBar control decides.
StatusButton.ClearValue(TitleBar.IsDragRegionProperty);

Aktualisieren von Ziehbereichen, wenn sich der Inhalt ändert

Das TitleBar-Steuerelement aktualisiert die Ziehbereiche, wenn Sie den Inhalt festlegen oder ersetzen, wenn der Inhalt geladen wird, wenn die Titelleiste die Größe ändert, und wenn sich der Wert eines TitleBar.IsDragRegion Elements ändert.

Wenn Sie Elemente im Titelleisteninhalt zur Laufzeit hinzufügen, entfernen oder in ihrer Größe ändern, rufen Sie RecomputeDragRegions auf, nachdem Sie die Änderung vorgenommen haben.

private void AddButton_Click(object sender, RoutedEventArgs e)
{
    RightPanel.Children.Insert(0, new Button { Content = "Extra" });

    // Update the drag regions so that the new button is clickable.
    AppTitleBar.RecomputeDragRegions();
}

Wenn sich der Inhalt der Titelleiste häufig ändert, können Sie AutoRefreshDragRegions stattdessen auf True festlegen. Das TitleBar-Steuerelement aktualisiert dann seine Ziehbereiche nach jedem Layoutdurchlauf. Diese Option kann sich auf die Leistung auswirken, daher ist sie standardmäßig False.

<TitleBar x:Name="AppTitleBar" Title="My App" AutoRefreshDragRegions="True">
    <!-- Title bar content that changes at run time. -->
</TitleBar>

Wenn Ihre App das TitleBar-Steuerelement nicht verwendet, verwenden Sie die InputNonClientPointerSource-Klasse, um die interaktiven Bereiche der benutzerdefinierten Titelleiste festzulegen. Weitere Informationen finden Sie unter Interaktive Inhalte.

Verwandte Artikel

• Titelleiste (Entwurf)
• Anpassung der Titelleiste
• TitleBar-Klasse