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. トースト通知

[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 interop に依存しています。OnInitialized で設定しないでください — OnAfterRenderAsync を使用してください。

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

10. FluentEditForm と EditForm

FluentEditForm は FluentWizard のステップ内（ステップごとの検証）でのみ必要です。通常のフォームには、Fluent フォームコンポーネントを備えた標準の EditForm を使用してください:

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

Fluent のスタイル設定には、標準の Blazor 検証コンポーネントの代わりに FluentValidationMessage と FluentValidationSummary を使用してください。

参照ファイル

特定のトピックに関する詳細なガイダンスについては、次を参照してください:

• セットアップと構成
• レイアウトとナビゲーション
• データグリッド
• テーマ設定