Bilah perintah

Bilah perintah memberi pengguna akses mudah ke tugas aplikasi Anda yang paling umum. Bilah perintah dapat menyediakan akses ke perintah tingkat aplikasi atau khusus halaman dan dapat digunakan dengan pola navigasi apa pun.

Apakah ini kontrol yang tepat?

Kontrol CommandBar adalah kontrol tujuan umum, fleksibel, dan ringan yang dapat menampilkan konten kompleks, seperti gambar atau blok teks, serta perintah sederhana seperti kontrol AppBarButton, AppBarToggleButton, dan AppBarSeparator .

Catatan

XAML menyediakan kontrol AppBar dan kontrol CommandBar . Anda harus menggunakan AppBar hanya saat memutakhirkan aplikasi Universal Windows 8 yang menggunakan AppBar, dan perlu meminimalkan perubahan. Untuk aplikasi baru di Windows 10, sebaiknya gunakan kontrol CommandBar sebagai gantinya. Dokumen ini mengasumsikan Anda menggunakan kontrol CommandBar.

anatomi

Secara default, bilah perintah memperlihatkan baris tombol ikon dan tombol "lihat selengkapnya" opsional, yang diwakili oleh elipsis [...]. Berikut adalah bilah perintah yang dibuat oleh kode contoh yang ditampilkan nanti. Ini ditunjukkan dalam keadaan ringkas tertutup.

Bilah perintah juga dapat ditampilkan dalam status minimal tertutup yang terlihat seperti ini. Lihat bagian Status terbuka dan tertutup untuk informasi selengkapnya.

Berikut adalah bilah perintah yang sama dalam status terbukanya. Label mengidentifikasi bagian utama kontrol.

Bilah perintah dibagi menjadi 4 area utama:

• Area konten diratakan ke sisi kiri bilah. Ini ditampilkan jika properti Konten diisi.
• Area perintah utama diselaraskan ke sisi kanan bilah. Ini ditampilkan jika properti PrimaryCommands diisi.
• Tombol "lihat lebih banyak" [...] ditampilkan di sebelah kanan bilah. Menekan tombol "lihat lebih banyak" [...] mengungkapkan label perintah utama dan membuka menu luapan jika ada perintah sekunder. Tombol tidak akan terlihat ketika tidak ada label perintah utama atau label sekunder yang ada. Untuk mengubah perilaku default, gunakan properti OverflowButtonVisibility .
• Menu luapan ditampilkan hanya ketika bilah perintah terbuka dan properti SecondaryCommands diisi. Ketika ruang terbatas, perintah utama akan berpindah ke area SecondaryCommands. Untuk mengubah perilaku default, gunakan properti IsDynamicOverflowEnabled .

Tata letak dibalik ketika FlowDirection adalah RightToLeft.

Penempatan

Bilah perintah dapat ditempatkan di bagian atas jendela aplikasi, di bagian bawah jendela aplikasi, dan sebaris, dengan menyematkannya dalam kontrol tata letak seperti Grid.row.

• Untuk perangkat genggam kecil, sebaiknya posisikan bilah perintah di bagian bawah layar agar mudah dijangkau.
• Untuk perangkat dengan layar yang lebih besar, menempatkan bilah perintah di dekat bagian atas jendela membuatnya lebih terlihat dan dapat ditemukan.

Gunakan API DiagonalSizeInches untuk menentukan ukuran layar fisik.

Bilah perintah dapat ditempatkan di wilayah layar berikut pada layar tampilan tunggal (contoh kiri) dan pada layar multi-tampilan (contoh kanan). Bilah perintah sebaris dapat ditempatkan di mana saja di ruang tindakan.

Perangkat sentuh: Jika bilah perintah harus tetap terlihat oleh pengguna saat papan ketik sentuh, atau Panel Input Lunak (SIP), muncul maka Anda dapat menetapkan bilah perintah ke properti BottomAppBar halaman dan akan bergerak untuk tetap terlihat ketika SIP ada. Jika tidak, Anda harus menempatkan bilah perintah sebaris dan diposisikan relatif terhadap konten aplikasi Anda.

