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

[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 vs 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 を使用してください。

リファレンスファイル

特定のトピックについて詳細なガイダンスについては、以下をご覧ください:

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