Titelbalk

Het besturingselement TitleBar biedt een vereenvoudigde manier om een aangepaste titelbalk voor uw app te maken. De titelbalk is een fundamenteel onderdeel van de gebruikersinterface van een Windows-app die de app identificeert via het pictogram en de titel, bevat de knoppen voor systeembijschriften waarmee een gebruiker het venster kan sluiten, maximaliseren, minimaliseren en herstellen, en waarmee een gebruiker het venster rond het scherm kan slepen.

U kunt een aangepaste titelbalk gebruiken om het titelbalkgebied beter te integreren met de gebruikersinterface van uw app. De titelbalk kan worden aangepast aan de visuele stijl van de app met behulp van Mica-thema's. Het kan andere relevante informatie bevatten, zoals een documenttitel of de huidige status (bijvoorbeeld 'Bewerken', 'Weergeven', enzovoort). Het kan ook andere WinUI 3-besturingselementen hosten, zoals AutoSuggestBox en PersonPicture, wat een samenhangende gebruikerservaring biedt voor uw app.

Schermopname van een app-venster met een aangepaste titelbalk

Is dit de juiste controle?

Gebruik de TitleBar-control wanneer u het titelbalkgebied wilt integreren in de gebruikersinterface van uw app met aanpassingen zoals ondertitels, Mica-thema's en integraties met WinUI-controls.

Anatomie

Op de titelbalk worden standaard alleen de knoppen voor systeembijschriften weergegeven. Andere onderdelen van de titelbalk worden weergegeven of verborgen, afhankelijk van de bijbehorende eigenschapsinstellingen.

De titelbalk is onderverdeeld in deze gebieden:

Schermopname van de onderdelen van een titelbalk.

Terugknop:IsBackButtonEnabled, IsBackButtonVisible, BackRequested - Een geïntegreerde terugknop voor navigatie.
Wisselknop Deelvenster:IsPaneToggleButtonVisible, PaneToggleRequested - Deze knop is bedoeld om te worden gebruikt in combinatie met de NavigationView-control.
Linkerkoptekst:LeftHeader
Pictogram:IconSource
Titel:Titel
Ondertitel:Ondertitel
Inhoud:Inhoud
Rechterkoptekst:RightHeader
Minimale sleepregio: Dit gebied is gereserveerd naast de systeemknoppen, zodat de gebruiker altijd een plek heeft om het venster vast te houden voor slepen.
Knoppen voor systeembijschrift: Deze knoppen maken geen deel uit van het besturingselement Titelbalk. Er wordt gewoon ruimte toegewezen waar de bijschriftknoppen worden weergegeven, afhankelijk van de instellingen voor RTL of LTR. Bijschriftknoppen en aanpassingen worden verwerkt door de AppWindowTitleBar.

De indeling wordt omgekeerd wanneer de FlowDirectionRightToLeftis.

Een titelbalk maken

Belangrijke API's:titelbalkklasse, eigenschap Titel

Open de WinUI 3 Gallery-app en zie de titelbalk in actie

De WinUI 3 Gallery-app bevat interactieve voorbeelden van WinUI-besturingselementen en -functies. Haal de app op uit de Microsoft Store of blader door de broncode op GitHub.

In dit voorbeeld wordt een eenvoudige titelbalk gemaakt die de systeemtitelbalk vervangt. Het heeft een titel, pictogram en Mica thema.

<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); 
}

Integratie met NavigationView

De navigatieweergave heeft een ingebouwde knop Terug en wisselknop voor deelvensters. Fluent Design-richtlijnen raden aan dat deze besturingselementen in de titelbalk worden geplaatst wanneer een aangepaste titelbalk wordt gebruikt.

In dit voorbeeld ziet u hoe u de titelbalk kunt integreren met een navigatieweergave-besturingselement door de terug-knop en de paneelwisselknop in de navigatieweergave te verbergen en door in plaats daarvan de bijbehorende knoppen op de titelbalk te gebruiken.

<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;
}

Sleepgebieden aanpassen

Gebruikers verplaatsen een venster door de titelbalk ervan te slepen. Het besturingselement TitleBar bepaalt welke onderdelen van het Content-gebied gebruikers kunnen slepen en welke onderdelen pointerinvoer ontvangen, zoals klikken.

