Kotak kombo dan kotak daftar

Gunakan kotak kombo (juga dikenal sebagai daftar drop-down) untuk menyajikan daftar item yang dapat dipilih pengguna. Kotak kombo dimulai dalam status ringkas dan diperluas untuk memperlihatkan daftar item yang dapat dipilih. Kotak daftar mirip dengan kotak kombo, tetapi tidak dapat diciutkan/tidak memiliki status ringkas. Anda bisa mempelajari selengkapnya tentang kotak daftar di akhir artikel ini.

Ketika kotak kombo ditutup, kotak kombo menampilkan pilihan saat ini atau kosong jika tidak ada item yang dipilih. Saat pengguna memperluas kotak kombo, pengguna akan menampilkan daftar item yang dapat dipilih.

Apakah ini kontrol yang tepat?

• Gunakan daftar drop-down untuk memungkinkan pengguna memilih satu nilai dari sekumpulan item yang dapat diwakili secara memadai dengan satu baris teks.
• Gunakan tampilan daftar atau kisi alih-alih kotak kombo untuk menampilkan item yang berisi beberapa baris teks atau gambar.
• Ketika ada kurang dari lima item, pertimbangkan untuk menggunakan tombol radio (jika hanya satu item yang dapat dipilih) atau kotak centang (jika beberapa item dapat dipilih).
• Gunakan kotak kombo saat item pilihan sangat penting sekunder dalam alur aplikasi Anda. Jika opsi default direkomendasikan untuk sebagian besar pengguna dalam sebagian besar situasi, menampilkan semua item dengan menggunakan tampilan daftar mungkin menarik lebih banyak perhatian pada opsi daripada yang diperlukan. Anda dapat menghemat ruang dan meminimalkan gangguan dengan menggunakan kotak kombo.

Contoh

Kotak kombo dalam status ringkasnya dapat menampilkan header.

Meskipun kotak kombo diperluas untuk mendukung panjang string yang lebih lama, hindari string yang terlalu panjang yang sulit dibaca.

Jika koleksi dalam kotak kombo cukup panjang, bilah gulir akan muncul untuk mengakomodasinya. Kelompokkan item secara logis dalam daftar.

Rekomendasi

• Batasi konten teks item kotak kombo ke satu baris.
• Urutkan item dalam kotak kombo dalam urutan paling logis. Kelompokkan opsi terkait dan tempatkan opsi paling umum di bagian atas. Urutkan nama dalam urutan alfabet, angka dalam urutan numerik, dan tanggal dalam urutan kronologis.

Kotak daftar

Kotak daftar memungkinkan pengguna untuk memilih satu item atau beberapa item dari koleksi. Kotak daftar mirip dengan daftar drop-down, kecuali kotak daftar selalu terbuka—tidak ada status ringkas (tidak diperluas) untuk kotak daftar. Item dalam daftar dapat digulir jika tidak ada spasi untuk menampilkan semuanya.

Apakah kotak daftar memiliki kontrol yang tepat?

• Kotak daftar dapat berguna ketika item dalam daftar cukup penting untuk ditampilkan secara menonjol, dan ketika ada cukup real estat layar, untuk menampilkan daftar lengkap.
• Kotak daftar harus menarik perhatian pengguna ke serangkaian alternatif lengkap dalam pilihan penting. Sebaliknya, daftar drop-down awalnya menarik perhatian pengguna ke item yang dipilih.
• Hindari menggunakan kotak daftar jika:
  • Ada sejumlah kecil item untuk daftar. Kotak daftar pilihan tunggal yang selalu memiliki 2 opsi yang sama mungkin lebih baik disajikan sebagai tombol radio. Pertimbangkan juga untuk menggunakan tombol radio ketika ada 3 atau 4 item statis dalam daftar.
  • Kotak daftar dipilih tunggal dan selalu memiliki 2 opsi yang sama di mana satu dapat disiratkan sebagai bukan yang lain, seperti "aktif" dan "nonaktif." Gunakan kotak centang tunggal atau sakelar pengalih.
  • Ada sejumlah besar item. Pilihan yang lebih baik untuk daftar panjang adalah tampilan kisi dan tampilan daftar. Untuk daftar data yang dikelompokkan yang sangat panjang, zoom semantik lebih disukai.
  • Item adalah nilai numerik yang bersebelah. Jika demikian, pertimbangkan untuk menggunakan slider.
  • Item pilihan sangat penting dalam alur aplikasi Anda atau opsi default direkomendasikan untuk sebagian besar pengguna dalam sebagian besar situasi. Gunakan daftar drop-down sebagai gantinya.