UWP dan WinUI 2

Penting

Informasi dan contoh dalam artikel ini dioptimalkan untuk aplikasi yang menggunakan SDK Aplikasi Windows dan WinUI 3, tetapi umumnya berlaku untuk aplikasi UWP yang menggunakan WinUI 2. Lihat referensi API UWP untuk informasi dan contoh spesifik platform.

Bagian ini berisi informasi yang Anda butuhkan untuk menggunakan kontrol di aplikasi UWP atau WinUI 2.

API untuk kontrol ini ada di namespace Windows.UI.Xaml.Controls .

• API UWP: kelas CommandBar, kelas AppBarButton, kelas AppBarToggleButton, kelas AppBarSeparator
• Buka aplikasi Galeri WinUI 2 dan lihat CommandBar beraksi. Aplikasi Galeri WinUI 2 mencakup contoh interaktif dari sebagian besar kontrol, fitur, dan fungsi WinUI 2. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub.

Sebaiknya gunakan WinUI 2 terbaru untuk mendapatkan gaya dan templat terbaru untuk semua kontrol. WinUI 2.2 atau yang lebih baru menyertakan templat baru untuk kontrol ini yang menggunakan sudut bulat. Untuk informasi selengkapnya, lihat radius sudut.

Gaya otomatis SplitButton di CommandBar mengharuskan Anda menggunakan kontrol SplitButton dari WinUI 2.6 atau yang lebih baru.

Membuat bilah perintah

• API Penting: Kelas CommandBar, kelas AppBarButton, kelas AppBarToggleButton, kelas AppBarSeparator

Buka aplikasi Galeri WinUI 3 dan lihat CommandBar beraksi.

Aplikasi Galeri WinUI 3 mencakup contoh interaktif dari sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub

Contoh ini membuat bilah perintah yang diperlihatkan sebelumnya.

<CommandBar>
    <AppBarToggleButton Icon="Shuffle" Label="Shuffle" Click="AppBarButton_Click" />
    <AppBarToggleButton Icon="RepeatAll" Label="Repeat" Click="AppBarButton_Click"/>
    <AppBarSeparator/>
    <AppBarButton Icon="Back" Label="Back" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Stop" Label="Stop" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Play" Label="Play" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Forward" Label="Forward" Click="AppBarButton_Click"/>

    <CommandBar.SecondaryCommands>
        <AppBarButton Label="Like" Click="AppBarButton_Click"/>
        <AppBarButton Label="Dislike" Click="AppBarButton_Click"/>
    </CommandBar.SecondaryCommands>

    <CommandBar.Content>
        <TextBlock Text="Now playing..." Margin="12,14"/>
    </CommandBar.Content>
</CommandBar>

Perintah dan konten

Kontrol CommandBar memiliki 3 properti yang dapat Anda gunakan untuk menambahkan perintah dan konten: PrimaryCommands, SecondaryCommands, dan Content.

Perintah

Secara default, item bilah perintah ditambahkan ke koleksi PrimaryCommands . Anda harus menambahkan perintah dalam urutan kepentingannya sehingga perintah yang paling penting selalu terlihat. Saat lebar bilah perintah berubah, seperti saat pengguna mengubah ukuran jendela aplikasi mereka, perintah utama secara dinamis berpindah antara bilah perintah dan menu luapan pada titik henti. Untuk mengubah perilaku default ini, gunakan properti IsDynamicOverflowEnabled .

Pada layar terkecil (lebar 320 epx), maksimum 4 perintah utama pas di bilah perintah.

Anda juga dapat menambahkan perintah ke koleksi SecondaryCommands , yang ditampilkan di menu luapan.

Anda dapat secara terprogram memindahkan perintah antara PrimaryCommands dan SecondaryCommands sesuai kebutuhan.

• Jika ada perintah yang akan muncul secara konsisten di seluruh halaman, sebaiknya pertahankan perintah tersebut di lokasi yang konsisten.
• Sebaiknya tempatkan perintah Terima, Ya, dan OK di sebelah kiri Tolak, Tidak, dan Batal. Konsistensi memberi pengguna kepercayaan diri untuk bergerak di sekitar sistem dan membantu mereka mentransfer pengetahuan mereka tentang navigasi aplikasi dari aplikasi ke aplikasi.

