syncfusion-blazor-toolbar

Syncfusion Blazor Toolbar コンポーネント

Syncfusion Blazor Toolbar は、ボタン、区切り線、カスタムコントロールを備えたインタラクティブなコマンドバーを作成するための多用途コンポーネントです。レスポンシブ動作が組み込まれており、アイテムを柔軟に設定できます。

このスキルを使用する場合

次のような場合に、このスキルを使用します。

• ボタン、アイコン、カスタムコントロールを備えたツールバーを作成する
• 書式設定ツールバー（太字、斜体、配置など）付きのテキストエディターを構築する
• アプリケーションにコマンドバーやアクションバーを実装する
• さまざまな画面サイズに適応するレスポンシブなツールバーを追加する
• アイテムのオーバーフロー動作（スクロール可能、ポップアップ、複数行）を設定する
• 配置と間隔を設定したナビゲーションツールバーを作成する
• トグルボタンや状態を持つツールバーアイテムを追加する
• アイテムの追加・削除機能を備えた動的なツールバーを実装する
• ツールバーの外観やスタイルをカスタマイズする
• 右から左に記述する言語向けに RTL サポートを有効にする

コンポーネントの概要

Blazor Toolbar コンポーネントには、次の機能があります。

• アイテムの種類：ボタン、区切り線、スペーサー、カスタムテンプレート
• レスポンシブモード：スクロール可能、ポップアップ、複数行、拡張オーバーフロー処理
• 配置：スペーサーを使った左揃え、中央揃え、右揃え
• カスタマイズ：アイコン、ツールチップ、スタイル、テンプレート、RTL サポート
• 動的な管理：プログラムによるアイテムの追加、削除、有効化、無効化、表示、非表示

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

はじめに

📄 参照： references/getting-started.md

ユーザーが次のことを行う場合：

• Toolbar コンポーネントをインストールして設定する
• NuGet パッケージを追加し、サービスを登録する
• アイテムを含む基本的なツールバーを作成する
• ToolbarItems の基本的な構造を理解する
• CSS テーマとスクリプト参照を設定する

アイテムの設定とプロパティ

📄 参照： references/item-configuration.md

ユーザーが次のことを行う場合：

• アイテムのプロパティ（Text、PrefixIcon、SuffixIcon、Width など）を設定する
• アイテムの配置（Left、Center、Right）を設定する
• アイテムの種類（Button、Separator、Input、Spacer）を定義する
• アイテムの表示状態と有効状態を制御する
• ツールバーのアイテムにツールチップを追加する
• カスタム CSS クラスや HTML 属性を使用する
• 個々のアイテムのオーバーフロー動作を設定する
• 他の Syncfusion コンポーネント（DropDownList、NumericTextBox など）を統合する
• 18 個のアイテムプロパティすべての詳細を理解する

実践的な操作ガイド

📄 参照： references/how-to-guides.md

ユーザーが次のことを行う場合：

• ツールバーのアイテムを動的に追加または削除する
• プログラムでツールバーのアイテムを有効または無効にする
• 条件に応じてツールバーのアイテムを表示または非表示にする
• 状態管理付きのトグルボタンを作成する
• HtmlAttributes と CssClass でアイテムをカスタマイズする
• アイテムごとにカスタムテンプレートを設定する
• SfTooltip コンポーネントを使ってツールチップを追加する
• TabIndex で Tab キーによるナビゲーションを有効にする
• スクロール距離をカスタマイズする

レスポンシブ動作とオーバーフローモード

📄 参照： references/responsive-mode.md

ユーザーが次のことを行う場合：

• ツールバーのオーバーフロー動作（Scrollable、Popup、MultiRow、Extended）を設定する
• オーバーフロー処理のアイテム優先度を設定する
• ツールバーとポップアップでのテキスト表示（ShowTextOn）を制御する
• ナビゲーション矢印付きのスクロール可能なツールバーを実装する
• ドロップダウンオーバーフロー付きのポップアップツールバーを作成する
• 複数行または拡張オーバーフローのレイアウトを設定する
• スクロール時のタッチ操作に対応する

Spacer による配置と間隔の調整

📄 参照： references/alignment-spacer.md

ユーザーが次のことを行う場合：

• Spacer を使ってアイテムを左、中央、右に配置する
• 左揃えと右揃えのパターンを作成する
• 右揃えのみを実装する
• Spacer と Align プロパティを使い分ける方法を理解する
• ツールバーのアイテム間に柔軟な間隔を適用する

スタイリングとカスタマイズ

📄 参照: references/styling.md

次のような場合に使用します。

• ツールバーコンテナーのスタイルをカスタマイズする
• ツールバー項目とボタンのスタイルを設定する
• アイコンの外観を変更する
• ホバー時とフォーカス時の状態をカスタマイズする
• カスタムテーマを適用する
• デフォルトの CSS クラスを上書きする
• アラビア語、ヘブライ語、ウルドゥー語の RTL（右から左）サポートを有効にする

クイックスタートの例

一般的な書式設定ボタンを備えた基本的なツールバー：

