Barra del titolo

Il controllo TitleBar offre un modo semplificato per creare una barra del titolo personalizzata per l'app. La barra del titolo è un componente fondamentale dell'interfaccia utente di un'app Windows che identifica l'app tramite l'icona e il titolo, ospita i pulsanti di didascalia di sistema che consentono a un utente di chiudere, ingrandire, ridurre al minimo e ripristinare la finestra e consente a un utente di trascinare la finestra intorno allo schermo.

Puoi usare una barra del titolo personalizzata per integrare meglio l'area della barra del titolo con l'interfaccia utente dell'app. La barra del titolo può essere personalizzata in modo che corrisponda allo stile di visualizzazione dell'app usando il tema Mica. Può includere altre informazioni rilevanti, ad esempio un titolo del documento o lo stato corrente,ad esempio "Modifica", "Visualizzazione" e così via. Può anche ospitare altri controlli WinUI 3, ad esempio AutoSuggestBox e PersonPicture, offrendo un'esperienza utente coerente per la tua app.

Questo è il controllo giusto?

Usa il controllo TitleBar quando vuoi integrare l'area della barra del titolo con l'interfaccia utente dell'app usando personalizzazioni come sottotitoli, tema Mica e integrazioni con i controlli WinUI.

Anatomia

Per impostazione predefinita, la barra del titolo mostra solo i pulsanti di didascalia di sistema. Altre parti della barra del titolo vengono visualizzate o nascoste a seconda delle impostazioni delle proprietà associate.

La barra del titolo è suddivisa in queste aree:

• Pulsante Indietro:IsBackButtonEnabled, IsBackButtonVisible, BackRequested - Pulsante Indietro predefinito per la navigazione.
• Pulsante Attiva/Disattiva Riquadro:IsPaneToggleButtonVisible, PaneToggleRequested. Questo pulsante deve essere usato insieme al controllo NavigationView.
• Intestazione sinistra:LeftHeader
• Icon:IconSource
• Titolo:Titolo
• Sottotitolo:Sottotitolo
• Content:Content
• Intestazione destra:RightHeader
• Area di trascinamento minima: Questa area è riservata accanto ai pulsanti di didascalia di sistema in modo che l'utente abbia sempre un posto in cui afferrare la finestra per il trascinamento.
• Pulsanti di didascalia di sistema: Questi pulsanti non fanno parte del controllo TitleBar, ma alloca semplicemente lo spazio in cui vengono visualizzati i pulsanti della didascalia, a seconda delle impostazioni RTL o LTR. I pulsanti e le personalizzazioni della didascalia vengono gestiti da AppWindowTitleBar.

Il layout viene invertito quando FlowDirection è RightToLeft.

Creare una barra del titolo

L'app Raccolta WinUI 3 include esempi interattivi di controlli e funzionalità WinUI. Ottenere l'app dal Microsoft Store o esplorare il codice sorgente in GitHub.

In questo esempio viene creata una semplice barra del titolo che sostituisce la barra del titolo di sistema. Ha un titolo, un'icona e un tema 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); 
}

Integrazione con NavigationView

La Visualizzazione di navigazione include un pulsante indietro e un pulsante per alternare il riquadro predefiniti. Le linee guida di Fluent Design consigliano di posizionare questi controlli nella barra del titolo quando viene usata una barra del titolo personalizzata.

In questo esempio viene illustrato come integrare il controllo TitleBar con un controllo NavigationView nascondendo invece il pulsante Indietro e l'interruttore del riquadro nella visualizzazione di spostamento e usando i pulsanti corrispondenti sulla barra del titolo.

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

Personalizzazione delle aree di trascinamento

Gli utenti spostano una finestra trascinando la barra del titolo. Il controllo TitleBar determina le parti dell'area Content che gli utenti possono trascinare e quali parti ricevono l'input del puntatore, ad esempio i clic.

A partire da SDK per app di Windows 2.1.3, il controllo TitleBar esamina gli elementi nel contenuto ed esclude solo i controlli interattivi, ad esempio pulsanti, caselle di testo e caselle combinate, dall'area di trascinamento. Lo spazio vuoto e gli elementi non interattivi, ad esempio textBlock, sono trascinabili per impostazione predefinita, quindi non è necessario modificare il markup. Nelle versioni precedenti, lo spazio vuoto nell'area del contenuto potrebbe bloccare il trascinamento della finestra. Questo comportamento predefinito è dovuto alla modifica della compatibilità del runtime TitleBar_ContentDragRegions. Per altre informazioni, vedi RuntimeCompatibilityOptions.DisabledChanges.

L'esempio seguente si basa sul sample WinUI 3 Gallery. Il contenuto della barra del titolo è un controllo Grid che contiene un controllo AutoSuggestBox e un pulsante. Entrambi i controlli sono cliccabili e lo spazio vuoto accanto a essi è trascinabile.

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

Eseguire l'override del comportamento di trascinamento di un elemento

Per eseguire l'override del comportamento predefinito per un elemento nel contenuto della barra del titolo, impostare la proprietà associata TitleBar.IsDragRegion . La proprietà è un valore booleano nullable.

È possibile impostare la proprietà su un pannello, ad esempio StackPanel:

• Se si imposta su False, l'intera area del pannello è cliccabile, incluso lo spazio tra i relativi elementi figlio.
• Se lo si imposta su True, il pannello e i relativi elementi figlio sono trascinabili, ad eccezione dei figli in cui si imposta la proprietà su False.

Impostare la proprietà sull'elemento più piccolo che lo richiede, in modo da non rendere accidentalmente un'ampia area della barra del titolo trascinabile o cliccabile.

Questo esempio rende un gruppo di controlli di formattazione cliccabili nel loro insieme, in modo che gli utenti non trascinino la finestra quando fanno clic sullo spazio tra i controlli.

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

Nel codice chiamare SetIsDragRegion per impostare il valore e chiamare ClearValue con IsDragRegionProperty per tornare al comportamento predefinito. Per leggere il valore, chiamare GetIsDragRegion. Restituisce null se la proprietà non è impostata. Quando il valore viene modificato, il controllo TitleBar aggiorna le aree di trascinamento.

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

Aggiornare le aree di trascinamento quando il contenuto cambia

Il controllo TitleBar aggiorna le aree di trascinamento quando imposti o sostituisci il relativo contenuto, quando il contenuto viene caricato, quando la barra del titolo cambia dimensione e quando il valore di TitleBar.IsDragRegion cambia in un elemento.

Se si aggiungono, rimuovono o ridimensionano elementi nel contenuto della barra del titolo in fase di esecuzione, chiamare RecomputeDragRegions dopo aver apportato la modifica.

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

Se il contenuto della barra del titolo cambia spesso, è possibile impostare AutoRefreshDragRegions su True . Il controllo TitleBar aggiorna quindi le aree di trascinamento dopo ogni passaggio di layout. Questa opzione può influire sulle prestazioni, quindi è disattivata per impostazione predefinita.

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

Se l'app non usa il controllo TitleBar, usa la classe InputNonClientPointerSource per impostare le aree interattive della barra del titolo personalizzata. Per altre info, vedi Contenuto interattivo.

Articoli correlati

• Barra del titolo (progettazione)
• Personalizzazione della barra del titolo
• Classe TitleBar