Barra de título

El control TitleBar proporciona una manera simplificada de crear una barra de título personalizada para la aplicación. La barra de título es un componente fundamental de la interfaz de usuario de una aplicación de Windows que identifica la aplicación a través de su icono y título, aloja los botones de título del sistema que permiten al usuario cerrar, maximizar, minimizar y restaurar la ventana, y permite que un usuario arrastre la ventana alrededor de la pantalla.

Puedes usar una barra de título personalizada para integrar mejor el área de la barra de título con la interfaz de usuario de la aplicación. La barra de título se puede personalizar para que coincida con el estilo visual de la aplicación mediante el tema de Mica. Puede incluir otra información relevante, como un título de documento o el estado actual (por ejemplo, "Edición", "Visualización", etc.). También puede hospedar otros controles winUI 3, como AutoSuggestBox y PersonPicture, lo que proporciona una experiencia de usuario coherente para la aplicación.

Captura de pantalla de una ventana de aplicación con una barra de título personalizada

¿Es este el control adecuado?

Usa el control TitleBar cuando quieras integrar el área de la barra de título con la interfaz de usuario de la aplicación mediante personalizaciones como subtítulos, creación de tema de Mica e integraciones con controles WinUI.

Anatomía

De forma predeterminada, la barra de título solo muestra los botones de título del sistema. Otras partes de la barra de título se muestran u ocultas en función de la configuración de propiedades asociadas.

La barra de título se divide en estas áreas:

Captura de pantalla que muestra las partes de un control de barra de título.

Botón Atrás:IsBackButtonEnabled, IsBackButtonVisible, BackRequested : botón atrás integrado para la navegación.
Botón de conmutación de panel:IsPaneToggleButtonVisible, PaneToggleRequested - Este botón está diseñado para usarse junto con el control NavigationView.
Encabezado izquierdo:LeftHeader
Icon:IconSource
Title:Título
Subtítulo:Subtítulo
Contenido:Contenido
Encabezado derecho:RightHeader
Región de arrastre mínima: Este área está reservada junto a los botones de título del sistema para que el usuario siempre tenga un lugar para agarrar la ventana para arrastrar.
Botones de título del sistema: Estos botones no forman parte del control TitleBar: simplemente asigna espacio donde aparecen los botones de título, en función de la configuración rtL o LTR. Los botones de título y las personalizaciones se controlan mediante AppWindowTitleBar.

El diseño se invierte cuando FlowDirection es RightToLeft.

Crear una barra de título

APIs importantes:Clase TitleBar, propiedad Título

Abra la aplicación Galería de WinUI 3 y vea titleBar en acción.

La aplicación Galería de WinUI 3 incluye ejemplos interactivos de características y controles winUI. Obtenga la aplicación del Microsoft Store o examine el código fuente en GitHub.

En este ejemplo se crea una barra de título simple que reemplaza la barra de título del sistema. Tiene un título, un icono y un tema de 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); 
}

Integración con NavigationView

La vista Navegación tiene un botón atrás integrado y un botón de alternancia de panel. La guía de Fluent Design recomienda que estos controles se coloquen en la barra de título cuando se usa una barra de título personalizada.

En este ejemplo se muestra cómo integrar el control TitleBar con un control NavigationView ocultando el botón atrás y el botón de alternancia de panel en la vista de navegación y usando los botones correspondientes en la barra de título en su lugar.

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

Personalizar regiones de arrastre

Los usuarios mueven una ventana arrastrando su barra de título. El control TitleBar determina qué partes de su área Content los usuarios pueden arrastrar y qué partes reciben entrada de puntero, como clics.

A partir de SDK de Aplicaciones para Windows 2.1.3, el control TitleBar examina los elementos de su contenido y excluye solo los controles interactivos, como botones, cuadros de texto y cuadros combinados, de la región de arrastre. El espacio vacío y los elementos no interactivos, como TextBlock, se pueden arrastrar de forma predeterminada, por lo que no es necesario cambiar el marcado. En versiones anteriores, el espacio vacío en el área de contenido podría bloquear el arrastre de la ventana. Este comportamiento predeterminado es el cambio de compatibilidad en tiempo de ejecución TitleBar_ContentDragRegions. Para obtener más información, consulta RuntimeCompatibilityOptions.DisabledChanges.

API importantes:TitleBar.IsDragRegion propiedad adjunta, propiedad AutoRefreshDragRegions, método RecomputeDragRegions

El ejemplo siguiente se basa en el ejemplo de la galería de WinUI 3. El contenido de la barra de título es un Grid que contiene un AutoSuggestBox y un botón. Ambos controles se pueden pulsar y el espacio vacío junto a ellos es arrastrable.

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

Anular el comportamiento de arrastre de un elemento

Para anular el comportamiento predeterminado de un elemento en el contenido de la barra de título, establezca la propiedad adjunta TitleBar.IsDragRegion. La propiedad es un valor Boolean anulable.

Valor	Behavior
No establecido (`null`)	El control TitleBar decide. Se puede hacer clic en los controles interactivos y arrastrar otros elementos.
`True`	El elemento se puede arrastrar, aunque sea un control interactivo. La entrada de puntero en el elemento mueve la ventana, por lo que los usuarios no pueden hacer clic en el elemento.
`False`	El elemento se puede pulsar, incluso si no es un control interactivo.

Puede establecer la propiedad en un panel, como StackPanel:

Si lo establece en False, se puede hacer clic en todo el área del panel, incluido el espacio entre sus elementos secundarios.
Si lo establece en True, el panel y sus elementos secundarios se pueden arrastrar, excepto los elementos secundarios en los que establezca la propiedad en False.

Establezca la propiedad en el elemento más pequeño que lo necesite, de modo que no haga que un área grande de la barra de título se pueda arrastrar o hacer clic por accidente.

En este ejemplo, se puede hacer clic en un grupo de controles de formato como un todo, de modo que los usuarios no arrastren la ventana cuando presionan el espacio entre los controles.

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

En el código, llame a SetIsDragRegion para establecer el valor y llame a ClearValue con IsDragRegionProperty para volver al comportamiento predeterminado. Para leer el valor, llame a GetIsDragRegion. Devuelve null si la propiedad no está establecida. Cuando cambia el valor, el control TitleBar actualiza sus regiones de arrastre.

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

Actualiza las regiones de arrastre cuando cambie el contenido

El control TitleBar actualiza sus regiones de arrastre al establecer o reemplazar su contenido, cuando se carga el contenido, cuando cambia el tamaño de la barra de título y cuando cambia el valor de TitleBar.IsDragRegion en un elemento.

Si agrega, quita o cambia el tamaño de los elementos en el contenido de la barra de título en tiempo de ejecución, llame a RecomputeDragRegions después de realizar el cambio.

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 el contenido de la barra de título cambia a menudo, puede establecer AutoRefreshDragRegions a True en su lugar. A continuación, el control TitleBar actualiza sus regiones de arrastre después de cada paso de diseño. Esta opción puede afectar al rendimiento, por lo que está desactivada False de forma predeterminada.

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

Note

Las regiones de arrastre solo afectan a la entrada del puntero. No cambian el foco del teclado ni cómo los clientes de Automatización de la interfaz de usuario, como lectores de pantalla, interactúan con los elementos de la barra de título. Asegúrese de que se pueda seguir accediendo con el teclado a los controles interactivos de la barra de título.

Si la aplicación no usa el control TitleBar, use la clase InputNonClientPointerSource para establecer las regiones interactivas de la barra de título personalizada. Para obtener más información, consulta Contenido interactivo.

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-10-15