@using Syncfusion.Blazor.Navigations

<SfToolbar>
    <ToolbarItems>
        <ToolbarItem Text="Cut" PrefixIcon="e-icons e-cut"></ToolbarItem>
        <ToolbarItem Text="Copy" PrefixIcon="e-icons e-copy"></ToolbarItem>
        <ToolbarItem Text="Paste" PrefixIcon="e-icons e-paste"></ToolbarItem>
        <ToolbarItem Type="ItemType.Separator"></ToolbarItem>
        <ToolbarItem Text="Bold" PrefixIcon="e-icons e-bold"></ToolbarItem>
        <ToolbarItem Text="Italic" PrefixIcon="e-icons e-italic"></ToolbarItem>
        <ToolbarItem Text="Underline" PrefixIcon="e-icons e-underline"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

一般的なパターン

パターン 1：テキストエディターのツールバー

配置と間隔の調整機能を備えた書式設定ツールバー：

<SfToolbar Width="600">
    <ToolbarItems>
        <ToolbarItem Text="Bold" PrefixIcon="e-icons e-bold"></ToolbarItem>
        <ToolbarItem Text="Italic" PrefixIcon="e-icons e-italic"></ToolbarItem>
        <ToolbarItem Type="ItemType.Separator"></ToolbarItem>
        <ToolbarItem Type="ItemType.Spacer"></ToolbarItem>
        <ToolbarItem Text="Left" PrefixIcon="e-icons e-align-left"></ToolbarItem>
        <ToolbarItem Text="Center" PrefixIcon="e-icons e-align-center"></ToolbarItem>
        <ToolbarItem Text="Right" PrefixIcon="e-icons e-align-right"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

パターン 2：ポップアップ付きのレスポンシブツールバー

あふれた項目をポップアップに移動するツールバー：

<SfToolbar Width="400" OverflowMode="OverflowMode.Popup">
    <ToolbarItems>
        <ToolbarItem Text="Cut" PrefixIcon="e-icons e-cut" Overflow="OverflowOption.Show"></ToolbarItem>
        <ToolbarItem Text="Copy" PrefixIcon="e-icons e-copy" Overflow="OverflowOption.Show"></ToolbarItem>
        <ToolbarItem Text="Paste" PrefixIcon="e-icons e-paste"></ToolbarItem>
        <ToolbarItem Type="ItemType.Separator"></ToolbarItem>
        <ToolbarItem Text="Bold" PrefixIcon="e-icons e-bold"></ToolbarItem>
        <ToolbarItem Text="Italic" PrefixIcon="e-icons e-italic"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

パターン 3：項目を追加・削除できる動的ツールバー

プログラムから項目を管理できるツールバー：

<SfToolbar>
    <ToolbarItems>
        @foreach (var item in ToolbarItems)
        {
            <ToolbarItem Text="@item.Text" PrefixIcon="@item.Icon"></ToolbarItem>
        }
    </ToolbarItems>
</SfToolbar>

@code {
    private List<ToolbarItemData> ToolbarItems = new()
    {
        new() { Text = "Cut", Icon = "e-icons e-cut" },
        new() { Text = "Copy", Icon = "e-icons e-copy" }
    };
    
    private void AddItem()
    {
        ToolbarItems.Add(new() { Text = "Paste", Icon = "e-icons e-paste" });
    }
    
    private void RemoveItem()
    {
        if (ToolbarItems.Count > 0)
            ToolbarItems.RemoveAt(0);
    }
    
    public class ToolbarItemData
    {
        public string Text { get; set; }
        public string Icon { get; set; }
    }
}

パターン 4：配置をカスタマイズできるツールバー

Spacer を使って、左揃え、中央揃え、右揃えにした項目：

<SfToolbar>
    <ToolbarItems>
        <ToolbarItem Text="File"></ToolbarItem>
        <ToolbarItem Text="Edit"></ToolbarItem>
        <ToolbarItem Type="ItemType.Spacer"></ToolbarItem>
        <ToolbarItem Text="Help"></ToolbarItem>
        <ToolbarItem Type="ItemType.Spacer"></ToolbarItem>
        <ToolbarItem Text="Settings" PrefixIcon="e-icons e-settings"></ToolbarItem>
        <ToolbarItem Text="Profile" PrefixIcon="e-icons e-user"></ToolbarItem>
    </ToolbarItems>
</SfToolbar>

主なプロパティのリファレンス

SfToolbar コンポーネントのプロパティ

プロパティ	型	説明
Width	string	ツールバーの幅を設定します（例："600px"、"100%"）
Height	string	ツールバーの高さを設定します
OverflowMode	OverflowMode	あふれた項目の動作を定義します：Scrollable、Popup、MultiRow、Extended
ScrollStep	int	ナビゲーション矢印を使ってスクロールする際のピクセル単位の距離
EnableRtl	bool	右から左へのレイアウトを有効にします
CssClass	string	ツールバーコンテナーに適用するカスタム CSS クラス

ToolbarItem のプロパティ