Tombol bilah aplikasi

PrimaryCommands dan SecondaryCommands hanya dapat diisi dengan jenis yang mengimplementasikan antarmuka ICommandBarElement , yang mencakup elemen perintah AppBarButton, AppBarToggleButton, dan AppBarSeparator .

Jika Anda ingin menyertakan jenis elemen yang berbeda dalam PrimaryCommands atau SecondaryCommands, Anda dapat menggunakan kelas AppBarElementContainer . Ini akan berfungsi sebagai pembungkus untuk elemen Anda dan akan memungkinkan elemen untuk ditampilkan di CommandBar.

Kontrol tombol bilah aplikasi ditandai oleh ikon dan label teks. Kontrol ini dioptimalkan untuk digunakan di bilah perintah, dan tampilannya berubah tergantung pada apakah kontrol digunakan di bilah perintah atau menu luapan.

Ikon

Ukuran ikon saat ditampilkan di area perintah utama adalah 20x20px; di menu luapan, ikon ditampilkan pada 16x16px. Jika Anda menggunakan SymbolIcon, FontIcon, atau PathIcon, ikon akan secara otomatis menskalakan ke ukuran yang benar tanpa kehilangan keakuratan saat perintah memasuki area perintah sekunder.

Untuk informasi selengkapnya dan contoh pengaturan ikon, lihat dokumentasi untuk kelas AppBarButton .

Label

Properti AppBarButton IsCompact menentukan apakah label ditampilkan. Dalam kontrol CommandBar, bilah perintah menimpa properti IsCompact tombol secara otomatis saat bilah perintah dibuka dan ditutup.

Untuk memosisikan label tombol bilah aplikasi, gunakan properti DefaultLabelPosition CommandBar.

<CommandBar DefaultLabelPosition="Right">
    <AppBarToggleButton Icon="Edit" Label="Edit"/>
    <AppBarToggleButton Icon="Share" Label="Share"/>
</CommandBar>

Pada jendela yang lebih besar, pertimbangkan untuk memindahkan label ke kanan ikon tombol bilah aplikasi untuk meningkatkan legibilitas. Label di bagian bawah mengharuskan pengguna membuka bilah perintah untuk mengungkapkan label, sementara label di sebelah kanan terlihat bahkan ketika bilah perintah ditutup.

Di menu luapan, label diposisikan di sebelah kanan ikon secara default, dan LabelPosition diabaikan. Anda dapat menyesuaikan gaya dengan mengatur properti CommandBarOverflowPresenterStyle ke Gaya yang menargetkan CommandBarOverflowPresenter.

Label tombol harus pendek, sebaiknya satu kata. Label yang lebih panjang di bawah ikon akan membungkus ke beberapa baris, meningkatkan tinggi keseluruhan bilah perintah yang dibuka. Anda dapat menyertakan karakter tanda hubung lunak (0x00AD) dalam teks agar label mengisyaratkan batas karakter tempat pemisah kata harus terjadi. Di XAML, Anda mengekspresikan ini menggunakan urutan escape, seperti ini:

<AppBarButton Icon="Back" Label="Areally&#x00AD;longlabel"/>

Ketika label membungkus di lokasi yang diisyaratkan, label terlihat seperti ini.

SplitButton

Anda dapat menampilkan SplitButton di CommandBar menggunakan kelas bawaan SplitButtonCommandBarStyle dan AppBarElementContainer . SplitButtonCommandBarStyle menyediakan visual bagi SplitButton agar terlihat dan terasa seperti AppBarButton, sementara AppBarElementContainer merupakan kelas pembungkus yang menyediakan fungsionalitas yang perlu ditindak seperti AppBarButton.

Saat Anda membungkus SplitButton di AppBarElementContainer dan menempatkannya di CommandBar, SplitButtonCommandBarStyle sumber daya diterapkan secara otomatis.

Kode sampel ini membuat dan menampilkan SplitButton di dalam CommandBar:

