Bilah judul

Kontrol TitleBar menyediakan cara yang disederhanakan untuk membuat bilah judul kustom untuk aplikasi Anda. Bilah judul adalah komponen mendasar dari antarmuka pengguna aplikasi Windows yang mengidentifikasi aplikasi melalui ikon dan judulnya, menampung tombol keterangan sistem yang memungkinkan pengguna menutup, memaksimalkan, meminimalkan, dan memulihkan jendela, dan memungkinkan pengguna menyeret jendela di sekitar layar.

Anda dapat menggunakan bilah judul kustom untuk mengintegrasikan area bilah judul dengan UI aplikasi Anda dengan lebih baik. Bilah judul dapat disesuaikan agar sesuai dengan gaya visual aplikasi menggunakan tema Mica. Ini dapat mencakup informasi relevan lainnya, seperti judul dokumen atau status saat ini (misalnya, "Mengedit," "Menampilkan," dll.). Ini juga dapat menghosting kontrol WinUI 3 lainnya, seperti AutoSuggestBox dan PersonPicture, memberikan pengalaman pengguna yang kohesif untuk aplikasi Anda.

Cuplikan layar jendela aplikasi dengan bilah judul kustom

Apakah ini kontrol yang tepat?

Gunakan kontrol TitleBar saat Anda ingin mengintegrasikan area bilah judul dengan UI aplikasi Anda menggunakan kustomisasi seperti subtitel, tema Mica , dan integrasi dengan kontrol WinUI.

Anatomi

Secara default, bilah judul hanya menampilkan tombol keterangan sistem. Bagian lain dari bilah judul ditampilkan atau disembunyikan tergantung pada pengaturan properti terkait.

Bilah judul dibagi menjadi area berikut:

Cuplikan layar memperlihatkan bagian kontrol bilah judul.

Tombol kembali:IsBackButtonEnabled, IsBackButtonVisible, BackRequested - Tombol kembali bawaan untuk navigasi.
Tombol pengalih panel:IsPaneToggleButtonVisible, PaneToggleRequested - Tombol ini dimaksudkan untuk digunakan bersama dengan kontrol NavigationView.
Kepala kiri:LeftHeader
Ikon:IconSource
Judul:Judul
Subjudul:Subjudul
Konten:Konten
Header kanan:RightHeader
Wilayah seret minimal: Area ini dicadangkan di samping tombol bilah judul sistem sehingga pengguna selalu memiliki tempat untuk menggerakkan jendela.
Tombol keterangan sistem: Tombol-tombol ini bukan bagian dari kontrol TitleBar - hanya mengalokasikan ruang di mana tombol keterangan muncul, tergantung pada pengaturan RTL atau LTR. Tombol keterangan dan kustomisasi ditangani oleh AppWindowTitleBar.

Tata letak dibalik ketika FlowDirection adalah RightToLeft.

Membuat bilah judul

API Penting:kelas TitleBar, properti Judul

Buka aplikasi Galeri WinUI 3 dan lihat TitleBar beraksi

Aplikasi Galeri WinUI 3 mencakup contoh interaktif kontrol dan fitur WinUI. Dapatkan aplikasi dari Microsoft Store atau telusuri kode sumber pada GitHub.

Contoh ini membuat bilah judul sederhana yang menggantikan bilah judul sistem. Ini memiliki judul, ikon, dan 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); 
}

Integrasi dengan NavigationView

Tampilan Navigasi memiliki tombol kembali bawaan dan tombol pengalih panel. Panduan Desain Fasih merekomendasikan agar kontrol ini ditempatkan di bilah judul saat bilah judul kustom digunakan.

Contoh ini menunjukkan cara mengintegrasikan kontrol Bilah Judul dengan kontrol NavigationView dengan menyembunyikan tombol kembali dan tombol pengalih panel dalam tampilan navigasi dan menggunakan tombol yang sesuai pada bilah judul sebagai gantinya.

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

Sesuaikan area seret

Pengguna memindahkan jendela dengan menyeret bilah judulnya. Kontrol TitleBar menentukan bagian mana dari area Konten yang dapat diseret pengguna dan bagian mana yang menerima input pointer, seperti klik.

