syncfusion-blazor-notifications

Syncfusion Blazor Notifications の実装

Syncfusion Blazor Notifications の Toast、Message、Skeleton コンポーネントを実装するための包括的なスキルです。これらのコンポーネントは、一時的な通知、インラインメッセージ、コンテンツの読み込み状態など、ユーザーへのフィードバックに欠かせない仕組みを提供します。

コンポーネントの概要

SfToast

フィードバックを提供するために一時的に表示される、軽量で操作を妨げない通知ポップアップです。位置、アニメーション、アクションボタン、テンプレートに対応しています。

主な機能:

• 位置を設定可能（左上、中央上、右上、左下、中央下、右下）
• 表示／非表示アニメーションのタイミングをカスタマイズ可能
• タイムアウトとプログレスバーによる自動非表示
• ユーザーが操作できるアクションボタン
• カスタムコンテンツ用のテンプレートに対応
• イベントコールバック（OnOpen、OnClose、OnClick）
• Toast の複数表示（新しいものを上または下に表示）

SfMessage

さまざまな重大度レベルのコンテキストに応じたフィードバックメッセージを表示する、インラインのアラートコンポーネントです。

主な機能:

• 重大度の種類（Normal、Info、Success、Warning、Error）に応じた色分けスタイル
• さまざまな見た目のスタイル（Text、Outlined、Filled）
• 重大度レベルに対応する組み込みアイコン
• メッセージを閉じられるオプションの閉じるボタン
• コンテンツの配置（左、中央、右）
• 表示制御と閉じるイベントの処理
• カスタム CSS スタイルに対応

SfSkeleton

コンテンツの読み込み中であることを示す、アニメーション付きの図形を表示するローディングプレースホルダーコンポーネントです。

主な機能:

• コンテンツの種類に応じた図形（Circle、Square、Rectangle、Text）
• 視覚的なフィードバックを提供するシマー効果（Pulse、Wave、Fade、None）
• サイズ（幅、高さ）を設定可能
• スクリーンリーダー向けのアクセシビリティラベル
• 表示／非表示の切り替え
• スタイル設定用の CSS カスタマイズ

クイックスタート

Toast - 基本的な例

@page "/toast-demo"
@using Syncfusion.Blazor.Notifications
@using Syncfusion.Blazor.Buttons

<SfButton @onclick="ShowToast">Show Toast</SfButton>

<SfToast @ref="ToastObj" Title="Notification" Content="Your changes have been saved successfully!" />

@code {
    SfToast ToastObj;

    private async Task ShowToast()
    {
        await ToastObj.ShowAsync();
    }
}

Message - 基本的な例

@page "/message-demo"
@using Syncfusion.Blazor.Notifications

<SfMessage Severity="MessageSeverity.Success" ShowIcon="true" ShowCloseIcon="true">
    Your profile has been updated successfully!
</SfMessage>

<SfMessage Severity="MessageSeverity.Warning" ShowIcon="true">
    Your session will expire in 5 minutes.
</SfMessage>

<SfMessage Severity="MessageSeverity.Error" ShowIcon="true" ShowCloseIcon="true">
    Failed to save changes. Please try again.
</SfMessage>

Skeleton - 基本的な例

@page "/skeleton-demo"
@using Syncfusion.Blazor.Notifications

<div class="skeleton-container">
    <SfSkeleton Shape="SkeletonType.Circle" Width="60px" Height="60px" />
    <div class="skeleton-text">
        <SfSkeleton Shape="SkeletonType.Text" Width="80%" />
        <SfSkeleton Shape="SkeletonType.Text" Width="60%" />
    </div>
</div>

<style>
    .skeleton-container {
        display: flex;
        gap: 16px;
        padding: 16px;
    }
    .skeleton-text {
        flex: 1;
        display: flex;
        flex-direction: column;
        gap: 8px;
    }
</style>

ドキュメントとナビゲーションガイド