<CommandBar>
    <AppBarButton Icon="Copy" ToolTipService.ToolTip="Copy" Label="Copy"/>
    <AppBarElementContainer>
        <muxc:SplitButton ToolTipService.ToolTip="Insert" Content="Insert">
            <muxc:SplitButton.Flyout>
                <MenuFlyout Placement="RightEdgeAlignedTop">
                    <MenuFlyoutItem Text="Insert above"/>
                    <MenuFlyoutItem Text="Insert between"/>
                    <MenuFlyoutItem  Text="Insert below"/>
                </MenuFlyout>
            </muxc:SplitButton.Flyout>
        </muxc:SplitButton>
    </AppBarElementContainer>
    <AppBarButton Label="Select all"/>
    <AppBarButton Label="Delete" Icon="Delete"/>
</CommandBar>

Menu dan flyout

Pertimbangkan pengelompokan logis untuk perintah, seperti menempatkan Balas, Balas Semua, dan Teruskan di menu Respons. Meskipun biasanya tombol bilah aplikasi mengaktifkan satu perintah, tombol bilah aplikasi dapat digunakan untuk menampilkan MenuFlyout atau Flyout dengan konten kustom.

Konten lainnya

Anda dapat menambahkan elemen XAML apa pun ke area konten dengan mengatur properti Konten . Jika Anda ingin menambahkan lebih dari satu elemen, Anda perlu menempatkannya dalam kontainer panel dan menjadikan panel sebagai anak tunggal dari properti Konten.

Ketika luapan dinamis diaktifkan, konten tidak akan diklip karena perintah utama dapat berpindah ke menu luapan. Jika tidak, perintah utama diutamakan dan dapat menyebabkan konten diklip.

Ketika ClosedDisplayMode Ringkas, konten dapat diklip jika lebih besar dari ukuran padat bilah perintah. Anda harus menangani acara Buka dan Tutup untuk menampilkan atau menyembunyikan bagian UI di area konten sehingga tidak diklip. Lihat bagian Status terbuka dan tertutup untuk informasi selengkapnya.

Status terbuka dan tertutup

Bilah perintah dapat terbuka atau tertutup. Saat terbuka, ini menunjukkan tombol perintah utama dengan label teks dan membuka menu luapan (jika ada perintah sekunder). Bilah perintah membuka menu luapan ke atas (di atas perintah utama) atau ke bawah (di bawah perintah utama). Arah default naik, tetapi jika tidak ada cukup ruang untuk membuka menu luapan ke atas, bilah perintah akan membukanya ke bawah.

Pengguna dapat beralih di antara status ini dengan menekan tombol "lihat lebih banyak" [...]. Anda dapat beralih di antara keduanya secara terprogram dengan mengatur properti IsOpen .

Anda dapat menggunakan acara Buka, Dibuka, Tutup, dan Ditutup untuk merespons bilah perintah yang sedang dibuka atau ditutup.

• Peristiwa Pembukaan dan Penutupan terjadi sebelum animasi transisi dimulai.
• Peristiwa Dibuka dan Ditutup terjadi setelah transisi selesai.

Dalam contoh ini, peristiwa Pembukaan dan Penutupan digunakan untuk mengubah keburaman bilah perintah. Saat bilah perintah ditutup, bilah tersebut semi transparan sehingga latar belakang aplikasi ditampilkan. Ketika bilah perintah dibuka, bilah perintah dibuat buram sehingga pengguna dapat fokus pada perintah.

<CommandBar Opening="CommandBar_Opening"
            Closing="CommandBar_Closing">
    <AppBarButton Icon="Accept" Label="Accept"/>
    <AppBarButton Icon="Edit" Label="Edit"/>
    <AppBarButton Icon="Save" Label="Save"/>
    <AppBarButton Icon="Cancel" Label="Cancel"/>
</CommandBar>

private void CommandBar_Opening(object sender, object e)
{
    CommandBar cb = sender as CommandBar;
    if (cb != null) cb.Background.Opacity = 1.0;
}

