Bagikan melalui

Kotak saran otomatis

Gunakan AutoSuggestBox untuk memberikan daftar saran bagi pengguna untuk dipilih saat mereka mengetik.

Kotak saran otomatis

Apakah ini kontrol yang tepat?

Jika Anda ingin kontrol sederhana dan dapat disesuaikan yang memungkinkan pencarian teks dengan daftar saran, pilih kotak saran otomatis.

Untuk informasi selengkapnya tentang memilih kontrol teks yang tepat, lihat artikel Kontrol teks .

Anatomi

Titik entri untuk kotak saran otomatis terdiri dari header opsional dan kotak teks dengan teks petunjuk opsional:

Contoh titik masuk untuk kontrol saran otomatis

Daftar hasil saran otomatis terisi secara otomatis setelah pengguna mulai memasukkan teks. Daftar hasil dapat muncul di atas atau di bawah kotak entri teks. Tombol "hapus semua" muncul:

Contoh kontrol saran otomatis yang diperluas

Recommendations

  • Saat menggunakan kotak saran otomatis untuk melakukan pencarian dan tidak ada hasil pencarian untuk teks yang dimasukkan, tampilkan pesan "Tidak ada hasil" baris tunggal sebagai hasilnya sehingga pengguna tahu permintaan pencarian mereka dijalankan:

    Contoh kotak saran otomatis tanpa hasil pencarian

Membuat kotak saran otomatis

Buka aplikasi Galeri WinUI 3 dan lihat AutoSuggestBox dalam tindakan

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

Untuk menggunakan AutoSuggestBox, Anda perlu menanggapi 3 tindakan pengguna.

  • Teks diubah - Saat pengguna memasukkan teks, perbarui daftar saran.
  • Saran yang dipilih - Saat pengguna memilih saran dalam daftar saran, perbarui kotak teks.
  • Kueri dikirimkan - Saat pengguna mengirimkan kueri, perlihatkan hasil kueri.

Teks diubah

Peristiwa TextChanged terjadi setiap kali konten kotak teks diperbarui. Gunakan properti event args Reason untuk menentukan apakah perubahan tersebut disebabkan oleh input pengguna. Jika alasan perubahan adalah UserInput, filter data Anda berdasarkan input. Kemudian, atur data yang difilter sebagai ItemsSource dari AutoSuggestBox untuk memperbarui daftar saran.

Untuk mengontrol bagaimana item ditampilkan dalam daftar saran, Anda bisa menggunakan DisplayMemberPath atau ItemTemplate.

  • Untuk menampilkan teks dari satu properti item data Anda, atur properti DisplayMemberPath untuk memilih properti mana dari objek Anda yang akan ditampilkan dalam daftar saran.
  • Untuk menentukan tampilan kustom untuk setiap item dalam daftar, gunakan properti ItemTemplate.

Saran dipilih

Saat pengguna menavigasi melalui daftar saran menggunakan keyboard, Anda perlu memperbarui teks dalam kotak teks agar cocok.

Anda dapat mengatur properti TextMemberPath untuk memilih properti mana dari objek data Anda untuk ditampilkan di kotak teks. Jika Anda menentukan TextMemberPath, kotak teks diperbarui secara otomatis. Anda biasanya harus menentukan nilai yang sama untuk DisplayMemberPath dan TextMemberPath sehingga teks sama dalam daftar saran dan kotak teks.

Jika Anda perlu menampilkan lebih dari properti sederhana, tangani acara SuggestionChosen untuk mengisi kotak teks dengan teks kustom berdasarkan item yang dipilih.

Kueri dikirimkan

Tangani peristiwa QuerySubmitted untuk melakukan tindakan kueri yang sesuai dengan aplikasi Anda dan tampilkan hasilnya kepada pengguna.

Peristiwa QuerySubmitted terjadi saat pengguna menerapkan string kueri. Pengguna dapat melakukan kueri dengan salah satu cara berikut:

  • Saat fokus ada di kotak teks, tekan Enter atau klik ikon kueri. Properti event args ChosenSuggestion adalah null.
  • Saat fokus ada di daftar saran, tekan Enter, klik, atau ketuk item. Properti event args SelectedSuggestion berisi item yang dipilih dari daftar.

Dalam semua kasus, properti queryText args peristiwa berisi teks dari kotak teks.

Berikut adalah AutoSuggestBox sederhana dengan penanganan aktivitas yang diperlukan.

<AutoSuggestBox PlaceholderText="Search" QueryIcon="Find" Width="200"
                TextChanged="AutoSuggestBox_TextChanged"
                QuerySubmitted="AutoSuggestBox_QuerySubmitted"
                SuggestionChosen="AutoSuggestBox_SuggestionChosen"/>

private void AutoSuggestBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
{
    // Only get results when it was a user typing,
    // otherwise assume the value got filled in by TextMemberPath
    // or the handler for SuggestionChosen.
    if (args.Reason == AutoSuggestionBoxTextChangeReason.UserInput)
    {
        //Set the ItemsSource to be your filtered dataset
        //sender.ItemsSource = dataset;
    }
}


private void AutoSuggestBox_SuggestionChosen(AutoSuggestBox sender, AutoSuggestBoxSuggestionChosenEventArgs args)
{
    // Set sender.Text. You can use args.SelectedItem to build your text string.
}


private void AutoSuggestBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
{
    if (args.ChosenSuggestion != null)
    {
        // User selected an item from the suggestion list, take an action on it here.
    }
    else
    {
        // Use args.QueryText to determine what to do.
    }
}

Gunakan AutoSuggestBox untuk memberikan daftar saran bagi pengguna untuk dipilih saat mereka mengetik.

Secara default, kotak entri teks tidak memiliki tombol kueri yang diperlihatkan. Anda bisa mengatur properti QueryIcon untuk menambahkan tombol dengan ikon yang ditentukan di sisi kanan kotak teks. Misalnya, untuk membuat AutoSuggestBox terlihat seperti kotak pencarian biasa, tambahkan ikon 'temukan', seperti ini.

<AutoSuggestBox QueryIcon="Find"/>

Berikut adalah AutoSuggestBox dengan ikon 'temukan'.

Contoh kontrol saran otomatis dengan ikon temukan.

  • Last updated on