Automatisk förslagsbox

Använd en AutoSuggestBox för att ange en lista med förslag som en användare kan välja mellan när de skriver.

Är det här rätt kontroll?

Om du vill ha en enkel, anpassningsbar kontroll som tillåter textsökning med en lista med förslag väljer du en automatisk förslagsruta.

Mer information om hur du väljer rätt textkontroll finns i artikeln Textkontroller .

Anatomi

Startpunkten för rutan för automatisk förslag består av en valfri rubrik och en textruta med valfri tipstext:

Resultatlistan för automatisk förslag fylls i automatiskt när användaren börjar ange text. Resultatlistan kan visas ovanför eller under textrutan. En "rensa alla"-knapp visas:

Recommendations

• När du använder rutan Föreslå automatiskt för att utföra sökningar och det inte finns några sökresultat för den angivna texten, visar du ett meddelande med en rad "Inga resultat" som resultat så att användarna vet att deras sökbegäran körs:

  

Skapa en automatisk förslagsruta

• Viktiga API:er:AutoSuggestBox-klass, TextChanged-händelse, SuggestionChose-händelse, QuerySubmitted-händelse

Öppna WinUI 3-galleriappen och se AutoSuggestBox i praktiken

WinUI 3-galleriappen innehåller interaktiva exempel på WinUI-kontroller och funktioner. Hämta appen från Microsoft Store eller bläddra i källkoden på GitHub.

Om du vill använda en AutoSuggestBox måste du svara på tre användaråtgärder.

• Text har ändrats – När användaren anger text uppdaterar du förslagslistan.
• Förslag valt – Uppdatera textrutan när användaren väljer ett förslag i förslagslistan.
• Skickad fråga – När användaren skickar en fråga visar du frågeresultatet.

Text har ändrats

Händelsen TextChanged inträffar när innehållet i textrutan uppdateras. Använd egenskapen event args Reason för att avgöra om ändringen berodde på användarindata. Om ändringsorsaken är UserInput filtrerar du dina data baserat på indata. Ange sedan filtrerade data som ItemsSource i AutoSuggestBox för att uppdatera förslagslistan.

Om du vill styra hur objekt visas i förslagslistan kan du använda DisplayMemberPath eller ItemTemplate.

• Om du vill visa texten i en enda egenskap för dataobjektet anger du egenskapen DisplayMemberPath för att välja vilken egenskap från objektet som ska visas i förslagslistan.
• Om du vill definiera ett anpassat utseende för varje objekt i listan använder du egenskapen ItemTemplate.

Förslag valt

När en användare navigerar i förslagslistan med tangentbordet måste du uppdatera texten i textrutan så att den matchar.

Du kan ange egenskapen TextMemberPath till att välja vilken egenskap från dataobjektet som ska visas i textrutan. Om du anger en TextMemberPath uppdateras textrutan automatiskt. Du bör vanligtvis ange samma värde för DisplayMemberPath och TextMemberPath så att texten är densamma i förslagslistan och textrutan.

Om du behöver visa mer än en enkel egenskap hanterar du händelsen SuggestionChosen för att fylla i textrutan med anpassad text baserat på det markerade objektet.

Skickad fråga

Hantera händelsen QuerySubmitted för att utföra en frågeåtgärd som är lämplig för din app och visa resultatet för användaren.

Händelsen QuerySubmitted inträffar när en användare bekräftar en frågesträng. Användaren kan checka in en fråga på något av följande sätt:

• Medan fokus ligger i textrutan trycker du på Retur eller klickar på frågeikonen. Event args ChosenSuggestion-egenskapen är null.
• Medan fokus finns i förslagslistan trycker du på Retur, klickar eller trycker på ett objekt. Egenskapen event args ChosenSuggestion innehåller det objekt som har valts från listan.

I samtliga fall innehåller egenskapen event args QueryText texten från textrutan.

Här är en enkel AutoSuggestBox med nödvändiga händelsehanterare.

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

Använda AutoSuggestBox för sökning

Använd en AutoSuggestBox för att ange en lista med förslag som en användare kan välja mellan när de skriver.

Som standard visas ingen frågeknapp i textrutan. Du kan ange egenskapen QueryIcon för att lägga till en knapp med den angivna ikonen till höger i textrutan. Om du till exempel vill att AutoSuggestBox ska se ut som en typisk sökruta lägger du till en sökikon, så här.

<AutoSuggestBox QueryIcon="Find"/>

Här är en AutoSuggestBox med en "find"-ikon.

Relaterade artiklar

• Textkontroller
• Stavningskontroll
• Textbox-klass
• Windows.UI.Xaml.Controls PasswordBox-klassen
• String.Length-egenskap