Mulai dari SDK Aplikasi Windows 2.1.3, kontrol Bilah Judul memeriksa elemen dalam kontennya dan hanya mengecualikan kontrol interaktif, seperti tombol, kotak teks, dan kotak kombo, dari wilayah seret. Ruang kosong dan elemen non-interaktif, seperti TextBlock, dapat diseret secara default, sehingga Anda tidak perlu mengubah markup Anda. Di versi sebelumnya, ruang kosong di area konten dapat memblokir penyeretan jendela. Perilaku default ini merupakan perubahan kompatibilitas runtime TitleBar_ContentDragRegions. Untuk informasi selengkapnya, lihat RuntimeCompatibilityOptions.DisabledChanges.

Api Penting:TitleBar.IsDragRegion properti terlampir, properti AutoRefreshDragRegions, metode RecomputeDragRegions

Contoh berikut didasarkan pada sampel Galeri WinUI 3. Konten bilah judul adalah Grid yang berisi AutoSuggestBox dan Button. Kedua kontrol dapat diklik, dan ruang kosong di sampingnya dapat diseret.

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

Mengesampingkan perilaku seret elemen

Untuk mengambil alih perilaku default untuk elemen di konten bilah judul, atur properti terlampir TitleBar.IsDragRegion . Properti adalah nilai Boolean yang dapat bernilai null.

Nilai	Behavior
Tidak diatur (`null`)	Kontrol TitleBar yang menentukan. Kontrol interaktif dapat diklik, dan elemen lain dapat diseret.
`True`	Elemen ini dapat diseret, bahkan jika itu adalah kontrol interaktif. Input penunjuk pada elemen memindahkan jendela, sehingga pengguna tidak dapat mengklik elemen .
`False`	Elemen ini dapat diklik, meskipun bukan kontrol interaktif.

Anda dapat mengatur properti pada panel, seperti StackPanel:

Jika Anda mengaturnya ke False, seluruh area panel dapat diklik, termasuk ruang di antara elemen anaknya.
Jika Anda mengaturnya ke True, panel dan anak-anaknya dapat diseret, kecuali untuk anak-anak tempat Anda mengatur properti ke False.

Atur properti pada elemen terkecil yang membutuhkannya, sehingga Anda tidak membuat area besar bilah judul dapat diseret atau diklik secara tidak sengaja.

Contoh ini membuat sekelompok kontrol pemformatan dapat diklik secara keseluruhan, sehingga pengguna tidak menyeret jendela saat mereka mengklik area kosong di antara kontrol.

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

Dalam kode, panggil SetIsDragRegion untuk mengatur nilai, dan panggil ClearValue dengan IsDragRegionProperty untuk kembali ke perilaku default. Untuk membaca nilainya, panggil GetIsDragRegion. Ini mengembalikan null jika properti tidak diatur. Saat nilai berubah, kontrol Bilah Judul memperbarui wilayah seretnya.

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

Memperbarui wilayah seret saat konten berubah

Kontrol Bilah Judul memperbarui wilayah seretnya saat Anda mengatur atau mengganti kontennya, saat konten dimuat, saat bilah judul berubah ukuran, dan saat nilai TitleBar.IsDragRegion berubah pada elemen.

Jika Anda menambahkan, menghapus, atau mengubah ukuran elemen di konten bilah judul pada waktu proses, panggil RecomputeDragRegions setelah Anda membuat perubahan.

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

Jika konten bilah judul sering berubah, Anda dapat mengatur AutoRefreshDragRegions ke True sebagai gantinya. Kontrol TitleBar kemudian memperbarui wilayah seretnya setelah setiap proses tata letak. Opsi ini dapat memengaruhi performa, sehingga False dinonaktifkan secara default.

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

Note

Area seret hanya memengaruhi input penunjuk. Mereka tidak mengubah fokus keyboard atau bagaimana klien UI Automation, seperti pembaca layar, berinteraksi dengan elemen di bilah judul. Pastikan kontrol interaktif di bilah judul Anda masih dapat dijangkau dengan keyboard.

Jika aplikasi Anda tidak menggunakan kontrol TitleBar, gunakan kelas InputNonClientPointerSource untuk mengatur wilayah interaktif bilah judul kustom Anda. Untuk informasi selengkapnya, lihat Konten interaktif.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-15