Zone de suggestion automatique

  • Article

Utilisez un objet AutoSuggestBox pour fournir une liste de suggestions afin que les utilisateurs puissent sélectionner des options au fil de leur saisie.

Zone de suggestion automatique

Est-ce le contrôle approprié ?

Si vous recherchez un contrôle simple et personnalisable permettant d’effectuer une recherche de texte avec une liste de suggestions, choisissez une zone de suggestion.

Pour plus d’informations sur le choix du contrôle de texte approprié, consultez l’article Contrôles de texte.

Anatomie

Le point d’entrée de la zone de suggestion automatique se compose d’un en-tête facultatif et d’une zone de texte avec texte d’information facultatif :

Exemple de point d’entrée pour le contrôle de suggestion automatique

La liste des résultats de suggestion automatique se remplit automatiquement dès que l’utilisateur commence à saisir du texte. La liste des résultats peut apparaître au-dessus ou en dessous de la zone de texte. Un bouton Effacer tout s’affiche :

Exemple de contrôle de suggestion automatique développé

Recommandations

  • Lorsque vous utilisez la zone de suggestion automatique pour effectuer des recherches et qu’il n’existe aucun résultat de recherche pour le texte entré, affichez le message d’une ligne « Aucun résultat » comme résultat afin que les utilisateurs sachent que leur requête de recherche a été exécutée :

    Exemple de zone de suggestion automatique sans résultat de recherche

UWP et WinUI 2

Important

Les informations et les exemples de cet article sont optimisés pour les applications qui utilisent le SDK d'application Windows et WinUI 3, mais qui s’appliquent généralement aux applications UWP qui utilisent WinUI 2. Consultez la référence API de la plateforme Windows universelle pour obtenir des informations et des exemples spécifiques à la plateforme.

Cette section contient les informations dont vous avez besoin pour utiliser le contrôle dans une application de la plateforme Windows universelle ou de WinUI 2.

Les API de ce contrôle existent dans l’espace de noms Windows.UI.Xaml.Controls .

Nous vous recommandons d’utiliser la dernière version de WinUI 2 pour obtenir les styles et modèles les plus récents pour tous les contrôles. WinUI 2.2 ou version ultérieure inclut un nouveau modèle pour ce contrôle qui utilise des coins arrondis. Pour plus d’informations, consultez Rayons des angles.

Créer une zone de suggestion automatique

Ouvrez l’application Galerie WinUI 3 et voyez autoSuggestBox en action.

L’application WinUI 3 Gallery comprend des exemples interactifs de la plupart des contrôles et des fonctionnalités WinUI 3. Procurez-vous l’application sur le Microsoft Store ou le code source sur GitHub.

Pour utiliser un objet AutoSuggestBox, vous devez répondre à 3 actions effectuées par les utilisateurs.

  • Texte modifié : lorsque l’utilisateur entre du texte, mettre à jour la liste de suggestions.
  • Suggestion choisie : lorsque l’utilisateur choisit une suggestion dans la liste de suggestions, mettre à jour la zone de texte.
  • Requête envoyée : lorsque l’utilisateur envoie une requête, afficher les résultats de la requête.

Texte modifié

L’événement TextChanged se produit chaque fois que le contenu de la zone de texte est mis à jour. Utilisez la propriété Reason d’arguments d’événement pour déterminer si la modification est due à une entrée utilisateur. Si la raison de la modification est UserInput, filtrez vos données en fonction de l’entrée. Ensuite, définissez les données filtrées comme ItemsSource de l’objet AutoSuggestBox pour mettre à jour la liste de suggestions.

Pour contrôler la façon dont les éléments sont affichés dans la liste de suggestions, vous pouvez utiliser DisplayMemberPath ou ItemTemplate.

  • Pour afficher le texte d’une seule propriété de votre élément de données, définissez la propriété DisplayMemberPath pour choisir la propriété de votre objet à afficher dans la liste de suggestions.
  • Pour définir une apparence personnalisée pour chaque élément dans la liste, utilisez la propriété ItemTemplate.

Suggestion choisie

Lorsqu’un utilisateur navigue dans la liste de suggestions à l’aide du clavier, vous devez mettre à jour le texte dans la zone de texte pour assurer la correspondance.

Vous pouvez définir la propriété TextMemberPath pour choisir la propriété de votre objet de données à afficher dans la zone de texte. Si vous spécifiez un TextMemberPath, la zone de texte est automatiquement mise à jour. Vous devez généralement spécifier la même valeur pour DisplayMemberPath et TextMemberPath afin que le texte soit identique dans la liste de suggestions et dans la zone de texte.

Si vous avez besoin d’afficher plus qu’une simple propriété, gérez l’événement SuggestionChosen pour remplir la zone de texte avec du texte personnalisé basé sur l’élément sélectionné.

Requête envoyée

Gérez l’événement QuerySubmitted pour effectuer une action de requête appropriée sur votre application et montrer les résultats à l’utilisateur.

L’événement QuerySubmitted se produit lorsqu’un utilisateur valide une chaîne de requête. L’utilisateur peut valider une requête de l’une de ces manières :

  • Lorsque le focus est sur la zone de texte, appuyez sur Entrée ou cliquez sur l’icône de requête. La propriété ChosenSuggestion des arguments d’événement est null.
  • Lorsque le focus est sur la liste de suggestions, appuyez sur Entrée, puis cliquez ou appuyez sur un élément. La propriété ChosenSuggestion des arguments d’événement contient l’élément sélectionné dans la liste.

Dans tous les cas, la propriété QueryText des arguments d’événement contient le texte de la zone de texte.

Voici un simple élément AutoSuggestBox avec les gestionnaires d’événements requis.

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

Utilisez un objet AutoSuggestBox pour fournir une liste de suggestions afin que les utilisateurs puissent sélectionner des options au fil de leur saisie.

Par défaut, la zone de texte n’affiche pas de bouton de requête. Vous pouvez définir la propriété QueryIcon pour ajouter un bouton avec l’icône spécifiée sur le côté droit de la zone de texte. Par exemple, pour rendre AutoSuggestBox similaire à une zone de recherche classique, ajoutez une icône « Rechercher » comme suit.

<AutoSuggestBox QueryIcon="Find"/>

Voici AutoSuggestBox avec une icône Rechercher.

Exemple de contrôle de suggestion automatique avec une icône de recherche.

Obtenir l’exemple de code