Rekomendasi untuk kotak daftar

• Rentang item yang ideal dalam kotak daftar adalah 3 hingga 9.
• Kotak daftar berfungsi dengan baik ketika itemnya dapat bervariasi secara dinamis.
• Jika memungkinkan, atur ukuran kotak daftar sehingga daftar itemnya tidak perlu digerakkan atau digulir.
• Verifikasi bahwa tujuan kotak daftar, dan item mana yang saat ini dipilih, kosong.
• Pesan efek visual dan animasi untuk umpan balik sentuh, dan untuk status item yang dipilih.
• Batasi konten teks item kotak daftar ke satu baris. Jika item adalah visual, Anda dapat menyesuaikan ukurannya. Jika item berisi beberapa baris teks atau gambar, gunakan tampilan kisi atau tampilan daftar.
• Gunakan font default kecuali pedoman merek Anda menunjukkan untuk menggunakan yang lain.
• Jangan gunakan kotak daftar untuk melakukan perintah atau menampilkan atau menyembunyikan kontrol lain secara dinamis.

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 ComboBox, properti IsEditable, Properti teks, peristiwa TextSubmitted, kelas ListBox
• Buka aplikasi Galeri WinUI 2 dan lihat ComboBox dalam tindakan. 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.

WinUI 2.2 atau yang lebih baru menyertakan templat baru untuk kontrol ini yang menggunakan sudut bulat. Untuk informasi selengkapnya, lihat radius sudut.

Membuat kotak kombo

• API Penting: Kelas ComboBox, properti IsEditable, Properti teks, peristiwa TextSubmitted, kelas ListBox

Buka aplikasi Galeri WinUI 3 dan lihat ComboBox dalam tindakan.

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

Anda mengisi kotak kombo dengan menambahkan objek langsung ke koleksi Item atau dengan mengikat properti ItemsSource ke sumber data. Item yang ditambahkan ke ComboBox dibungkus dalam kontainer ComboBoxItem .

Berikut adalah kotak kombo sederhana dengan item yang ditambahkan di XAML.

<ComboBox Header="Colors" PlaceholderText="Pick a color" Width="200">
    <x:String>Blue</x:String>
    <x:String>Green</x:String>
    <x:String>Red</x:String>
    <x:String>Yellow</x:String>
</ComboBox>

Contoh berikut menunjukkan pengikatan kotak kombo ke kumpulan objek FontFamily.

<ComboBox x:Name="FontsCombo" Header="Fonts" Height="44" Width="296"
          ItemsSource="{x:Bind fonts}" DisplayMemberPath="Source"/>

ObservableCollection<FontFamily> fonts = new ObservableCollection<FontFamily>()
{
    fonts.Add(new FontFamily("Arial"));
    fonts.Add(new FontFamily("Courier New"));
    fonts.Add(new FontFamily("Times New Roman"));
};

Pilihan item

Seperti ListView dan GridView, ComboBox berasal dari Selector, sehingga Anda bisa mendapatkan pilihan pengguna dengan cara standar yang sama.

Anda bisa mendapatkan atau mengatur item yang dipilih kotak kombo dengan menggunakan properti SelectedItem , dan mendapatkan atau mengatur indeks item yang dipilih dengan menggunakan properti SelectedIndex .

Untuk mendapatkan nilai properti tertentu pada item data yang dipilih, Anda bisa menggunakan properti SelectedValue . Dalam hal ini, atur SelectedValuePath untuk menentukan properti mana pada item yang dipilih untuk mendapatkan nilai.

Tip

Jika Anda mengatur SelectedItem atau SelectedIndex untuk menunjukkan pilihan default, pengecualian terjadi jika properti diatur sebelum kumpulan Item kotak kombo diisi. Kecuali Anda menentukan Item di XAML, yang terbaik adalah menangani peristiwa dimuat kotak kombo, dan mengatur SelectedItem atau SelectedIndex di penanganan aktivitas yang dimuat.

Anda dapat mengikat properti ini di XAML, atau menangani peristiwa SelectionChanged untuk merespons perubahan pilihan.

Dalam kode penanganan aktivitas, Anda bisa mendapatkan item yang dipilih dari properti SelectionChangedEventArgs.AddedItems . Anda bisa mendapatkan item yang dipilih sebelumnya (jika ada) dari properti SelectionChangedEventArgs.RemovedItems . Koleksi AddedItems dan RemovedItems masing-masing hanya berisi 1 item karena kotak kombo tidak mendukung beberapa pilihan.

Contoh ini memperlihatkan cara menangani peristiwa SelectionChanged, dan juga cara mengikat ke item yang dipilih.