Vanaf Windows App SDK 2.1.3 onderzoekt het besturingselement Titelbalk de elementen in de inhoud en sluit het alleen interactieve besturingselementen, zoals knoppen, tekstvakken en keuzelijsten met invoervak, uit van het sleepgebied. Lege ruimte en niet-interactieve elementen, zoals een TextBlock, zijn standaard versleepbaar, dus u hoeft uw opmaak niet te wijzigen. In eerdere versies kon lege ruimte in het inhoudsgebied het slepen van vensters blokkeren. Dit standaardgedrag is de TitleBar_ContentDragRegions runtimecompatibiliteitswijziging. Zie RuntimeCompatibilityOptions.DisabledChanges voor meer informatie.

Belangrijke API's:TitleBar.IsDragRegion attached property, AutoRefreshDragRegions property, RecomputeDragRegions method

Het volgende voorbeeld is gebaseerd op het WinUI 3 Gallery-voorbeeld. De inhoud van de titelbalk is een Grid dat een AutoSuggestBox en een knop bevat. Beide besturingselementen zijn klikbaar en de lege ruimte ernaast is versleepbaar.

<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>

Het sleepgedrag van een element overschrijven

Als u het standaardgedrag voor een element in de inhoud van de titelbalk wilt overschrijven, stelt u de gekoppelde eigenschap TitleBar.IsDragRegion in. De eigenschap is een booleaanse waarde die null kan zijn.

Value	Behavior
Niet ingesteld (`null`)	Het besturingselement TitleBar bepaalt. Interactieve bedieningselementen zijn klikbaar en andere elementen kunnen worden gesleept.
`True`	Het element kan worden gesleept, zelfs als het een interactief besturingselement is. Aanwijzerinvoer op het element verplaatst het venster, zodat gebruikers niet op het element kunnen klikken.
`False`	Het element kan worden geklikt, zelfs als het geen interactief besturingselement is.

U kunt de eigenschap instellen op een panel, zoals een StackPanel:

Als u dit instelt op False, is het hele gedeelte van het deelvenster klikbaar, inclusief de ruimte tussen de onderliggende elementen.
Als u dit instelt op True, kunnen het paneel en de onderliggende elementen worden gesleept, met uitzondering van onderliggende elementen waarop u de eigenschap False instelt.

Stel de eigenschap in op het kleinste element dat dit nodig heeft, zodat u niet per ongeluk een groot deel van de titelbalk versleepbaar maakt of erop kunt klikken.

In dit voorbeeld kan op een groep opmaakbesturingselementen als geheel worden geklikt, zodat gebruikers het venster niet slepen wanneer ze op de ruimte tussen de besturingselementen klikken.

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

Roep in code SetIsDragRegion aan om de waarde in te stellen en roep ClearValue aan met IsDragRegionProperty om terug te keren naar het standaardgedrag. Als u de waarde wilt lezen, roept u GetIsDragRegion aan. Het retourneert null als de eigenschap niet is ingesteld. Wanneer de waarde wordt gewijzigd, werkt het besturingselement TitleBar de sleepregio's bij.

// 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);

Sleepgebieden bijwerken wanneer de inhoud wordt gewijzigd

Het besturingselement TitleBar werkt de sleepregio's bij wanneer u de inhoud instelt of vervangt, wanneer de inhoud wordt geladen, wanneer de titelbalk de grootte wijzigt en wanneer de waarde van TitleBar.IsDragRegion op een element verandert.

Als u tijdens runtime elementen toevoegt, verwijdert of het formaat ervan wijzigt in de inhoud van de titelbalk, roept u RecomputeDragRegions aan nadat u de wijziging hebt aangebracht.

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();
}

Als de inhoud van de titelbalk vaak wordt gewijzigd, kunt u AutoRefreshDragRegions in plaats daarvan instellen op True. Het TitleBar-besturingselement werkt vervolgens de sleepregio's bij na elke lay-outcyclus. Deze optie kan van invloed zijn op de prestaties, dus staat deze standaard False.

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

Note

Sleepgebieden hebben alleen invloed op de invoer van de aanwijzer. Ze wijzigen de focus van het toetsenbord niet of hoe UI Automation clients, zoals schermlezers, communiceren met de elementen in de titelbalk. Zorg ervoor dat de interactieve besturingselementen in de titelbalk nog steeds bereikbaar zijn met het toetsenbord.

Als uw app het besturingselement TitleBar niet gebruikt, gebruikt u de klasse InputNonClientPointerSource om de interactieve regio's van uw aangepaste titelbalk in te stellen. Zie Interactieve inhoud voor meer informatie.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-10-15