Toast コンポーネント

Toast を使い始める

📄 読む: references/toast-getting-started.md

• インストールと NuGet パッケージのセットアップ
• Program.cs でのサービス登録
• 基本的な Toast の実装
• プログラムによる Toast の表示と非表示
• 位置設定の基本
• シンプルな成功／エラー通知

Toast の高度な機能

📄 読む: references/toast-features.md

• 位置と配置のオプション（事前定義された 9 種類の位置）
• アニメーション設定（効果と時間を指定した表示／非表示）
• タイムアウトと延長タイムアウトによる自動非表示
• プログレスバーの表示と方向
• イベントハンドラー付きアクションボタン
• タイトルとコンテンツのテンプレート
• 複数の Toast の管理と表示順
• イベントコールバック（OnOpen、OnClose、OnClick、BeforeOpen、BeforeClose）
• RTL（右から左）への対応
• 幅、高さ、CSS スタイルのカスタマイズ
• ターゲットコンテナーの指定

Message コンポーネント

Message の実装

📄 読む: references/message-implementation.md

• Message コンポーネントの使い始め方
• 重大度の種類（Normal、Info、Success、Warning、Error）
• バリアントスタイル（Text、Outlined、Filled）
• アイコンの設定（組み込みアイコンとカスタムアイコン）
• 閉じるアイコンと閉じる処理
• コンテンツ配置のオプション
• 表示制御と双方向バインディング
• 閉じるイベントの処理
• ChildContent によるカスタムコンテンツ
• CSS クラスのカスタマイズ
• アクセシビリティ機能
• フォームおよび検証との連携

Skeleton コンポーネント

スケルトンの実装

📄 参照： references/skeleton-implementation.md

• Skeleton コンポーネントの使い始め方
• Skeleton の形状（Circle、Square、Rectangle、Text）
• シマーエフェクト（Pulse、Wave、Fade、None）
• 幅と高さの設定
• 読み込み状態の表示切り替え
• スクリーンリーダー向けのアクセシビリティラベル
• 複数の Skeleton レイアウト（リスト、カード、テーブル）
• 一般的な読み込みパターン（プロフィール、記事、グリッド）
• CSS のカスタマイズとテーマ設定
• パフォーマンスに関する考慮事項

スタイルとテーマ

すべての通知コンポーネントのスタイル設定

📄 参照： references/styling-and-themes.md

• テーマの統合（Bootstrap、Material、Fluent、Tailwind）
• Toast 用のカスタム CSS クラス
• Message 用のカスタム CSS クラス
• Skeleton 用のカスタム CSS クラス
• すべてのコンポーネントでのダークモード対応
• レスポンシブデザインのパターン
• 色のカスタマイズ
• アニメーションのカスタマイズ
• コンポーネント固有のスタイル設定手法

ユースケースと例

実際の実装例

📄 参照： references/use-cases-and-examples.md

• フォーム送信時のフィードバック（Toast + Message）
• E コマースのカート通知
• ダッシュボードのデータ更新
• ファイルアップロードの進行状況とフィードバック
• ユーザー認証時のフィードバック
• Skeleton プレースホルダーを使ったデータの読み込み
• エラー処理と復旧
• 複数ステップのプロセスに関するフィードバック
• 通知センター／履歴
• 3 つのコンポーネントを効果的に組み合わせる方法

一般的なパターン

パターン 1：Toast による成功／エラーフィードバック

@code {
    SfToast ToastObj;

    private async Task SaveData()
    {
        try
        {
            await DataService.SaveAsync();
            ToastObj.Title = "Success";
            ToastObj.Content = "Data saved successfully!";
            await ToastObj.ShowAsync();
        }
        catch (Exception ex)
        {
            ToastObj.Title = "Error";
            ToastObj.Content = $"Failed to save: {ex.Message}";
            await ToastObj.ShowAsync();
        }
    }
}

パターン 2：Message によるフォーム検証