<StackPanel>
    <ComboBox x:Name="colorComboBox" Width="200"
              Header="Colors" PlaceholderText="Pick a color"
              SelectionChanged="ColorComboBox_SelectionChanged">
        <x:String>Blue</x:String>
        <x:String>Green</x:String>
        <x:String>Red</x:String>
        <x:String>Yellow</x:String>
    </ComboBox>

    <Rectangle x:Name="colorRectangle" Height="30" Width="100"
               Margin="0,8,0,0" HorizontalAlignment="Left"/>

    <TextBlock Text="{x:Bind colorComboBox.SelectedIndex, Mode=OneWay}"/>
    <TextBlock Text="{x:Bind colorComboBox.SelectedItem, Mode=OneWay}"/>
</StackPanel>

private void ColorComboBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    string colorName = e.AddedItems[0].ToString();
    Color color;
    switch (colorName)
    {
        case "Yellow":
            color = Colors.Yellow;
            break;
        case "Green":
            color = Colors.Green;
            break;
        case "Blue":
            color = Colors.Blue;
            break;
        case "Red":
            color = Colors.Red;
            break;
    }
    colorRectangle.Fill = new SolidColorBrush(color);
}

SelectionChanged dan navigasi keyboard

Secara default, peristiwa SelectionChanged terjadi saat pengguna mengklik, mengetuk, atau menekan Enter pada item dalam daftar untuk menerapkan pilihan mereka, dan kotak kombo ditutup. Pilihan tidak berubah saat pengguna menavigasi daftar kotak kombo terbuka dengan tombol panah keyboard.

Untuk membuat kotak kombo yang "pembaruan langsung" saat pengguna menavigasi daftar terbuka dengan tombol panah (seperti drop-down pilihan Font), atur SelectionChangedTrigger ke Always. Ini menyebabkan peristiwa SelectionChanged terjadi ketika fokus berubah ke item lain di daftar terbuka.

Perubahan perilaku item yang dipilih

Di Windows 10, versi 1809 (SDK 17763) atau yang lebih baru, perilaku item yang dipilih diperbarui untuk mendukung kotak kombo yang dapat diedit.

Sebelum SDK 17763, nilai properti SelectedItem (dan oleh karena itu, SelectedValue dan SelectedIndex) harus berada di koleksi Item kotak kombo. Menggunakan contoh sebelumnya, pengaturan colorComboBox.SelectedItem = "Pink" menghasilkan:

• SelectedItem = null
• NilaiPilih = null
• SelectedIndex = -1

Di SDK 17763 dan yang lebih baru, nilai properti SelectedItem (dan oleh karena itu, SelectedValue dan SelectedIndex) tidak diharuskan berada dalam koleksi Item kotak kombo. Menggunakan contoh sebelumnya, pengaturan colorComboBox.SelectedItem = "Pink" menghasilkan:

• SelectedItem = Pink
• NilaiPilih = Merah Muda
• SelectedIndex = -1

Pencarian Teks

Kotak kombo secara otomatis mendukung pencarian dalam koleksi mereka. Saat pengguna mengetik karakter pada keyboard fisik saat berfokus pada kotak kombo terbuka atau tertutup, kandidat yang cocok dengan string pengguna ditampilkan. Fungsionalitas ini sangat membantu saat menavigasi daftar panjang. Misalnya, saat berinteraksi dengan drop-down yang berisi daftar status, pengguna dapat menekan tombol "w" untuk menampilkan "Washington" untuk pemilihan cepat. Pencarian teks tidak peka huruf besar/kecil.

Anda dapat mengatur properti IsTextSearchEnabled ke false untuk menonaktifkan fungsionalitas ini.

Membuat kotak kombo dapat diedit

Penting

Fitur ini memerlukan Windows 10, versi 1809 (SDK 17763) atau yang lebih baru.

Secara default, kotak kombo memungkinkan pengguna memilih dari daftar opsi yang telah ditentukan sebelumnya. Namun, ada kasus di mana daftar hanya berisi subset nilai yang valid, dan pengguna harus dapat memasukkan nilai lain yang tidak tercantum. Untuk mendukung ini, Anda dapat membuat kotak kombo dapat diedit.

Untuk membuat kotak kombo dapat diedit, atur properti IsEditable ke true. Kemudian, tangani peristiwa TextSubmitted untuk bekerja dengan nilai yang dimasukkan oleh pengguna.

Secara default, nilai SelectedItem diperbarui saat pengguna menerapkan teks kustom. Anda dapat mengambil alih perilaku ini dengan mengatur Ditangani ke true di arg peristiwa TextSubmitted. Ketika peristiwa ditandai sebagai ditangani, kotak kombo tidak akan mengambil tindakan lebih lanjut setelah peristiwa dan akan tetap dalam status pengeditan. SelectedItem tidak akan diperbarui.

