fluentui-blazor

Fluent UI Blazor — 使用指南

本技能介绍如何在 Blazor 应用中正确使用 Microsoft.FluentUI.AspNetCore.Components（版本 4）NuGet 包。

关键规则

1. 无需手动添加 <script> 或 <link> 标签

该库通过 Blazor 的静态 Web 资产和 JS 初始化器自动加载所有 CSS 和 JS。绝不要告诉用户为核心库添加 <script> 或 <link> 标签。

2. 基于服务的组件必须使用提供程序

这些提供程序组件必须添加到根布局（例如 MainLayout.razor）中，对应的服务才能正常工作。否则，服务调用会静默失败（没有错误，也没有 UI）。

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

3. 在 Program.cs 中注册服务

builder.Services.AddFluentUIComponents();

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

ServiceLifetime 规则：

• ServiceLifetime.Scoped — 适用于 Blazor Server / Interactive（默认）
• ServiceLifetime.Singleton — 适用于 Blazor WebAssembly 独立模式
• ServiceLifetime.Transient — 会抛出 NotSupportedException

4. 图标需要单独的 NuGet 包

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

配合 @using 别名使用：

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

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

模式：Icons.[Variant].[Size].[Name]

• 变体：Regular、Filled
• 尺寸：Size12、Size16、Size20、Size24、Size28、Size32、Size48

自定义图像：Icon.FromImageUrl("/path/to/image.png")

绝不要使用基于字符串的图标名称 — 图标是强类型类。

5. 列表组件的绑定模型

FluentSelect<TOption>、FluentCombobox<TOption>、FluentListbox<TOption> 和 FluentAutocomplete<TOption> 的工作方式与 <InputSelect> 不同。它们使用：

• Items — 数据源（IEnumerable<TOption>）
• OptionText — Func<TOption, string?>，用于提取显示文本
• OptionValue — Func<TOption, string?>，用于提取值字符串
• SelectedOption / SelectedOptionChanged — 用于单选绑定
• SelectedOptions / SelectedOptionsChanged — 用于多选绑定

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

不是这样（错误模式）：

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

6. FluentAutocomplete 的具体说明

• 使用 ValueText（不是 Value — 它已过时）作为搜索输入文本
• OnOptionsSearch 是筛选选项所需的回调
• 默认为 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. 对话框服务模式

不要切换 <FluentDialog> 标签的可见性。 服务模式是：

1. 创建一个实现 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. 通过 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;
    }
}

对于便捷对话框：

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

8. 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");

FluentToastProvider 参数：Position（默认 TopRight）、Timeout（默认 7000ms）、MaxToastCount（默认 4）。

9. 设计令牌和主题仅在渲染后生效

设计令牌依赖 JS 互操作。绝不要在 OnInitialized 中设置它们 — 请使用 OnAfterRenderAsync。

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

10. FluentEditForm 与 EditForm

FluentEditForm 仅在 FluentWizard 步骤内（逐步验证）需要。对于常规表单，请使用标准 EditForm 配合 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>

请使用 FluentValidationMessage 和 FluentValidationSummary 代替标准 Blazor 验证组件，以获得 Fluent 样式。

参考文件

有关特定主题的详细指导，请参阅：

• 安装和配置
• 布局和导航
• 数据网格
• 主题