Guia de Uso do Fluent UI Blazor

Esta habilidade ensina como usar corretamente o pacote NuGet Microsoft.FluentUI.AspNetCore.Components (versão 4) em aplicações Blazor.

Regras Críticas

1. Não são necessárias tags manuais <script> ou <link>

A biblioteca carrega automaticamente todo o CSS e JS através dos ativos web estáticos do Blazor e inicializadores de JS. Nunca diga aos usuários para adicionar tags <script> ou <link> para a biblioteca principal.

2. Providers são obrigatórios para componentes baseados em serviços

Esses componentes provedores DEVEM ser adicionados ao layout raiz (por exemplo, MainLayout.razor) para que seus serviços correspondentes funcionem. Sem eles, as chamadas de serviço falham silenciosamente (sem erro, sem UI).

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

3. Registro de serviço em Program.cs

builder.Services.AddFluentUIComponents();

// Or with configuration:
builder.Services.AddFluentUIComponents(options =>
{
    options.UseTooltipServiceProvider = true;  // default: true
    options.ServiceLifetime = ServiceLifetime.Scoped; // default
});

Regras de ServiceLifetime:

• ServiceLifetime.Scoped — para Blazor Server / Interativo (padrão)
• ServiceLifetime.Singleton — para Blazor WebAssembly standalone
• ServiceLifetime.Transient — lança NotSupportedException

4. Ícones requerem um pacote NuGet separado

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

Uso com um alias @using:

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

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

Padrão: Icons.[Variant].[Size].[Name]

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

Imagem personalizada: Icon.FromImageUrl("/path/to/image.png")

Nunca use nomes de ícones baseados em strings — ícones são classes fortemente tipadas.

5. Modelo de vinculação do componente List

FluentSelect<TOption>, FluentCombobox<TOption>, FluentListbox<TOption> e FluentAutocomplete<TOption> NÃO funcionam como <InputSelect>. Eles usam:

• Items — a fonte de dados (IEnumerable<TOption>)
• OptionText — Func<TOption, string?> para extrair o texto de exibição
• OptionValue — Func<TOption, string?> para extrair o valor como string
• SelectedOption / SelectedOptionChanged — para vinculação de seleção única
• SelectedOptions / SelectedOptionsChanged — para vinculação de multisseleção

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

NÃO assim (padrão incorreto):

@* WRONG — do not use InputSelect pattern *@
<FluentSelect @bind-Value="@selectedValue">
    <option value="1">One</option>
</FluentSelect>

6. Específicos do FluentAutocomplete

• Use ValueText (NÃO Value — está obsoleto) para o texto de entrada de pesquisa
• OnOptionsSearch é o callback obrigatório para filtrar opções
• O padrão é 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. Padrão do serviço de Diálogo

NÃO alterne a visibilidade de tags <FluentDialog>. O padrão do serviço é:

1. Crie um componente de conteúdo implementando 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. Mostre o diálogo via IDialogService:

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

private async Task ShowEditDialog()
{
    var dialog = await DialogService.ShowDialogAsync<EditPersonDialog, Person>(
        person,

…