Строка заголовка

Элемент управления TitleBar предоставляет упрощенный способ создания настраиваемой строки заголовка для приложения. Строка заголовка является основным компонентом пользовательского интерфейса приложения Windows, который определяет приложение с помощью значка и заголовка, содержит кнопки заголовка системы, позволяющие пользователю закрыть, развернуть, свернуть и восстановить окно, а также позволит пользователю перетаскивать окно по экрану.

Вы можете использовать настраиваемую строку заголовка, чтобы лучше интегрировать область заголовка с пользовательским интерфейсом приложения. Строку заголовка можно настроить, чтобы она соответствовала визуальному стилю приложения, используя тематику Mica. Она может включать другие важные сведения, такие как название документа или текущее состояние (например, "Редактирование", "Просмотр", и т. д.). Он также может размещать другие элементы управления WinUI 3, такие как AutoSuggestBox и PersonPicture, обеспечивая единый пользовательский интерфейс для вашего приложения.

Снимок экрана: окно приложения с настраиваемой строкой заголовка

Это правильный контроль?

Используйте элемент управления TitleBar, если вы хотите интегрировать область заголовка с пользовательским интерфейсом приложения с помощью настроек, таких как субтитры, тематические элементы Mica и интеграции с элементами управления WinUI.

Анатомия

По умолчанию в панели заголовка отображаются только кнопки управления системой. Другие части строки заголовка отображаются или скрыты в зависимости от параметров связанного свойства.

Строка заголовка разделена на следующие области:

Снимок экрана, показывающий части элемента управления строкой заголовка.

Кнопка назад:IsBackButtonEnabled, IsBackButtonVisible, BackRequested — встроенная кнопка назад для навигации.
Кнопка переключения области:IsPaneToggleButtonVisible и PaneToggleRequested предназначена для использования в сочетании с элементом управления NavigationView.
Левый заголовок:LeftHeader
Значок:IconSource
Заголовок:Заголовок
Субтитры:Субтитры
Содержание:Содержание
Правый заголовок:RightHeader
Минимальная область перетаскивания: Эта область зарезервирована рядом с системными кнопками заголовка, чтобы пользователь всегда мог захватить окно для его перемещения.
Кнопки заголовка системы: Эти кнопки не являются частью элемента управления TitleBar. Он просто выделяет пространство, в котором отображаются кнопки заголовка в зависимости от параметров RTL или LTR. Кнопки заголовка и настройки обрабатываются AppWindowTitleBar.

Макет изменяется, когда FlowDirection имеет значение RightToLeft.

Создание строки заголовка

Важные API:класс TitleBar, свойство Title

Откройте приложение коллекции WinUI 3 и просмотрите строку TitleBar в действии

Приложение WinUI 3 Gallery содержит интерактивные примеры элементов управления и функций WinUI. Получите приложение из Microsoft Store или просмотрите исходный код GitHub.

В этом примере создается простая строка заголовка, которая заменяет строку заголовка системы. Он имеет заголовок, значок и тематику 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); 
}

Интеграция с NavigationView

В представлении навигации есть встроенная кнопка "Назад" и кнопка переключателя области. Руководство по проектированию Fluent рекомендует поместить эти элементы управления в строку заголовка при использовании настраиваемой строки заголовка.

В этом примере показано, как интегрировать элемент управления TitleBar с элементом управления NavigationView, скрывая кнопку "Назад" и кнопку переключателя области в представлении навигации и используя соответствующие кнопки в строке заголовка.

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

Настроить области перетаскивания

Пользователи перемещают окно, перетаскивая его заголовок. Элемент управления TitleBar определяет, какие части области контента пользователи могут перетаскивать, а какие части обрабатывают события указателя, такие как щелчки.

Начиная с Windows App SDK 2.1.3 элемент управления TitleBar проверяет элементы в его содержимом и исключает только интерактивные элементы управления, такие как кнопки, текстовые поля и поля со списком из области перетаскивания. Пустое пространство и неинтерактивные элементы, такие как TextBlock, перетаскиваются по умолчанию, поэтому вам не нужно изменять разметку. В более ранних версиях пустое пространство в области содержимого могло блокировать перетаскивание окна. Это поведение по умолчанию — это TitleBar_ContentDragRegions изменение совместимости среды выполнения. Дополнительные сведения см. в разделе RuntimeCompatibilityOptions.DisabledChanges.

Важные API:присоединенное свойство TitleBar.IsDragRegion, свойство AutoRefreshDragRegions, метод RecomputeDragRegions

Следующий пример основан на примере Gallery для WinUI 3. Содержимое строки заголовка — это Grid, содержащий AutoSuggestBox и кнопку. Оба элемента управления доступны для щелчка, а пустое пространство рядом с ними можно перетаскивать.

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

Переопределите поведение перетаскивания элемента

Чтобы переопределить поведение по умолчанию для элемента в содержимом строки заголовка, задайте присоединенное свойство TitleBar.IsDragRegion . Свойство — это логическое значение, допускающее значение NULL.

Value	Behavior
Не задано (`null`)	Элемент управления TitleBar определяет. Интерактивные элементы управления доступны для щелчка, а другие элементы можно перетаскивать.
`True`	Элемент перетаскивается, даже если это интерактивный элемент управления. Ввод указателем на элементе перемещает окно, поэтому пользователи не могут щелкнуть элемент.
`False`	Элемент доступен для щелчка, даже если он не является интерактивным элементом управления.

Свойство можно задать на панели, например StackPanel:

Если задать для нее значение False, вся область панели становится кликабельной, включая пространство между ее дочерними элементами.
Если задано значение True, панель и ее дочерние элементы можно перетаскивать, за исключением дочерних элементов, в которых задано значение свойства False.

Задайте свойство на самом маленьком элементе, которому оно требуется, чтобы случайно не сделать большую область строки заголовка перетаскиваемой или кликабельной.

В этом примере группа элементов управления форматированием сделана кликабельной целиком, чтобы пользователи не перетаскивали окно при нажатии на область между элементами управления.

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

В коде вызовите SetIsDragRegion, чтобы задать значение, и вызовите ClearValue с IsDragRegionProperty, чтобы вернуться к поведению по умолчанию. Чтобы прочитать значение, вызовите GetIsDragRegion. Возвращается null , если свойство не задано. При изменении значения элемент управления TitleBar обновляет области перетаскивания.

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

Обновить регионы перетаскивания при изменении содержимого

Элемент управления TitleBar обновляет области перетаскивания при установке или замене его содержимого, когда содержимое загружается, когда строка заголовка изменяет размер и когда у элемента изменяется значение TitleBar.IsDragRegion.

При добавлении, удалении или изменении размера элементов в содержимом заголовка во время выполнения вызовите RecomputeDragRegions после внесения изменений.

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

Если содержимое строки заголовка часто изменяется, вместо этого можно установить для AutoRefreshDragRegions значение True. Затем элемент управления TitleBar обновляет области перетаскивания после каждого прохода макета. Этот параметр может повлиять на производительность, поэтому он False отключен по умолчанию.

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

Note

Области перетаскивания влияют только на ввод указателем. Они не изменяют ни фокус клавиатуры, ни то, как клиенты модель автоматизации пользовательского интерфейса, такие как средства чтения с экрана, взаимодействуют с элементами в строке заголовка. Убедитесь, что интерактивные элементы управления в строке заголовка по-прежнему доступны с помощью клавиатуры.

Если приложение не использует элемент управления TitleBar, используйте класс InputNonClientPointerSource , чтобы задать интерактивные области настраиваемой строки заголовка. Дополнительные сведения см. в разделе "Интерактивное содержимое".

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-15