<EditForm Model="@model" OnValidSubmit="HandleValidSubmit">
    <DataAnnotationsValidator />
    
    @if (!string.IsNullOrEmpty(errorMessage))
    {
        <SfMessage Severity="MessageSeverity.Error" 
                   ShowIcon="true" 
                   ShowCloseIcon="true"
                   Closed="@(() => errorMessage = null)">
            @errorMessage
        </SfMessage>
    }
    
    
</EditForm>

パターン 3：Skeleton による読み込み状態

@if (isLoading)
{
    <div class="product-card-skeleton">
        <SfSkeleton Shape="SkeletonType.Rectangle" Width="100%" Height="200px" />
        <SfSkeleton Shape="SkeletonType.Text" Width="80%" />
        <SfSkeleton Shape="SkeletonType.Text" Width="60%" />
    </div>
}
else
{
    <div class="product-card">
        <img src="@product.ImageUrl" alt="@product.Name" />
        <h3>@product.Name</h3>
        <p>@product.Description</p>
    </div>
}

パターン 4：複数の Toast タイプ

<SfToast @ref="SuccessToast" 
         Title="Success" 
         Icon="e-success" 
         CssClass="e-toast-success"
         <ToastPosition X="Right" Y="Top"></ToastPositio

<SfToast @ref="ErrorToast" 
         Title="Error" 
         Icon="e-error" 
         CssClass="e-toast-danger"
         <ToastPosition X="Right" Y="Top"></ToastPosition>

<SfToast @ref="WarningToast" 
         Title="Warning" 
         Icon="e-warning" 
         CssClass="e-toast-warning"
         <ToastPosition X="Right" Y="Top"></ToastPosition>

@code {
    SfToast SuccessToast, ErrorToast, WarningToast;

    private async Task ShowSuccess(string message)
    {
        SuccessToast.Content = message;
        await SuccessToast.ShowAsync();
    }

    private async Task ShowError(string message)
    {
        ErrorToast.Content = message;
        await ErrorToast.ShowAsync();
    }

    private async Task ShowWarning(string message)
    {
        WarningToast.Content = message;
        await WarningToast.ShowAsync();
    }
}

インストール

NuGet パッケージ

dotnet add package Syncfusion.Blazor.Notifications
dotnet add package Syncfusion.Blazor.Themes

サービスの登録

Program.cs:

using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSyncfusionBlazor();

名前空間のインポート

_Imports.razor:

@using Syncfusion.Blazor.Notifications

テーマの参照

App.razor またはレイアウトファイル：

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

主要なプロパティの一覧

Toast のプロパティ

プロパティ	型	説明
Content	string	Toast メッセージの内容
Title	string	Toast のタイトルテキスト
Icon	string	アイコンの CSS クラス
Position	ToastPosition	X 軸と Y 軸の位置（Top、Bottom、Left、Right、Center）
Timeout	int	自動非表示までの時間（ミリ秒、既定値：5000）
ShowCloseButton	bool	閉じるボタンを表示（既定値：false）
ShowProgressBar	bool	進行状況バーを表示（既定値：false）
NewestOnTop	bool	新しい Toast を上に重ねて表示（既定値：true）
CssClass	string	カスタム CSS クラス

Message のプロパティ

プロパティ	型	説明
Severity	MessageSeverity	Normal、Info、Success、Warning、Error
Variant	MessageVariant	Text、Outlined、Filled
ShowIcon	bool	深刻度アイコンを表示（既定値：true）
ShowCloseIcon	bool	閉じるボタンを表示（既定値：false）
Visible	bool	表示／非表示を制御
ContentAlignment	HorizontalAlign	左、中央、右の配置
CssClass	string	カスタム CSS クラス

Skeleton のプロパティ

