LgSuggestBox

LgSuggestBox est un champ texte qui propose des suggestions pendant la saisie : les valeurs correspondantes sont affichées dans un menu déroulant et la valeur retenue reste une saisie libre (la sélection d'une suggestion est facultative). Les suggestions viennent d'une liste locale (Items) ou d'un contrôleur distant (ControllerUri).

<LgSuggestBox Label="#City" Items="_cities" @bind-Value="_model.City" />

Espace de noms : Lagoon.UI.Components
Hérite de : LgSuggestBoxBase<string> → LgTextBox → LgInputRenderBase<string> → LgInputBase<string> → LgAriaComponentBase → LgComponentBase
Interfaces : ILgDropDownComponent
Package NuGet : Lagoon.UI

Suggestion ou sélection ?

LgSuggestBox accepte une valeur libre ; les suggestions ne sont qu'une aide à la saisie. Pour contraindre la valeur à une liste fermée, utilisez LgSelect.

Utilisation

Démonstration

Essayez ce composant dans le showcase Lagoon.

Suggestions locales

Items fournit la liste des valeurs proposées. Le texte saisi filtre la liste (mode Contains par défaut) et le menu ne s'ouvre que s'il y a des résultats.

CityPage.razor
<LgSuggestBox Label="#City"
              Items="_cities"
              Placeholder="#TypeCityName"
              @bind-Value="_model.City" />

CityPage.razor.cs
public partial class CityPage : LgPage
{
    // Valeurs suggérées : la saisie reste libre, la liste n'est qu'une aide.
    private readonly List<string> _cities = new() { "Paris", "Lyon", "Marseille", "Toulouse", "Nantes" };

    private readonly CityVm _model = new();

    private sealed class CityVm
    {
        public string City { get; set; }
    }
}

Suggestions distantes avec `ControllerUri`

Pour une liste volumineuse ou dépendante du serveur, ControllerUri pointe vers une action queryable : le composant poste automatiquement une requête de données vers {ControllerUri}/$qd avec le texte saisi, le filtre et la pagination.

SupplierPage.razor
<LgSuggestBox Label="#Supplier"
              ControllerUri="api/suppliers/names"
              MinSearchCharacter="2"
              SeeAllEnabled="true"
              @bind-Value="_model.Supplier" />

SupplierPage.razor.cs
public partial class SupplierPage : LgPage
{
    private readonly SupplierVm _model = new();

    private sealed class SupplierVm
    {
        public string Supplier { get; set; }
    }
}

Contrat des endpoints

ControllerUri pointe vers une action queryable. Le composant appelle {ControllerUri}/$qd en POST via le chargeur distant Lagoon ; l'action source reste exposée en GET et décorée avec [Queryable].

GET + POST `$qd` — Recherche de suggestions (`ControllerUri`)

SuppliersController.cs
[ApiController]
[Route("api/suppliers")]
public class SuppliersController : LgControllerBase
{
    private readonly ApplicationDbContext _db;

    public SuppliersController(ApplicationDbContext db)
    {
        _db = db;
    }

    [HttpGet("names")]
    [Queryable]
    public IQueryable<string> GetNames()
    {
        // Retourne IQueryable<string> pour laisser [Queryable] appliquer le texte
        // recherché, la pagination et le tri envoyés par le composant.
        return _db.Suppliers.Select(s => s.Name);
    }
}

Filtrage, collation et nombre de résultats

FilterTextSearchMode, TextFilterCollation, MinSearchCharacter et MaxItemsInView ajustent le comportement de recherche. HighlightText surligne le texte trouvé dans les résultats et SeeAllEnabled ajoute un bouton « Voir tout » quand plus de résultats sont disponibles que MaxItemsInView.

ProductPage.razor
<LgSuggestBox Label="#Product"
              Items="_products"
              FilterTextSearchMode="FilterTextSearchMode.StartsWith"
              TextFilterCollation="CollationType.IgnoreCaseAndAccent"
              MinSearchCharacter="1"
              MaxItemsInView="10"
              HighlightText="true"
              @bind-Value="_model.Product" />

ProductPage.razor.cs
public partial class ProductPage : LgPage
{
    private readonly List<string> _products = new() { "Écrou M6", "Écrou M8", "Vis M6", "Vis M8", "Rondelle M6" };

    private readonly ProductVm _model = new();

    private sealed class ProductVm
    {
        public string Product { get; set; }
    }
}

Personnaliser le rendu des suggestions

ItemContent remplace le rendu par défaut d'une suggestion. Avec HighlightText, ajoutez la classe highlightable sur l'élément qui contient le texte à surligner.

AccountPage.razor
<LgSuggestBox Label="#Account" Items="_accounts" HighlightText="true" @bind-Value="_model.Account">
    <ItemContent Context="item">
        <LgIcon IconName="@IconNames.All.PersonFill" />
        <span class="highlightable">@item</span>
    </ItemContent>
</LgSuggestBox>

AccountPage.razor.cs
public partial class AccountPage : LgPage
{
    private readonly List<string> _accounts = new() { "compta-fournisseurs", "compta-clients", "banque" };

    private readonly AccountVm _model = new();

    private sealed class AccountVm
    {
        public string Account { get; set; }
    }
}

Propriétés

Toutes les propriétés [Parameter] du composant, y compris celles héritées.

Nom	Type	Défaut	Déclaré dans	Description
`ControllerUri`	`string`	`null`	`LgSuggestBoxBase<TItem>`	URI du contrôleur utilisé pour charger les suggestions à distance.
`DropDownMaxHeight`	`int`	`-1`	`LgSuggestBoxBase<TItem>`	Hauteur maximale du menu déroulant, en pixels. `-1` utilise l'espace disponible.
`FilterTextSearchMode`	`FilterTextSearchMode`	`Contains`	`LgSuggestBoxBase<TItem>`	Mode de comparaison utilisé pour filtrer le texte recherché.
`HighlightText`	`bool`	`false`	`LgSuggestBoxBase<TItem>`	Surligne le texte trouvé dans les suggestions affichées.
`ItemContent`	`RenderFragment<string>`	`null`	`LgSuggestBoxBase<TItem>`	Template personnalisé pour rendre une suggestion.
`Items`	`IEnumerable<string>`	`null`	`LgSuggestBoxBase<TItem>`	Source locale des suggestions.
`MaxItemsInView`	`int`	`8`	`LgSuggestBoxBase<TItem>`	Nombre maximum de suggestions affichées. `0` affiche tous les résultats.
`MinSearchCharacter`	`int`	`0`	`LgSuggestBoxBase<TItem>`	Nombre minimal de caractères avant de lancer la recherche.
`SeeAllEnabled`	`bool`	`false`	`LgSuggestBoxBase<TItem>`	Affiche un bouton « Voir tout » quand plus de résultats sont disponibles que `MaxItemsInView`.
`TextFilterCollation`	`CollationType?`	`null`	`LgSuggestBoxBase<TItem>`	Sensibilité à la casse et aux accents. Si `null`, la configuration de comportement de l'application s'applique.
`AllowResize`	`bool`	`false`	`LgTextBox`	Autorise le redimensionnement lorsque `TextMode` vaut `TextBoxMode.Multiline`.
`AutoComplete`	`bool`	`false`	`LgTextBox`	Active l'autocomplétion du navigateur si `true` ; sinon l'attribut `autocomplete="off"` est rendu.
`AutoUnmask`	`bool`	`false`	`LgTextBox`	Retourne la valeur sans le masque lorsque `InputMask` est utilisé.
`ClearIncomplete`	`bool`	`false`	`LgTextBox`	Vide la valeur si le masque de saisie est incomplet.
`DataList`	`List<string>`	`null`	`LgTextBox`	Liste de valeurs utilisée pour rendre un `datalist` associé à l'entrée.
`InputMask`	`string`	`null`	`LgTextBox`	Masque de saisie appliqué au champ texte.
`InputMaskKind`	`InputMaskKind`	`None`	`LgTextBox`	Type de masque de saisie.
`InputMaskPlaceholder`	`string`	`null`	`LgTextBox`	Caractère remplissant les positions vides du masque de saisie (par exemple `#` avec le masque `99-99-99-99-99` affiche `##-##-##-##-##`). À ne pas confondre avec `Placeholder`. Sans valeur, le caractère par défaut du masque (`_`) est conservé.
`MaxLength`	`int?`	`null`	`LgTextBox`	Nombre maximal de caractères.
`MaxRows`	`int?`	`null`	`LgTextBox`	Nombre maximal de lignes lorsque `TextMode` vaut `TextBoxMode.Multiline`.
`MinRows`	`int?`	`null`	`LgTextBox`	Nombre minimal de lignes lorsque `TextMode` vaut `TextBoxMode.Multiline`.
`OnChangeDisabled`	`bool`	`false`	`LgTextBox`	Désactive le gestionnaire `onchange` natif du champ.
`OnChangingAsync`	`Func<ChangingEventArgs<string>, Task>`	`null`	`LgTextBox`	Callback appelé avant le changement de valeur ; le changement peut y être annulé.
`OnFocus`	`EventCallback<FocusEventArgs>`	—	`LgTextBox`	Callback appelé à la prise de focus (déclenche aussi la recherche initiale).
`OnInput`	`EventCallback<ChangeEventArgs>`	—	`LgTextBox`	Callback appelé à la saisie (`oninput`), utilisé par la recherche.
`OnKeyUp`	`EventCallback<KeyboardEventArgs>`	—	`LgTextBox`	Callback appelé au relâchement d'une touche.
`Placeholder`	`string`	`null`	`LgTextBox`	Texte indicatif affiché quand le champ est vide. Distinct de `InputMaskPlaceholder`.
`Rows`	`int?`	`null`	`LgTextBox`	Nombre de lignes lorsque `TextMode` vaut `TextBoxMode.Multiline`.
`TextMode`	`TextBoxMode?`	`null`	`LgTextBox`	Mode du champ texte. `null` rend un champ texte simple.
`Prefix`	`string`	`null`	`LgInputRenderBase`	Préfixe affiché dans le champ.
`PrefixType`	`InputLabelType`	`Text`	`LgInputRenderBase`	Nature du préfixe.
`Suffix`	`string`	`null`	`LgInputRenderBase`	Suffixe affiché dans le champ.
`SuffixType`	`InputLabelType`	`Text`	`LgInputRenderBase`	Nature du suffixe.
`AdditionalAttributes`	`IReadOnlyDictionary<string, object>`	`null`	`LgInputBase`	Attributs HTML additionnels appliqués à l'élément rendu.
`AutoFocus`	`bool`	`false`	`LgInputBase`	Donne le focus au champ lors du premier rendu.
`ConfirmationMessage`	`string`	`null`	`LgInputBase`	Message de confirmation affiché avant d'appliquer un changement de valeur.
`Container`	`IInputContainer<string>`	`null`	`LgInputBase`	Usage interne : rattache une cellule de GridView au champ.
`CssClass`	`string`	`null`	`LgInputBase`	Classes CSS additionnelles.
`Disabled`	`bool`	`false`	`LgInputBase`	Désactive le champ.
`DisplayName`	`string`	`null`	`LgInputBase`	Nom du champ utilisé dans les messages d'erreur.
`HideValidationMessage`	`bool`	`false`	`LgInputBase`	Masque le message de validation sous le champ.
`Label`	`string`	`null`	`LgInputBase`	Libellé du champ.
`LabelContent`	`RenderFragment`	`null`	`LgInputBase`	Contenu personnalisé de la zone de libellé.
`OnChange`	`EventCallback<ChangeEventArgs>`	—	`LgInputBase`	Callback appelé après le changement de valeur.
`OnReset`	`EventCallback<ChangeEventArgs>`	—	`LgInputBase`	Callback appelé quand le champ est réinitialisé par le bouton d'effacement.
`PolicyEdit`	`string`	`null`	`LgInputBase`	Policy requise pour modifier le champ.
`PolicyVisible`	`string`	`null`	`LgInputBase`	Policy requise pour afficher le champ.
`ReadOnly`	`bool`	`false`	`LgInputBase`	Affiche le champ en lecture seule.
`Required`	`bool?`	`null`	`LgInputBase`	Champ obligatoire. Si `null`, déduit de l'attribut `[Required]` de la propriété liée.
`ResetButton`	`bool?`	`null`	`LgInputBase`	Affiche le bouton d'effacement. Si `null`, la configuration de comportement de l'application s'applique.
`ResetText`	`string`	`null`	`LgInputBase`	Texte du bouton d'effacement.
`ResetTextAriaLabel`	`string`	`null`	`LgInputBase`	Libellé accessible (`aria-label`) du bouton d'effacement.
`Tooltip`	`string`	`null`	`LgInputBase`	Bulle d'aide.
`TooltipIsHtml`	`bool`	`false`	`LgInputBase`	Indique si le contenu du `Tooltip` est au format HTML (sinon texte brut).
`Value`	`string`	`null`	`LgInputBase`	Valeur liée (`@bind-Value`).
`ValueChanged`	`EventCallback<string>`	—	`LgInputBase`	Callback de mise à jour de la valeur liée.
`ValueExpression`	`Expression<Func<string>>`	—	`LgInputBase`	Expression identifiant la propriété liée.
`AriaLabel`	`string`	`null`	`LgAriaComponentBase`	Valeur de l'attribut `aria-label`.
`AriaLabelledBy`	`string`	`null`	`LgAriaComponentBase`	Valeur de l'attribut `aria-labelledby`.

Paramètres en cascade

LgSuggestBox consomme aussi des paramètres fournis automatiquement par des composants ancêtres (vous n'avez pas à les définir) : ParentAuthorizeView (LgAuthorizeView) et le contexte d'édition d'un LgEditForm parent.

Événements

Événement	Type	Description
`OnChangingAsync`	`Func<ChangingEventArgs<string>, Task>`	Avant le changement de valeur ; `args.Cancel = true` annule le changement.
`OnChange`	`EventCallback<ChangeEventArgs>`	Après le changement de valeur (saisie validée ou suggestion sélectionnée).
`OnInput`	`EventCallback<ChangeEventArgs>`	À la saisie ; c'est aussi l'événement qui déclenche la recherche.
`OnKeyUp`	`EventCallback<KeyboardEventArgs>`	Au relâchement d'une touche.
`OnFocus`	`EventCallback<FocusEventArgs>`	À la prise de focus (déclenche la recherche initiale).
`OnReset`	`EventCallback<ChangeEventArgs>`	À la réinitialisation par le bouton d'effacement.

Énumérations associées

Les énumérations de la famille suggest (FilterTextSearchMode, CollationType, InputMaskKind, TextBoxMode) sont documentées sur la page LgNavigationBox, qui partage la même base LgSuggestBoxBase.

Bonnes pratiques / accessibilité

Fixez MinSearchCharacter à 2 ou 3 avec ControllerUri pour limiter les requêtes serveur sur les premiers caractères.
La valeur liée reste une saisie libre : validez-la côté modèle si seules les valeurs suggérées sont acceptables — ou utilisez LgSelect pour une liste fermée.

Référence complète

Tous les paramètres (hérités compris) : Référence API — LgSuggestBox.

Composants liés

LgSelect — sélection dans une liste fermée.
LgTextBox — champ texte de base.
LgNavigationBox — recherche de navigation basée sur la même famille suggest.

Utilisation​

Démonstration​

Suggestions locales​

Suggestions distantes avec ControllerUri​

Contrat des endpoints​

GET + POST $qd — Recherche de suggestions (ControllerUri)​

Filtrage, collation et nombre de résultats​

Personnaliser le rendu des suggestions​

Propriétés​

Événements​

Énumérations associées​

Bonnes pratiques / accessibilité​

Composants liés​