Barre de titre

Le contrôle TitleBar offre un moyen simplifié de créer une barre de titre personnalisée pour votre application. La barre de titre est un composant fondamental de l'interface utilisateur d'une application Windows qui identifie l'application via son icône et son titre, héberge les boutons de légende système qui permettent à un utilisateur de fermer, d'optimiser, de réduire et de restaurer la fenêtre et de faire glisser la fenêtre autour de l'écran.

Vous pouvez utiliser une barre de titre personnalisée pour mieux intégrer la zone de barre de titre à l’interface utilisateur de votre application. La barre de titre peut être personnalisée pour correspondre au style visuel de l’application à l’aide de thèmes Mica. Il peut inclure d’autres informations pertinentes, telles qu’un titre de document ou l’état actuel (par exemple, « Édition », « Affichage », etc.). Il peut également héberger d’autres contrôles WinUI 3, tels que AutoSuggestBox et PersonPicture, fournissant une expérience utilisateur cohérente pour votre application.

Est-ce le contrôle approprié ?

Utilisez le contrôle TitleBar lorsque vous souhaitez intégrer la zone de barre de titre à l’interface utilisateur de votre application à l’aide de personnalisations telles que les sous-titres, les thèmes Mica et les intégrations avec les contrôles WinUI.

Anatomie

Par défaut, la barre de titre affiche uniquement les boutons de légende système. D’autres parties de la barre de titre sont affichées ou masquées en fonction des paramètres de propriété associés.

La barre de titre est divisée en zones suivantes :

• Bouton Précédent :IsBackButtonEnabled, IsBackButtonVisible, BackRequested - Un bouton Précédent intégré pour faciliter la navigation.
• Bouton de bascule volet :IsPaneToggleButtonVisible, PaneToggleRequested - ce bouton est destiné à être utilisé conjointement avec le contrôle NavigationView.
• En-tête gauche :LeftHeader
• Icône :IconSource
• Titre :Titre
• Sous-titre :Sous-titre
• Contenu :Contenu
• En-tête droit :RightHeader
• Min drag region : Cette zone est réservée en regard des boutons de légende système afin que l’utilisateur dispose toujours d’un emplacement pour attraper et déplacer la fenêtre.
• Boutons de légende système : Ces boutons ne font pas partie du contrôle TitleBar : il alloue simplement de l’espace où les boutons de légende apparaissent, en fonction des paramètres RTL ou LTR. Les boutons de légende et les personnalisations sont gérés par AppWindowTitleBar.

La disposition est inversée lorsque FlowDirection est RightToLeft.

Créer une barre de titre

L’application Galerie WinUI 3 inclut des exemples interactifs de contrôles et de fonctionnalités WinUI. Obtenez l’application à partir du Microsoft Store ou parcourez le code source sur GitHub.

Cet exemple crée une barre de titre simple qui remplace la barre de titre système. Il a un titre, une icône et un thème Mica.

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

Intégration à NavigationView

Le mode Navigation comporte un bouton précédent intégré et un bouton bascule du volet. Les instructions Fluent Design recommandent que ces contrôles soient placés dans la barre de titre lorsqu’une barre de titre personnalisée est utilisée.

Cet exemple montre comment intégrer le contrôle TitleBar à un contrôle NavigationView en masquant le bouton Précédent et le bouton bascule du volet dans l’affichage de navigation et en utilisant les boutons correspondants dans la barre de titre à la place.

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

Personnaliser les zones de glissement

Les utilisateurs déplacent une fenêtre en faisant glisser sa barre de titre. Le contrôle TitleBar détermine quelles parties de sa zone de contenu les utilisateurs peuvent faire glisser et quelles parties reçoivent une entrée de pointeur, par exemple des clics.

À compter de SDK d'application Windows 2.1.3, le contrôle TitleBar examine les éléments de son contenu et exclut uniquement les contrôles interactifs, tels que les boutons, les zones de texte et les zones de liste modifiable, de la zone de déplacement. L’espace vide et les éléments non interactifs, tels qu’un TextBlock, peuvent être déplacés par glisser-déposer par défaut, vous n’avez donc pas besoin de modifier votre balisage. Dans les versions antérieures, l’espace vide dans la zone de contenu pouvait bloquer le déplacement de la fenêtre. Ce comportement par défaut est le changement de compatibilité du runtime TitleBar_ContentDragRegions. Pour plus d’informations, consultez RuntimeCompatibilityOptions.DisabledChanges.

L’exemple suivant est basé sur l’exemple de galerie WinUI 3. Le contenu de la barre de titre est une grille qui contient un AutoSuggestBox et un bouton. Les deux contrôles sont cliquables, et l’espace vide en regard d’eux est déplaçable.

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

Redéfinir le comportement de glisser d’un élément

Pour redéfinir le comportement par défaut d’un élément dans le contenu de la barre de titre, définissez la propriété jointe TitleBar.IsDragRegion. La propriété est une valeur booléenne pouvant être nulle.

Vous pouvez définir la propriété sur un panneau, tel qu’un StackPanel :

• Si vous le définissez sur False, la zone entière du panneau est cliquable, y compris l’espace entre ses enfants.
• Si vous la définissez sur True, le panneau et ses enfants sont déplaçables, à l’exception des enfants où vous définissez la propriété sur False.

Définissez la propriété sur le plus petit élément qui en a besoin, afin de ne pas rendre par inadvertance une grande zone de la barre de titre déplaçable ou cliquable.

Cet exemple montre comment rendre un groupe de contrôles de mise en forme cliquable dans son ensemble, afin que les utilisateurs ne fassent pas glisser la fenêtre lorsqu’ils appuient sur l’espace entre les contrôles.

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

Dans le code, appelez SetIsDragRegion pour définir la valeur et appelez ClearValue avec IsDragRegionProperty pour revenir au comportement par défaut. Pour lire la valeur, appelez GetIsDragRegion. Elle retourne null si la propriété n’est pas définie. Lorsque la valeur change, le contrôle TitleBar met à jour ses zones de déplacement.

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

Mettre à jour les zones de glissement lorsque le contenu change

Le contrôle TitleBar met à jour ses régions de glissement lorsque vous définissez ou remplacez son contenu, lorsque le contenu se charge, lorsque la barre de titre change de taille et lorsque la valeur de TitleBar.IsDragRegion change sur un élément.

Si vous ajoutez, supprimez ou redimensionnez des éléments dans le contenu de la barre de titre au moment de l’exécution, appelez RecomputeDragRegions après avoir apporté la modification.

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

Si le contenu de la barre de titre change souvent, vous pouvez définir AutoRefreshDragRegions à la place de True. Le contrôle TitleBar met ensuite à jour ses régions de glissement après chaque passe de disposition. Cette option peut affecter les performances. Elle est False par défaut.

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

Si votre application n’utilise pas le contrôle TitleBar, utilisez la classe InputNonClientPointerSource pour définir les régions interactives de votre barre de titre personnalisée. Pour plus d’informations, consultez contenu interactif.

Articles connexes

• Barre de titre (design)
• Personnalisation de la barre de titre
• TitleBar, classe