Fluent UI Blazor 使用指南：Microsoft.FluentUI.AspNetCore.Components 4 版本完整教程

fluentui-blazor by github/awesome-copilot

7,400 周安装量

26,700 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/github/awesome-copilot --skill 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 中注册服务

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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> 标签的可见性。 服务模式如下：

创建一个实现 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.");

[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 样式。

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

2026 年 2 月 18 日

🇺🇸English

Fluent UI Blazor — Consumer Usage Guide

This skill teaches how to correctly use the Microsoft.FluentUI.AspNetCore.Components (version 4) NuGet package in Blazor applications.

Critical Rules

1. No manual `<script>` or `<link>` tags needed

The library auto-loads all CSS and JS via Blazor's static web assets and JS initializers. Never tell users to add<script> or <link> tags for the core library.

2. Providers are mandatory for service-based components

These provider components MUST be added to the root layout (e.g. MainLayout.razor) for their corresponding services to work. Without them, service calls fail silently (no error, no UI).

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

3. Service registration in Program.cs

builder.Services.AddFluentUIComponents();

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

ServiceLifetime rules:

ServiceLifetime.Scoped — for Blazor Server / Interactive (default)
ServiceLifetime.Singleton — for Blazor WebAssembly standalone
ServiceLifetime.Transient — throwsNotSupportedException

4. Icons require a separate NuGet package

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

Usage with a @using alias:

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

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

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

Variants: Regular, Filled
Sizes: Size12, Size16, Size20, Size24, Size28, Size32, Size48

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

Never use string-based icon names — icons are strongly-typed classes.

5. List component binding model

FluentSelect<TOption>, FluentCombobox<TOption>, FluentListbox<TOption>, and FluentAutocomplete<TOption> do NOT work like <InputSelect>. They use:

Items — the data source (IEnumerable<TOption>)
OptionText — Func<TOption, string?> to extract display text
OptionValue — Func<TOption, string?> to extract the value string
SelectedOption / SelectedOptionChanged — for single selection binding
SelectedOptions / — for multi-selection binding

NOT like this (wrong pattern):

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

6. FluentAutocomplete specifics

Use ValueText (NOT Value — it's obsolete) for the search input text
OnOptionsSearch is the required callback to filter options
Default is 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. Dialog service pattern

Do NOT toggle visibility of<FluentDialog> tags. The service pattern is:

Create a content component implementing 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. Show the dialog 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;
    }
}

For convenience dialogs:

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

8. Toast notifications

[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 parameters: Position (default TopRight), Timeout (default 7000ms), MaxToastCount (default 4).

9. Design tokens and themes work only after render

Design tokens rely on JS interop. Never set them inOnInitialized — use OnAfterRenderAsync.

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

10. FluentEditForm vs EditForm

FluentEditForm is only needed inside FluentWizard steps (per-step validation). For regular forms, use standard EditForm with Fluent form components:

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

Use FluentValidationMessage and FluentValidationSummary instead of standard Blazor validation components for Fluent styling.

Reference files

For detailed guidance on specific topics, see:

Weekly Installs

7.4K

Repository

github/awesome-copilot

GitHub Stars

26.7K

First Seen

Feb 18, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex7.3K

gemini-cli7.3K

opencode7.2K

github-copilot7.2K

cursor7.2K

kimi-cli7.2K

SelectedOptionsChanged

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

Fluent UI Blazor 使用指南：Microsoft.FluentUI.AspNetCore.Components 4 版本完整教程

🇨🇳中文介绍

Fluent UI Blazor — 使用指南

关键规则

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

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

3. 在 Program.cs 中注册服务

相关 Skills

4. 图标需要单独的 NuGet 包

5. 列表组件绑定模型

6. FluentAutocomplete 特定规则

7. 对话框服务模式

8. 通知提示

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

10. FluentEditForm 与 EditForm

参考文件

🇺🇸English

Fluent UI Blazor — Consumer Usage Guide

Critical Rules

1. No manual `<script>` or `<link>` tags needed

2. Providers are mandatory for service-based components

3. Service registration in Program.cs

4. Icons require a separate NuGet package

5. List component binding model

6. FluentAutocomplete specifics

7. Dialog service pattern

8. Toast notifications

9. Design tokens and themes work only after render

10. FluentEditForm vs EditForm

Reference files

Fluent UI Blazor 使用指南：Microsoft.FluentUI.AspNetCore.Components 4 版本完整教程

🇨🇳中文介绍

Fluent UI Blazor — 使用指南

关键规则

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

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

3. 在 Program.cs 中注册服务

相关 Skills

4. 图标需要单独的 NuGet 包

5. 列表组件绑定模型

6. FluentAutocomplete 特定规则

7. 对话框服务模式

8. 通知提示

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

10. FluentEditForm 与 EditForm

参考文件

🇺🇸English

Fluent UI Blazor — Consumer Usage Guide

Critical Rules

1. No manual <script> or <link> tags needed

2. Providers are mandatory for service-based components

3. Service registration in Program.cs

4. Icons require a separate NuGet package

5. List component binding model

6. FluentAutocomplete specifics

7. Dialog service pattern

8. Toast notifications

9. Design tokens and themes work only after render

10. FluentEditForm vs EditForm

Reference files

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

1. No manual `<script>` or `<link>` tags needed