プロパティ	型	説明
Text	string	ボタンのテキスト
PrefixIcon	string	テキストの前に表示するアイコンの CSS クラス
SuffixIcon	string	テキストの後に表示するアイコンの CSS クラス
TooltipText	string	ホバー時に表示するツールチップ
Type	ItemType	Button、Separator、Input、Spacer のいずれか
Align	ItemAlign	左、中央、右の配置
Disabled	bool	true の場合、項目を無効にします
Visible	bool	項目の表示状態を制御します
Width	string	項目の幅を設定します
CssClass	string	項目に適用するカスタム CSS クラス
HtmlAttributes	Dictionary	カスタム HTML 属性（id、style、role など）
Overflow	OverflowOption	Show（優先）、Hide（二次優先）、None のいずれか
ShowAlwaysInPopup	bool	ポップアップモードで項目を常にポップアップに表示します
ShowTextOn	DisplayMode	テキストの表示場所を制御します：Toolbar、Overflow、Both
TabIndex	int	Tab キーによる移動を有効にします
Template	RenderFragment	カスタムコンテンツテンプレート
Id	string	項目の一意な識別子

実装ガイドライン

項目を設定する場合

1. 適切な項目タイプを使用する：アクションには Button、視覚的な区切りには Separator、配置には Spacer、カスタムコントロールには Input を使用します
2. アイコンを追加して UX を向上させる：アイコンのみ、またはアイコンとテキストを組み合わせたボタンには PrefixIcon を使用します
3. ツールチップを設定する：アイコンのみのボタンに TooltipText を設定して、アクセシビリティを向上させます
4. レスポンシブ動作を考慮する：対象デバイスに応じて適切な OverflowMode を選択します
5. あふれた項目の優先順位を設定する：Overflow プロパティを使って、どの項目を先にポップアップへ移動するかを制御します

あふれた項目を処理する場合

1. Scrollable モード（デフォルト）：水平方向に余裕のあるデスクトップアプリケーションに最適です
2. Popup モード：モバイルや幅が限られたコンテナーに最適です
3. MultiRow モード：関連する項目が多数あるツールバーに適しています
4. Extended モード：MultiRow に似ていますが、レイアウトの動作が異なります

外観をカスタマイズする場合

1. 組み込みアイコンを使用する：e-icons クラスで Syncfusion アイコンライブラリを活用します
2. テーマを一貫して適用する：カスタムスタイルには CssClass を使用します
3. アクセシビリティを考慮する：十分な色のコントラストとフォーカスインジケーターを維持します
4. レスポンシブ動作をテストする：さまざまな幅でツールバーの外観を確認します

動的な動作を実装する場合

1. データバインディングを使用する：動的に更新できるよう、ToolbarItems をコレクションにバインドします
2. イベントを処理する：ボタンの操作には OnClick を使用します
3. 条件に応じて状態を更新する：アプリケーションの状態に応じて、Disabled または Visible プロパティを切り替えます
4. 項目のライフサイクルを管理する：ツールバーを更新するには、バインドされたコレクションに項目を追加または削除します

よくあるユースケース

1. リッチテキストエディター：太字、斜体、配置、リストの書式設定ツールバー
2. ファイルマネージャー：アップロード、ダウンロード、削除、名前変更ボタンを備えたアクションバー
3. データグリッド：追加、編集、削除、エクスポート操作用のコマンドツールバー
4. 画像エディター：描画、トリミング、フィルターツールを備えたツールパレット
5. ナビゲーションメニュー：メニュー項目や検索機能を備えた最上位のナビゲーション
6. ダッシュボードのコントロール：更新、フィルター、設定用のアクションボタン
7. フォームビルダー：ドラッグ可能なコントロールを備えたコンポーネントパレット

ヒントとベストプラクティス

• アイコンのみのボタン：アクセシビリティのために、必ず TooltipText を指定します
• レスポンシブデザイン：さまざまな幅でツールバーをテストし、オーバーフロー時の動作を確認します
• キーボードナビゲーション：キーボードアクセシビリティを向上させるため、TabIndex を有効にします
• 視覚的なグループ化：関連する項目を論理的なグループにまとめるには、Separator を使用します
• パフォーマンス：項目数が多い場合は、初期レンダリングのサイズを抑えるために Popup モードを検討します
• カスタムテンプレート：標準のボタンでは対応できない複雑なコントロールには、Template プロパティを使用します
• 柔軟な配置：より動的なレイアウトには、Align プロパティより Spacer を優先します

次のステップ

基本的なツールバーを実装した後は、次の手順に進みます。

1. さまざまな画面サイズに対応できるよう、レスポンシブモードを確認します
2. アクセシビリティのために、TabIndex を使ったキーボードナビゲーションを追加します
3. アプリケーションのテーマに合わせてスタイルをカスタマイズします
4. インタラクティブなツールバーのために、動的な項目管理を実装します
5. テンプレートを使って、トグルボタンやカスタムコントロールを追加します
6. 他の Syncfusion コンポーネント（DropDownList、ColorPicker など）と連携します