Titelrad

TitleBar-kontrollen ger ett förenklat sätt att skapa en anpassad titelrad för din app. Namnlisten är en grundläggande komponent i en Windows-appens användargränssnitt som identifierar appen via dess ikon och rubrik, innehåller knapparna för systemtext som gör att en användare kan stänga, maximera, minimera och återställa fönstret och låta en användare dra fönstret runt skärmen.

Du kan använda en anpassad titelrad för att bättre integrera den med appens användargränssnitt. Titelraden kan anpassas så att den matchar appens visuella stil med hjälp av Mica-temaning. Den kan innehålla annan relevant information, till exempel en dokumentrubrik eller det aktuella tillståndet (t.ex. "Redigering", "Visning" osv.). Den kan också vara värd för andra WinUI 3-kontroller, till exempel AutoSuggestBox och PersonPicture, vilket ger en sammanhängande användarupplevelse för din app.

Skärmbild av ett applikationsfönster med en anpassad titelrad

Är det här rätt kontroll?

Använd kontrollen TitleBar när du vill integrera området med namnlisten med ditt appgränssnitt med hjälp av anpassningar som undertexter, Mica-teman och integreringar med WinUI-kontroller.

Anatomi

Som standard visar namnlisten bara knapparna för systemrubrik. Andra delar av namnlisten visas eller döljs beroende på associerade egenskapsinställningar.

Titelraden är indelad i följande områden:

Skärmbild som visar delarna i ett kontrollfält för namnlist.

Layouten vänds när FlowDirection är RightToLeft.

Skapa en titellist

Öppna WinUI 3-galleriappen och se titlebaren i praktiken

WinUI 3-galleriikon WinUI 3-galleriappen innehåller interaktiva exempel på WinUI-kontroller och funktioner. Hämta appen från Microsoft Store eller bläddra i källkoden på GitHub.

I det här exemplet skapas en enkel titelrad som ersätter systemets titelrad. Den har en rubrik, en ikon och Mica-tema.

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

Integrering med NavigationView

Navigeringsvyn har en inbyggd bakåtknapp och växlingsknapp för fönster. Fluent Design-vägledningen rekommenderar att dessa kontroller placeras i titelraden när en anpassad titelrad används.

Det här exemplet visar hur du integrerar kontrollen TitleBar med en NavigationView-kontroll genom att dölja bakåtknappen och växlingsknappen i navigeringsvyn och använda motsvarande knappar i namnlisten i stället.

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

Anpassa dragområden

Användare flyttar ett fönster genom att dra dess titelrad. Kontrollen TitleBar avgör vilka delar av dess innehållsområde som användare kan dra och vilka delar som tar emot pekarindata, till exempel klick.

Från och med Windows App SDK 2.1.3 undersöker kontrollen TitleBar elementen i innehållet och utesluter endast interaktiva kontroller, till exempel knappar, textrutor och kombinationsrutor, från dragregionen. Tomt utrymme och icke-interaktiva element, till exempel en TextBlock, kan dras som standard, så du behöver inte ändra din markup. I tidigare versioner kunde tomt utrymme i innehållsområdet blockera fönsterdrag. Det här standardbeteendet är kompatibilitetsändringen TitleBar_ContentDragRegions för körning. Mer information finns i RuntimeCompatibilityOptions.DisabledChanges.

Följande exempel baseras på WinUI 3-galleriets exempel. Innehållet i namnfältet är ett Grid som innehåller en AutoSuggestBox och en knapp. Båda kontrollerna kan klickas och det tomma utrymmet bredvid dem kan dras.

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

Åsidosätt dragbeteendet för ett element

Om du vill åsidosätta standardbeteendet för ett element i rubrikfältets innehåll anger du den kopplade egenskapen TitleBar.IsDragRegion. Egenskapen är ett booleskt värde som kan vara null.

Value Behavior
Inte angivet (null) TitleBar-kontrollen bestämmer. Interaktiva kontroller kan klickas och andra element kan dras.
True Elementet kan dras, även om det är en interaktiv kontroll. Pekarinmatning på elementet flyttar fönstret så att användarna inte kan klicka på elementet.
False Elementet kan klickas, även om det inte är en interaktiv kontroll.

Du kan ange egenskapen på en panel, till exempel en StackPanel:

  • Om du ställer in det på False kan hela panelområdet vara klickbart, inklusive utrymmet mellan dess underordnade.
  • Om du ställer in den på Truekan panelen och dess underordnade objekt dras, med undantag för underordnade objekt där du anger egenskapen till False.

Ange egenskapen på det minsta element som behöver det, så att du inte av misstag gör ett stort område i namnlisten dragbart eller klickbart.

Det här exemplet gör en grupp formateringskontroller klickbara som helhet, så att användarna inte drar fönstret när de klickar på mellanrummet mellan kontrollerna.

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

I kod anropar du SetIsDragRegion för att ange värdet och anropar ClearValue med IsDragRegionProperty för att återgå till standardbeteendet. Om du vill läsa värdet anropar du GetIsDragRegion. Den returnerar null om egenskapen inte har angetts. När värdet ändras uppdaterar kontrollen TitleBar sina dragregioner.

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

Uppdatera dragregioner när innehållet ändras

Kontrollen TitleBar uppdaterar sina dragregioner när du anger eller ersätter dess innehåll, när innehållet läses in, när namnlisten ändrar storlek och när värdet för TitleBar.IsDragRegion ändras på ett element.

Om du lägger till, tar bort eller ändrar storlek på element i rubrikfältets innehåll vid körning ska du anropa RecomputeDragRegions efter att du gjort ändringen.

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

Om innehållet i namnfältet ändras ofta kan du i stället ställa in AutoRefreshDragRegions till True. Kontrollen TitleBar uppdaterar sedan sina dragregioner efter varje layoutpass. Det här alternativet kan påverka prestanda, så det är avstängt False som standard.

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

Note

Dragregioner påverkar endast pekarindata. De ändrar inte tangentbordsfokus eller hur UI Automation-klienter, till exempel skärmläsare, interagerar med elementen i titelraden. Kontrollera att de interaktiva kontrollerna i namnlisten fortfarande kan nås med tangentbordet.

Om din app inte använder kontrollen TitleBar ska du använda klassen InputNonClientPointerSource för att ange de interaktiva regionerna i din anpassade titelrad. Mer information finns i Interaktivt innehåll.

  • Uppdaterades senast