Guide d'utilisation Fluent UI Blazor — Consommateurs

Cette compétence enseigne comment utiliser correctement le package NuGet Microsoft.FluentUI.AspNetCore.Components (version 4) dans les applications Blazor.

Règles critiques

1. Aucune balise <script> ou <link> manuelle requise

La bibliothèque charge automatiquement tous les CSS et JS via les static web assets et les JS initializers de Blazor. Ne dites jamais aux utilisateurs d'ajouter des balises <script> ou <link> pour la bibliothèque principale.

2. Les providers sont obligatoires pour les composants basés sur les services

Ces composants provider DOIVENT être ajoutés à la mise en page racine (par ex. MainLayout.razor) pour que leurs services correspondants fonctionnent. Sans eux, les appels de service échouent silencieusement (pas d'erreur, pas d'interface utilisateur).

<FluentToastProvider />
<FluentDialogProvider />
<FluentMessageBarProvider />
<FluentTooltipProvider />
<FluentKeyCodeProvider />

3. Enregistrement des services dans Program.cs

builder.Services.AddFluentUIComponents();

// Ou avec configuration :
builder.Services.AddFluentUIComponents(options =>
{
    options.UseTooltipServiceProvider = true;  // par défaut : true
    options.ServiceLifetime = ServiceLifetime.Scoped; // par défaut
});

Règles ServiceLifetime :

• ServiceLifetime.Scoped — pour Blazor Server / Interactive (par défaut)
• ServiceLifetime.Singleton — pour Blazor WebAssembly autonome
• ServiceLifetime.Transient — lève une NotSupportedException

4. Les icônes nécessitent un package NuGet séparé

dotnet add package Microsoft.FluentUI.AspNetCore.Components.Icons

Utilisation avec un alias @using :

@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons

<FluentIcon Value="@(Icons.Regular.Size24.Save)" />
<FluentIcon Value="@(Icons.Filled.Size20.Delete)" Color="@Color.Error" />

Motif : Icons.[Variant].[Size].[Name]

• Variantes : Regular, Filled
• Tailles : Size12, Size16, Size20, Size24, Size28, Size32, Size48

Image personnalisée : Icon.FromImageUrl("/path/to/image.png")

Ne jamais utiliser de noms d'icônes basés sur des chaînes — les icônes sont des classes fortement typées.

5. Modèle de liaison du composant List

FluentSelect<TOption>, FluentCombobox<TOption>, FluentListbox<TOption> et FluentAutocomplete<TOption> ne fonctionnent PAS comme <InputSelect>. Ils utilisent :

• Items — la source de données (IEnumerable<TOption>)
• OptionText — Func<TOption, string?> pour extraire le texte affiché
• OptionValue — Func<TOption, string?> pour extraire la valeur chaîne
• SelectedOption / SelectedOptionChanged — pour la liaison de sélection simple
• SelectedOptions / SelectedOptionsChanged — pour la liaison de sélection multiple

<FluentSelect Items="@countries"
              OptionText="@(c => c.Name)"
              OptionValue="@(c => c.Code)"
              @bind-SelectedOption="@selectedCountry"
              Label="Country" />

PAS ainsi (motif incorrect) :

@* INCORRECT — n'utilisez pas le motif InputSelect *@
<FluentSelect @bind-Value="@selectedValue">
    <option value="1">One</option>
</FluentSelect>

6. Spécificités de FluentAutocomplete

• Utilisez ValueText (PAS Value — c'est obsolète) pour le texte de saisie de recherche
• OnOptionsSearch est le callback requis pour filtrer les options
• La valeur par défaut est Multiple="true"

<FluentAutocomplete TOption="Person"
                    OnOptionsSearch="@OnSearch"
                    OptionText="@(p => p.FullName)"
                    @bind-SelectedOptions="@selectedPeople"
                    Label="Search people" />

@code {
    private void OnSearch(OptionsSearchEventArgs<Person> args)
    {
        args.Items = allPeople.Where(p =>
            p.FullName.Contains(args.Text, StringComparison.OrdinalIgnoreCase));
    }
}

7. Motif du service Dialog

NE BASCULEZ PAS la visibilité des balises <FluentDialog>. Le motif du service est :

1. Créez un composant de contenu implémentant IDialogContentComponent<TData> :

public partial class EditPersonDialog : IDialogContentComponent<Person>
{
    [Parameter] public Person Content { get; set; } = default!;

    [CascadingParameter] public FluentDialog Dialog { get; set; } = default!;

    private async Task SaveAsync()
    {
        await Dialog.CloseAsync(Content);
    }

    private async Task CancelAsync()
    {
        await Dialog.CancelAsync();
    }
}

2. Affichez la boîte de dialogue via IDialogService :

[Inject] private IDialogService DialogService { get; set; } = default!;

private async Task ShowEditDialog()
{
    var dialog = await DialogService.ShowDialogAsync<EditPersonDialog, Person>(
        person,
        new DialogParameters
        {
            Title = "Edit Person",
            PrimaryAction = "Save",
            SecondaryAction = "Cancel",
            Width = "500px",
            PreventDismissOnOverlayClick = true,
        });

    var result = await dialog.Result;
    if (!result.Cancelled)
    {
        var updatedPerson = result.Data as Person;
    }
}

Pour les boîtes de dialogue de commodité :

await DialogService.ShowConfirmationAsync("Are you sure?", "Yes", "No");
await DialogService.ShowSuccessAsync("Done!");
await DialogService.ShowErrorAsync("Something went wrong.");

8. Notifications Toast

[Inject] private IToastService ToastService { get; set; } = default!;

ToastService.ShowSuccess("Item saved successfully");
ToastService.ShowError("Failed to save");
ToastService.ShowWarning("Check your input");
ToastService.ShowInfo("New update available");

Paramètres FluentToastProvider : Position (par défaut TopRight), Timeout (par défaut 7000ms), MaxToastCount (par défaut 4).

9. Les design tokens et thèmes ne fonctionnent qu'après le rendu

Les design tokens dépendent de JS interop. Ne les réglez jamais dans OnInitialized — utilisez OnAfterRenderAsync.

<FluentDesignTheme Mode="DesignThemeModes.System"
                   OfficeColor="OfficeColor.Teams"
                   StorageName="mytheme" />

10. FluentEditForm vs EditForm

FluentEditForm n'est nécessaire qu'à l'intérieur des étapes FluentWizard (validation par étape). Pour les formulaires réguliers, utilisez le standard EditForm avec les composants de formulaire Fluent :

<EditForm Model="@model" OnValidSubmit="HandleSubmit">
    <DataAnnotationsValidator />
    <FluentTextField @bind-Value="@model.Name" Label="Name" Required />
    <FluentSelect Items="@options"
                  OptionText="@(o => o.Label)"
                  @bind-SelectedOption="@model.Category"
                  Label="Category" />
    <FluentValidationSummary />
    <FluentButton Type="ButtonType.Submit" Appearance="Appearance.Accent">Save</FluentButton>
</EditForm>

Utilisez FluentValidationMessage et FluentValidationSummary au lieu des composants de validation Blazor standard pour le style Fluent.

Fichiers de référence

Pour des conseils détaillés sur des sujets spécifiques, voir :

• Setup and configuration
• Layout and navigation
• Data grid
• Theming