제목 표시줄

TitleBar 컨트롤은 앱에 대한 사용자 지정 제목 표시줄을 만드는 간소화된 방법을 제공합니다. 제목 표시줄은 아이콘과 제목을 통해 앱을 식별하는 Windows 앱의 사용자 인터페이스의 기본 구성 요소이며, 사용자가 창을 닫고, 최대화하고, 최소화하고, 복원할 수 있도록 하는 시스템 캡션 단추를 포함하며, 사용자가 화면을 중심으로 창을 끌 수 있도록 합니다.

사용자 지정 제목 표시줄을 사용하여 제목 표시줄 영역을 앱 UI와 더 잘 통합할 수 있습니다. 제목 표시줄은 Mica 테마를 사용하여 앱의 비주얼 스타일과 일치하도록 사용자 지정할 수 있습니다. 문서 제목 또는 현재 상태(예: "편집 중", "보기" 등)와 같은 기타 관련 정보를 포함할 수 있습니다. AutoSuggestBox 및 PersonPicture와 같은 다른 WinUI 3 컨트롤을 호스트하여 앱에 대한 응집력 있는 사용자 환경을 제공할 수도 있습니다.

사용자 지정 제목 표시줄이 있는 앱 창의 스크린샷

이것이 올바른 컨트롤인가요?

제목, Mica 테마 지정 및 WinUI 컨트롤과의 통합과 같은 사용자 지정을 사용하여 제목 표시줄 영역을 앱 UI와 통합하려는 경우 TitleBar 컨트롤을 사용합니다.

해부학

기본적으로 제목 표시줄에는 시스템 캡션 단추만 표시됩니다. 제목 표시줄의 다른 부분은 연결된 속성 설정에 따라 표시되거나 숨겨집니다.

제목 표시줄은 다음 영역으로 나뉩니다.

제목 표시줄 컨트롤의 부분을 보여 주는 스크린샷

뒤로 단추:IsBackButtonEnabled, IsBackButtonVisible, BackRequested - 기본 제공된 탐색용 뒤로 단추입니다.
창 토글 단추:IsPaneToggleButtonVisible, PaneToggleRequested - 이 단추는 NavigationView 컨트롤과 함께 사용됩니다.
왼쪽 헤더:LeftHeader
아이콘:IconSource
제목:제목
부제:부제
콘텐츠:콘텐츠
오른쪽 헤더:RightHeader
최소 끌기 영역: 이 영역은 시스템 캡션 단추 옆에 예약되어 있으므로 사용자는 항상 창을 끌어다 놓을 수 있습니다.
시스템 캡션 단추: 이러한 단추는 TitleBar 컨트롤의 일부가 아닙니다. RTL 또는 LTR 설정에 따라 캡션 단추가 표시되는 공간을 할당하기만 하면 됩니다. 캡션 단추 및 사용자 지정은 AppWindowTitleBar에서 처리됩니다.

FlowDirection이 RightToLeft인 경우 레이아웃이 반전됩니다.

제목 표시줄 만들기

중요 API:TitleBar 클래스, Title 속성

WinUI 3 갤러리 앱을 열고 작업 중인 TitleBar를 확인합니다.

WinUI 3 갤러리 앱에는 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 앱 SDK 2.1.3부터 TitleBar 컨트롤은 콘텐츠의 요소를 검사하고 끌기 영역에서 단추, 텍스트 상자 및 콤보 상자와 같은 대화형 컨트롤만 제외합니다. 빈 공간 및 TextBlock과 같은 비대화형 요소는 기본적으로 드래그할 수 있으므로 태그를 변경할 필요가 없습니다. 이전 버전에서는 콘텐츠 영역의 빈 공간이 창 끌기를 차단할 수 있었습니다. 이 기본 동작은 TitleBar_ContentDragRegions 런타임 호환성 변경입니다. 자세한 내용은 RuntimeCompatibilityOptions.DisabledChanges를 참조하세요.

중요 API:TitleBar.IsDragRegion 연결된 속성, AutoRefreshDragRegions 속성, RecomputeDragRegions 메서드

다음 예제는 WinUI 3 갤러리 샘플을 기반으로 합니다. 제목 표시줄 콘텐츠는 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 허용 Boolean 값입니다.

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를 호출하여 기본 동작으로 돌아갑니다. 값을 읽으려면 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

끌기 영역은 포인터 입력에만 영향을 줍니다. 이들은 키보드 포커스나 화면 읽기 프로그램과 같은 UI 자동화 클라이언트가 제목 표시줄의 요소와 상호 작용하는 방식을 변경하지 않습니다. 키보드를 사용하여 제목 표시줄의 대화형 컨트롤에 계속 접근할 수 있는지 확인합니다.

앱에서 TitleBar 컨트롤을 사용하지 않는 경우 InputNonClientPointerSource 클래스를 사용하여 사용자 지정 제목 표시줄의 대화형 영역을 설정합니다. 자세한 내용은 대화형 콘텐츠를 참조하세요.

피드백

이 페이지가 도움이 되었나요?

2026-10-15 에 마지막으로 업데이트됨