private void CommandBar_Closing(object sender, object e)
{
    CommandBar cb = sender as CommandBar;
    if (cb != null) cb.Background.Opacity = 0.5;
}

IsSticky

Jika pengguna berinteraksi dengan bagian lain aplikasi saat bilah perintah terbuka, maka bilah perintah akan ditutup secara otomatis. Ini disebut pengalih cahaya. Anda dapat mengontrol perilaku pengalih cahaya dengan mengatur properti IsSticky . Ketika IsSticky="true", bilah tetap terbuka hingga pengguna menekan tombol "lihat lebih banyak" [...] atau memilih item dari menu luapan.

Sebaiknya hindari bilah perintah lengket karena tidak sesuai dengan harapan pengguna untuk mematikan lampu dan perilaku fokus keyboard.

Mode Tampilan

Anda dapat mengontrol bagaimana bilah perintah ditampilkan dalam status tertutup dengan mengatur properti ClosedDisplayMode . Ada 3 mode tampilan tertutup untuk dipilih:

• Ringkas: Mode default. Menampilkan konten, ikon perintah utama tanpa label, dan tombol "lihat lainnya" [...].
• Minimal: Hanya menampilkan bilah tipis yang bertindak sebagai tombol "lihat lebih banyak" [...]. Pengguna dapat menekan di mana saja di bilah untuk membukanya.
• Tersembunyi: Bilah perintah tidak ditampilkan saat ditutup. Ini dapat berguna untuk menampilkan perintah kontekstual dengan bilah perintah sebaris. Dalam hal ini, Anda harus membuka bilah perintah secara terprogram dengan mengatur properti IsOpen atau mengubah ClosedDisplayMode menjadi Minimal atau Ringkas.

Di sini, bilah perintah digunakan untuk menyimpan perintah pemformatan sederhana untuk RichEditBox. Saat kotak edit tidak memiliki fokus, perintah pemformatan dapat mengganggu, sehingga disembunyikan. Saat kotak edit sedang digunakan, ClosedDisplayMode bilah perintah diubah menjadi Ringkas sehingga perintah pemformatan terlihat.

<StackPanel Width="300"
            GotFocus="EditStackPanel_GotFocus"
            LostFocus="EditStackPanel_LostFocus">
    <CommandBar x:Name="FormattingCommandBar" ClosedDisplayMode="Hidden">
        <AppBarButton Icon="Bold" Label="Bold" ToolTipService.ToolTip="Bold"/>
        <AppBarButton Icon="Italic" Label="Italic" ToolTipService.ToolTip="Italic"/>
        <AppBarButton Icon="Underline" Label="Underline" ToolTipService.ToolTip="Underline"/>
    </CommandBar>
    <RichEditBox Height="200"/>
</StackPanel>

private void EditStackPanel_GotFocus(object sender, RoutedEventArgs e)
{
    FormattingCommandBar.ClosedDisplayMode = AppBarClosedDisplayMode.Compact;
}

private void EditStackPanel_LostFocus(object sender, RoutedEventArgs e)
{
    FormattingCommandBar.ClosedDisplayMode = AppBarClosedDisplayMode.Hidden;
}

Catatan

Implementasi perintah pengeditan berada di luar cakupan contoh ini. Untuk informasi selengkapnya, lihat artikel RichEditBox .

Meskipun mode Minimal dan Tersembunyi berguna dalam beberapa situasi, perlu diingat bahwa menyembunyikan semua tindakan dapat membingungkan pengguna.

Mengubah ClosedDisplayMode untuk memberikan lebih atau kurang petunjuk kepada pengguna memengaruhi tata letak elemen di sekitarnya. Sebaliknya, ketika CommandBar beralih antara tertutup dan terbuka, itu tidak memengaruhi tata letak elemen lain.

Mendapatkan kode sampel

• Sampel Galeri WinUI - Lihat semua kontrol XAML dalam format interaktif.
• Sampel Perintah XAML

Artikel terkait

• Dasar-dasar desain perintah untuk aplikasi Windows
• Flyout bilah perintah
• Menu flyout dan bilah menu
• Kelas MenuFlyout
• Kelas CommandBar