Pole z sugestiami automatycznymi

Użyj kontrolki AutoSuggestBox, aby podać listę sugestii dla użytkownika do wybrania w miarę ich wpisywania.

Czy jest to właściwa kontrola?

Jeśli szukasz prostego, dostosowywalnego kontrolera pozwalającego na wyszukiwanie tekstu z listą sugestii, wybierz pole podpowiedzi.

Aby uzyskać więcej informacji na temat wybierania odpowiedniej kontrolki tekstu, zobacz artykuł Kontrolki tekstu .

Anatomia

Punkt wejścia dla pola automatycznego sugerowania składa się z opcjonalnego nagłówka i pola tekstowego z opcjonalnym tekstem wskazówki:

Automatycznie sugerowana lista wyników jest wypełniana automatycznie po rozpoczęciu wprowadzania tekstu przez użytkownika. Lista wyników może pojawić się powyżej lub poniżej pola wprowadzania tekstu. Zostanie wyświetlony przycisk "Wyczyść wszystko":

Rekomendacje

• W przypadku używania pola automatycznego sugerowania do przeprowadzania wyszukiwań i nie istnieją żadne wyniki wyszukiwania dla wprowadzonego tekstu, wyświetl jednowierszowy komunikat "Brak wyników" w wyniku, aby użytkownicy wiedzieli, że zostało wykonane żądanie wyszukiwania:

  

Utwórz pole automatycznego sugerowania

Aplikacja Galeria WinUI 3 zawiera interaktywne przykłady większości kontrolek, funkcji i funkcji interfejsu WinUI 3. Pobierz aplikację ze Sklepu Microsoft lub pobierz kod źródłowy w witrynie GitHub

Aby użyć kontrolki AutoSuggestBox, musisz odpowiedzieć na 3 akcje użytkownika.

• Tekst uległ zmianie — gdy użytkownik wprowadza tekst, zaktualizuj listę sugestii.
• Wybrana sugestia — gdy użytkownik wybierze sugestię na liście sugestii, zaktualizuj pole tekstowe.
• Przesłane zapytanie — gdy użytkownik przesyła zapytanie, pokaż wyniki zapytania.

Zmieniono tekst

Zdarzenie TextChanged występuje za każdym razem, gdy zawartość pola tekstowego zostanie zaktualizowana. Użyj właściwości event args Reason, aby określić, czy zmiana była spowodowana danymi wejściowymi użytkownika. Jeśli przyczyną zmiany jest UserInput, przefiltruj dane na podstawie danych wejściowych. Następnie ustaw przefiltrowane dane jako ItemsSource dla AutoSuggestBox, aby zaktualizować listę sugestii.

Aby kontrolować sposób wyświetlania elementów na liście sugestii, możesz użyć DisplayMemberPath lub ItemTemplate.

• Aby wyświetlić tekst pojedynczej właściwości elementu danych, ustaw właściwość DisplayMemberPath, aby wybrać właściwość z obiektu do wyświetlenia na liście sugestii.
• Aby zdefiniować niestandardowy wygląd każdego elementu na liście, użyj właściwości ItemTemplate.

Wybrana sugestia

Gdy użytkownik przejdzie przez listę sugestii przy użyciu klawiatury, musisz zaktualizować tekst w polu tekstowym, aby był zgodny.

Możesz ustawić właściwość TextMemberPath, aby wybrać właściwość obiektu danych do wyświetlenia w polu tekstowym. Jeśli określisz element TextMemberPath, pole tekstowe zostanie automatycznie zaktualizowane. Zazwyczaj należy określić tę samą wartość dla parametrów DisplayMemberPath i TextMemberPath, aby tekst był taki sam na liście sugestii i w polu tekstowym.

Jeśli musisz pokazać więcej niż prostą właściwość, obsłuż zdarzenie SuggestionChosen, aby wypełnić pole tekstowe tekstem niestandardowym na podstawie wybranego elementu.

Przesłane zapytanie

Obsłuż zdarzenie QuerySubmitted, aby wykonać akcję zapytania odpowiednią dla aplikacji i pokazać wynik użytkownikowi.

Zdarzenie QuerySubmitted występuje, gdy użytkownik zatwierdza ciąg zapytania. Użytkownik może zatwierdzić zapytanie na jeden z następujących sposobów:

• Gdy fokus znajduje się w polu tekstowym, naciśnij Enter lub kliknij ikonę zapytania. Właściwość Argumentu Zdarzenia ChosenSuggestion ma wartość null.
• Gdy fokus znajduje się na liście sugestii, naciśnij Enter, kliknij lub stuknij element. Właściwość event args SelectedSuggestion zawiera element wybrany z listy.

We wszystkich przypadkach właściwość event args QueryText zawiera tekst z pola tekstowego.

Oto prosta funkcja AutoSuggestBox z wymaganymi procedurami obsługi zdarzeń.

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

Użyj autosuggestBox do wyszukiwania

Użyj kontrolki AutoSuggestBox, aby podać listę sugestii dla użytkownika do wybrania w miarę ich wpisywania.

Domyślnie pole wprowadzania tekstu nie ma wyświetlanego przycisku zapytania. Możesz ustawić właściwość QueryIcon, aby dodać przycisk z określoną ikoną po prawej stronie pola tekstowego. Na przykład aby pole AutoSuggestBox wyglądało jak typowe pole wyszukiwania, dodaj ikonę "znajdź" w następujący sposób.

<AutoSuggestBox QueryIcon="Find"/>

Oto autosuggestBox z ikoną "znajdź".

UwP i WinUI 2

API dla tej kontrolki istnieją w ramach przestrzeni nazw Windows.UI.Xaml.Controls.

Zalecamy użycie najnowszej wersji WinUI 2 , aby uzyskać najbardziej aktualne style i szablony dla wszystkich kontrolek. Interfejs WinUI 2.2 lub nowszy zawiera nowy szablon dla tej kontrolki, który używa zaokrąglonych narożników. Aby uzyskać więcej informacji, zobacz Zaokrąglenie narożnika.

Powiązane artykuły

• Kontrolki tekstu
• sprawdzanie pisowni
• Klasa TextBox
• windows.UI.Xaml.Controls PasswordBox, klasa
• Właściwość String.Length