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();

// 或带配置：
builder.Services.AddFluentUIComponents(options =>
{
    options.UseTooltipServiceProvider = true;  // 默认：true
    options.ServiceLifetime = ServiceLifetime.Scoped; // 默认
});

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" />

不要像这样（错误模式）：

@* 错误——不要使用 InputSelect 模式 *@
<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 样式。

参考文件

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

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