Contoh ini memperlihatkan kotak kombo sederhana yang dapat diedit. Daftar berisi string sederhana, dan nilai apa pun yang dimasukkan oleh pengguna digunakan seperti yang dimasukkan.

Pemilih "nama yang baru digunakan" memungkinkan pengguna memasukkan string kustom. Daftar 'RecentlyUsedNames' berisi beberapa nilai yang dapat dipilih pengguna, tetapi pengguna juga dapat menambahkan nilai kustom baru. Properti 'CurrentName' mewakili nama yang saat ini dimasukkan.

<ComboBox IsEditable="true"
          ItemsSource="{x:Bind RecentlyUsedNames}"
          SelectedItem="{x:Bind CurrentName, Mode=TwoWay}"/>

Teks dikirimkan

Anda dapat menangani peristiwa TextSubmitted agar berfungsi dengan nilai yang dimasukkan oleh pengguna. Di penanganan aktivitas, Anda biasanya akan memvalidasi bahwa nilai yang dimasukkan oleh pengguna valid, lalu menggunakan nilai di aplikasi Anda. Bergantung pada situasinya, Anda mungkin juga menambahkan nilai ke daftar opsi kotak kombo untuk digunakan di masa mendatang.

Peristiwa TextSubmitted terjadi ketika kondisi ini terpenuhi:

• Properti IsEditable benar
• Pengguna memasukkan teks yang tidak cocok dengan entri yang ada di daftar kotak kombo
• Pengguna menekan Enter, atau memindahkan fokus dari kotak kombo.

Peristiwa TextSubmitted tidak terjadi jika pengguna memasukkan teks lalu menavigasi ke atas atau ke bawah melalui daftar.

Sampel - Memvalidasi input dan menggunakan secara lokal

Dalam contoh ini, pemilih ukuran font berisi sekumpulan nilai yang sesuai dengan ramp ukuran font, tetapi pengguna dapat memasukkan ukuran font yang tidak ada dalam daftar.

Saat pengguna menambahkan nilai yang tidak ada dalam daftar, ukuran font diperbarui, tetapi nilainya tidak ditambahkan ke daftar ukuran font.

Jika nilai yang baru dimasukkan tidak valid, Anda menggunakan SelectedValue untuk mengembalikan properti Teks ke nilai baik terakhir yang diketahui.

<ComboBox x:Name="fontSizeComboBox"
          IsEditable="true"
          ItemsSource="{x:Bind ListOfFontSizes}"
          TextSubmitted="FontSizeComboBox_TextSubmitted"/>

private void FontSizeComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSubmittedEventArgs e)
{
    if (byte.TryParse(e.Text, out double newValue))
    {
        // Update the app's font size.
        _fontSize = newValue;
    }
    else
    {
        // If the item is invalid, reject it and revert the text.
        // Mark the event as handled so the framework doesn't update the selected item.
        sender.Text = sender.SelectedValue.ToString();
        e.Handled = true;
    }
}

Sampel - Memvalidasi input dan menambahkan ke daftar

Di sini, "pemilih warna favorit" berisi warna favorit paling umum (Merah, Biru, Hijau, Oranye), tetapi pengguna dapat memasukkan warna favorit yang tidak ada dalam daftar. Saat pengguna menambahkan warna yang valid (seperti Merah Muda), warna yang baru dimasukkan ditambahkan ke daftar dan ditetapkan sebagai "warna favorit" aktif.

<ComboBox x:Name="favoriteColorComboBox"
          IsEditable="true"
          ItemsSource="{x:Bind ListOfColors}"
          TextSubmitted="FavoriteColorComboBox_TextSubmitted"/>

private void FavoriteColorComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSubmittedEventArgs e)
{
    if (IsValid(e.Text))
    {
        FavoriteColor newColor = new FavoriteColor()
        {
            ColorName = e.Text,
            Color = ColorFromStringConverter(e.Text)
        }
        ListOfColors.Add(newColor);
    }
    else
    {
        // If the item is invalid, reject it but do not revert the text.
        // Mark the event as handled so the framework doesn't update the selected item.
        e.Handled = true;
    }
}

bool IsValid(string Text)
{
    // Validate that the string is: not empty; a color.
}

Mendapatkan kode sampel

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

Artikel terkait

• Kontrol teks
• Panduan untuk pemeriksaan ejaan
• Kelas TextBox
• Kelas PasswordBox
• Properti String.Length