Freigeben über

Feld mit automatischen Vorschlägen

  • Artikel

Verwenden Sie ein AutoSuggestBox-Steuerelement, um eine Liste von Vorschlägen bereitzustellen, aus der ein Benutzer während der Eingabe auswählen kann.

Ein Feld für automatische Vorschläge

Ist dies das richtige Steuerelement?

Wenn Sie ein einfaches, anpassbares Steuerelement wünschen, das die Textsuche mit einer Liste von Vorschlägen zulässt, wählen Sie ein Feld für automatische Vorschläge aus.

Weitere Informationen zur Auswahl des passenden Textsteuerelements finden Sie im Artikel Textsteuerelemente.

Aufbau

Der Einstiegspunkt für das Feld für automatische Vorschläge besteht aus einer optionalen Kopfzeile und einem Textfeld mit optionalem Hinweistext:

Beispiel für den Einstiegspunkt für das Steuerelement mit automatischen Vorschlägen

Die Ergebnisliste für automatische Vorschläge wird automatisch ausgefüllt, sobald der Benutzer mit der Eingabe von Text beginnt. Die Ergebnisliste kann oberhalb oder unterhalb des Textfelds angezeigt werden. Eine Schaltfläche "Alles löschen" wird angezeigt:

Beispiel für das erweiterte Steuerelement für automatische Vorschläge

Empfehlungen

  • Wenn Sie das Feld "Automatische Vorschläge" zum Ausführen von Suchvorgängen verwenden und für den eingegebenen Text keine Suchergebnisse vorhanden sind, wird als Ergebnis eine einzeilige Meldung "Keine Ergebnisse" angezeigt, damit Benutzer ihre Suchanforderung ausführen können:

    Beispiel für ein Feld für automatische Vorschläge ohne Suchergebnisse

UWP und WinUI 2

Wichtig

Die Informationen und Beispiele in diesem Artikel sind für Apps optimiert, die das Windows App SDK und WinUI 3 verwenden, gelten jedoch allgemein für UWP-Apps, die WinUI 2 verwenden. In der UWP-API-Referenz finden Sie plattformspezifische Informationen und Beispiele.

Dieser Abschnitt enthält Informationen, die Sie zum Verwenden des Steuerelements in einer UWP- oder WinUI 2-App benötigen.

APIs für dieses Steuerelement sind im Windows.UI.Xaml.Controls-Namespace vorhanden.

Wir empfehlen die Verwendung der neuesten WinUI 2 zum Abrufen der aktuellsten Stile und Vorlagen für alle Steuerelemente. WinUI 2.2 oder höher enthält eine neue Vorlage für dieses Steuerelement, die abgerundete Ecken verwendet. Weitere Informationen finden Sie unter Eckradius.

Erstellen eines Felds für automatische Vorschläge

Öffnen Sie die WinUI 3 Gallery-App, und zeigen Sie die Aktion AutoSuggestBox an.

Die WinUI 3-Katalog-App umfasst interaktive Beispiele für die meisten WinUI 3-Steuerelemente, -Features und -Funktionen. Laden Sie die App aus dem Microsoft Store herunter, oder rufen Sie den Quellcode auf GitHub ab

Um ein AutoSuggestBox-Steuerelement zu verwenden, müssen Sie auf drei Benutzeraktionen reagieren.

  • Text geändert – Wenn der Benutzer Text eingibt, aktualisieren Sie die Vorschlagsliste.
  • Vorschlag ausgewählt – Wenn der Benutzer einen Vorschlag in der Vorschlagsliste auswählt, aktualisieren Sie das Textfeld.
  • Abfrage übermittelt – Wenn der Benutzer eine Abfrage sendet, zeigen Sie die Abfrageergebnisse an.

Text geändert