プロパティ	型	説明
Shape	SkeletonType	Circle、Square、Rectangle、Text
Effect	ShimmerEffect	Pulse、Wave、Fade、None
Width	string	px、%、その他の CSS 単位で指定する幅
Height	string	px、%、その他の CSS 単位で指定する高さ
Visible	bool	表示／非表示を制御
Label	string	アクセシビリティラベル
CssClass	string	カスタム CSS クラス

一般的なユースケース

1. フォーム送信時のフィードバック - フォーム送信後に成功またはエラーのトーストを表示します
2. 検証メッセージ - 検証エラーのインラインメッセージを表示します
3. 読み込み状態 - データ取得中にスケルトンを使用します
4. カート操作 - カートへの追加や削除時にトースト通知を表示します
5. ファイルのアップロード - 進捗状況と完了通知を表示します
6. API エラー - 再試行オプション付きのエラーメッセージを表示します
7. セッション警告 - セッションの有効期限が切れる前に警告メッセージを表示します
8. データの更新 - 更新処理中にスケルトンのプレースホルダーを表示します
9. 複数ステップのフォーム - 各ステップで進捗状況を表示します
10. リアルタイム更新 - ライブデータの変更時にトースト通知を表示します

トラブルシューティング

トーストが表示されない

• トーストを表示するために ShowAsync() が呼び出されていることを確認します
• トーストコンポーネントにコンテンツまたはテンプレートがあることを確認します
• トーストのタイムアウトが短すぎないか確認します
• ToastPosition がビューポートの範囲内にあることを確認します

メッセージが表示されない

• Visible プロパティが true に設定されていることを確認します
• ChildContent または Content プロパティにメッセージの内容があることを確認します
• コンポーネントが DOM にレンダリングされていること（親要素によって非表示になっていないこと）を確認します
• CSS の z-index の競合を確認します

スケルトンがアニメーションしない

• Effect プロパティが設定されていること（Pulse、Wave、または Fade）を確認します
• テーマとともにシマー効果の CSS が読み込まれていることを確認します
• スケルトンに幅と高さが定義されていることを確認します
• Visible が true に設定されていることを確認します

テーマが適用されない

• テーマの CSS が App.razor またはレイアウトで参照されていることを確認します
• Syncfusion.Blazor.Themes パッケージがインストールされていることを確認します
• コンポーネントを使用する前に CSS リンクが配置されていることを確認します
• ブラウザーのキャッシュをクリアしてみます

サービスが登録されていない

• Program.cs に builder.Services.AddSyncfusionBlazor() を追加します
• Syncfusion.Blazor.Core パッケージがインストールされていることを確認します
• using ステートメントがあることを確認します
• サービスを追加した後にプロジェクトを再ビルドします

ベストプラクティス

1. 適切な通知の種類を使用する - 一時的な通知にはトースト、継続して表示する通知にはメッセージを使用します
2. トーストの表示時間を制限する - ほとんどのメッセージでは 3～7 秒、エラーの場合はより長くします
3. 明確な操作を用意する - 適切な場合は、再試行／閉じるボタンを含めます
4. スケルトンの形状を一致させる - スケルトンの形状を実際のコンテンツ構造に合わせます
5. アクセシビリティ - スケルトンとアイコンには必ずラベルを付けます
6. 位置の一貫性 - アプリ全体で同じトースト位置を使用します
7. メッセージの重大度 - メッセージの状況に応じた適切な重大度を使用します
8. 使いすぎを避ける - 通知を多用してユーザーを圧倒しないようにします
9. 段階的な機能強化 - 体感パフォーマンスの向上にスケルトンを使用します
10. エラー処理 - トーストやメッセージの表示エラーは常に適切に処理します

次のステップ

• アニメーションとテンプレートについては、トーストの高度な機能を参照してください
• フォーム検証については、メッセージの実装をご覧ください
• 読み込み状態については、スケルトンのパターンをご確認ください
• カスタマイズについては、スタイリングガイドを参照してください
• 一連のシナリオについては、実際の使用例をご覧ください