Das TextChanged-Ereignis tritt auf, wenn der Inhalt des Textfelds aktualisiert wird. Verwenden Sie die Eigenschaft "Event args Reason ", um zu bestimmen, ob die Änderung auf Benutzereingaben zurückzuführen war. Wenn der Änderungsgrund "UserInput" lautet, filtern Sie Ihre Daten basierend auf der Eingabe. Legen Sie dann die gefilterten Daten als ItemsSource des AutoSuggestBox-Steuerelements fest, um die Vorschlagsliste zu aktualisieren.

Um zu steuern, wie Elemente in der Vorschlagsliste angezeigt werden, können Sie DisplayMemberPath oder ItemTemplate verwenden.

  • Um den Text einer einzelnen Eigenschaft Ihres Datenelements anzuzeigen, legen Sie die DisplayMemberPath-Eigenschaft fest, um auszuwählen, welche Eigenschaft aus Ihrem Objekt in der Vorschlagsliste angezeigt werden soll.
  • Verwenden Sie die ItemTemplate-Eigenschaft, um ein benutzerdefiniertes Aussehen für jedes Element in der Liste zu definieren.

Ausgewählter Vorschlag

Wenn ein Benutzer mithilfe der Tastatur durch die Vorschlagsliste navigiert, müssen Sie den Text im Textfeld entsprechend aktualisieren.

Sie können die TextMemberPath-Eigenschaft festlegen, um auszuwählen, welche Eigenschaft aus Ihrem Datenobjekt im Textfeld angezeigt werden soll. Wenn Sie einen TextMemberPath angeben, wird das Textfeld automatisch aktualisiert. Normalerweise sollten Sie denselben Wert für DisplayMemberPath und TextMemberPath angeben, sodass der Text in der Vorschlagsliste und im Textfeld identisch ist.

Wenn Sie mehr als eine einfache Eigenschaft anzeigen müssen, behandeln Sie das SuggestionChosen-Ereignis , um das Textfeld basierend auf dem ausgewählten Element mit benutzerdefiniertem Text aufzufüllen.

Übermittelte Abfrage

Behandeln Sie das QuerySubmitted-Ereignis , um eine Abfrageaktion auszuführen, die für Ihre App geeignet ist, und zeigen Sie dem Benutzer das Ergebnis an.

Das QuerySubmitted-Ereignis tritt auf, wenn ein Benutzer eine Abfragezeichenfolge commits. Der Benutzer kann eine Abfrage auf eine der folgenden Arten übernehmen:

  • Während sich der Fokus im Textfeld befindet, drücken Sie die EINGABETASTE, oder klicken Sie auf das Abfragesymbol. Die Ereignisargumente ChosenSuggestion-Eigenschaft ist NULL.
  • Während sich der Fokus in der Vorschlagsliste befindet, drücken Sie die EINGABETASTE, klicken oder tippen Sie auf ein Element. Die Ereignisargumente SelectedSuggestion-Eigenschaft enthält das Element, das aus der Liste ausgewählt wurde.

In allen Fällen enthält die QueryText-Eigenschaft des Ereignisses den Text aus dem Textfeld.

Hier ist ein einfaches AutoSuggestBox-Steuerelement mit den erforderlichen Ereignishandlern.

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

Verwenden Sie ein AutoSuggestBox-Steuerelement, um eine Liste von Vorschlägen bereitzustellen, aus der ein Benutzer während der Eingabe auswählen kann.

Standardmäßig wird für das Texteingabefeld keine Abfrageschaltfläche angezeigt. Sie können die QueryIcon-Eigenschaft festlegen, um eine Schaltfläche mit dem angegebenen Symbol auf der rechten Seite des Textfelds hinzuzufügen. Wenn das AutoSuggestBox-Element wie ein typisches Suchfeld aussehen soll, fügen Sie beispielsweise wie folgt ein Suchsymbol hinzu.

<AutoSuggestBox QueryIcon="Find"/>

Hier sehen Sie ein AutoSuggestBox-Steuerelement mit einem Symbol "Suchen".

Beispiel für ein Steuerelement mit automatischen Vorschlägen mit einem Suchsymbol.

Beispielcode herunterladen