syncfusion-react-toolbar

Syncfusion React Toolbar の実装

コンポーネントの概要

Syncfusion React Toolbar コンポーネントは、コマンドを整理して実行するための柔軟なコマンドバーを提供します。複数の項目タイプ（ボタン、セパレーター、入力）、レスポンシブなオーバーフローモード、包括的なアクセシビリティ機能に対応しています。

主な機能：

• 複数の項目タイプ：Button、Separator、Input
• レスポンシブなオーバーフローモード：Scrollable、Popup、MultiRow、Extended
• キーボードナビゲーションと ARIA を標準サポート
• ツールバー項目内でのコンポーネントのレンダリング
• 外観と動作をカスタマイズ可能
• Tab キーによるナビゲーションに対応
• 項目の動的な管理（追加／削除／有効化／無効化）
• 豊富なイベントシステム（beforeCreate、clicked、keyDown、created、destroyed）
• RTL とロケールに完全対応
• ステートレスなテンプレートレンダリング

---

目次

1. はじめに

ファイル： references/getting-started.md

• 依存関係のセットアップ
• プロジェクトの初期化（Vite/CRA）
• パッケージのインストール
• CSS テーマのインポート（Tailwind、Bootstrap、Fluent、Material）
• 基本的な実装例
• グローバル設定：
  • 国際化のためのロケール対応
  • RTL（右から左）レイアウト
  • 永続化の設定
  • 衝突の検出
  • HTML サニタイザー
• 開発サーバーのセットアップ

2. 項目の設定

ファイル： references/item-configuration.md

• ItemModel API リファレンス：
  • インターフェース構造の全体
  • 16 個すべてのプロパティと型
  • 説明付きのプロパティリファレンス
  • Items 配列の設定パターン
  • 設定例（シンプル、グループ化、条件付き、アクセシブル）
• Button 項目タイプのプロパティ：
  • text - 表示テキスト
  • id - 一意の識別子
  • prefixIcon / suffixIcon - アイコンの配置
  • width - カスタム幅
  • align - 配置（Left/Center/Right）
  • disabled - 無効状態
  • visible - 表示／非表示の制御
  • cssClass - カスタム CSS クラス
  • htmlAttributes - HTML 属性
  • overflow - 優先表示設定（Show/Hide/None）
  • showAlwaysInPopup - ポップアップでの常時表示を強制
  • showTextOn - テキストの表示モード（Both/Overflow/Toolbar）
• Separator 項目タイプ
• コンポーネント用の Input 項目タイプ
• tabIndex による Tab ナビゲーション
• 完全な動作例

3. レスポンシブモード

ファイル： references/responsive-modes.md

• Scrollable モード（デフォルト）
  • ナビゲーション矢印による水平スクロール
  • タッチスワイプに対応
  • 矢印キーによるナビゲーション
  • 用途：項目数が多い場合、大画面
• Popup モード
  • ドロップダウン形式のオーバーフローコンテナー
  • コマンドの優先度を制御
  • コンパクトな外観
  • 用途：スペースが限られている場合、モバイル
• MultiRow モード
  • 項目を複数行に折り返し
  • スクロール不要
  • すべての項目を表示
  • 用途：幅が変化するコンテナー
• Extended モード
  • 水平スクロールに対応した複数行表示
  • 行単位のナビゲーション
  • 用途：幅が限られた領域に項目が多い場合
• コマンドの優先度（Show/Hide/None）
• テキストの表示オプション（Both/Overflow/Toolbar）
• モード比較表
• 各モードの実用例

4. アクセシビリティとキーボード操作

ファイル： references/accessibility.md

• 準拠する標準：
  • WCAG 2.2 Level AA
  • Section 508 に準拠
  • スクリーンリーダーに対応（NVDA、JAWS、VoiceOver）
• ARIA 属性：
  • role="toolbar"
  • aria-label、aria-orientation
  • aria-expanded、aria-haspopup
• キーボードナビゲーション：
  • allowKeyboard プロパティによる制御
  • 矢印キー（左／右）によるナビゲーション
  • Home/End キー
  • Tab/Shift+Tab によるフォーカス移動
  • Enter/Space による実行
  • Escape によるポップアップの終了
• keyDown イベントの処理：
  • イベントパラメーター（currentItem、nextItem、originalEvent）
  • カスタムキーボードショートカット
  • デフォルトのナビゲーションの防止
  • キーごとのアクション
• スクリーンリーダーへの対応とテスト
• 色のコントラストに関する WCAG 準拠
• モバイル／タッチのアクセシビリティ
• RTL 対応
• ARIA のベストプラクティス
• テストチェックリストとツール

5. 項目の設定（続き）

ファイル： references/item-configuration.md

• ボタンプロパティのリファレンス
• 区切り線のスタイル設定
• 入力コンポーネント（NumericTextBox、DropDownList、CheckBox、RadioButton）
• タブナビゲーションコントロール
• ツールバーの完全なサンプル

6. スタイル設定とカスタマイズ

ファイル： references/styling-customization.md

• CSS クラス構造：
  • .e-toolbar - コンテナー
  • .e-toolbar-item - 項目のラッパー
  • .e-tbar-btn - ボタン
  • .e-icons - アイコン要素
  • .e-separator - 区切り線
  • .e-toolbar-pop - ポップアップ
• ツールバーコンテナーのスタイル設定
• 項目とボタンのスタイル設定
• アイコンのスタイル設定とカスタマイズ
• 状態のスタイル設定（ホバー、フォーカス、アクティブ、無効）
• テーマの統合（Tailwind、Bootstrap、Fluent、Material）
• ポップアップのカスタマイズ用 CSS クラス：
  • .e-toolbar-pop - ポップアップコンテナー
  • .e-overflow-button - ドロップダウンの切り替え
  • .e-overflow-show - 優先項目を表示
  • .e-overflow-hide - 優先項目を非表示
  • .e-popup-text - ポップアップテキストのスタイル設定
  • .e-toolbar-text - ツールバーテキストのスタイル設定
• カスタムスタイル設定の例
• パフォーマンスの最適化
• スタイル設定済みの完全なサンプル

7. 高度な機能とテンプレート

ファイル： references/advanced-features.md

• テンプレートの設定：
  • テンプレートの基本（関数／JSX）
  • テンプレートのプロパティ
  • テンプレートを使用する場面
• 項目ごとのカスタムテンプレート：
  • 単一項目のテンプレート
  • 複数の異なるテンプレート
  • テンプレート内の状態
  • テンプレートのスタイル設定
• ステートレステンプレート：
  • パフォーマンスの最適化
  • CSS クラスのカスタマイズ
  • ポップアップのカスタマイズに相当する設定
• トグルボタン：
  • 単一のトグル状態
  • トグルグループ（ラジオボタン風）
  • CSS のスタイル設定
• リンク項目：
  • ナビゲーションリンク
  • 外部リンク
  • パンくずリストのパターン
• ツールチップ：
  • HTML の title 属性
  • カスタムツールチップコンポーネント
  • スタイル設定と配置
• その他のコンポーネントのレンダリング：
  • Syncfusion コンポーネント（DropDownList、NumericTextBox、ColorPicker）
  • React コンポーネント
  • カスタムコンポーネント
• コマンドのカスタマイズ：
  • クリックハンドラー
  • コンテキストメニュー
  • カスタムアクション
• 項目の動的管理：
  • addItems() - 実行時に項目を追加
  • removeItems() - インデックスまたは ID を指定して項目を削除
  • enableItems() - 項目を有効／無効にする
  • hideItem() - 項目を表示／非表示にする
  • disable() - ツールバー全体を無効にする
  • destroy() - クリーンアップ
  • refreshOverflow() - レイアウトを再計算
• イベント処理：
  • beforeCreate - 初期化前のカスタマイズ
  • created - 初期化後のコールバック
  • clicked - ClickEventArgs を使用する項目のクリックイベント
  • keyDown - KeyDownEventArgs を使用するキーボードイベント
  • destroyed - クリーンアップイベント
• スクロールステップのカスタマイズ：
  • スクロール距離を制御
  • スクロールステップを動的に設定
  • タッチスワイプの動作
• 高度な機能を含む完全なサンプル

---

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

はじめに

📄 参照： references/getting-started.md

• パッケージのインストールと依存関係
• Vite と React を使用したセットアップ
• CSS のインポートとテーマの設定
• ItemsDirective を使用した基本的なツールバー
• HTML 要素の初期化
• 開発サーバーの起動

項目の設定と種類

📄 参照： references/item-configuration.md

• プロパティ（text、icons、width、align）を持つボタン項目の種類
• 区切り線項目の種類
• コンポーネント用の入力項目の種類
• tabIndex を使用した Tab キーによるナビゲーション
• 動作する完全なサンプル

レスポンシブモード

📄 参照： references/responsive-modes.md

• スクロール可能モード（デフォルトの動作）
• ポップアップオーバーフローモード
• コマンドの優先度（表示、非表示、なし）
• テキストの表示オプション
• ナビゲーションと操作のパターン

アクセシビリティとキーボードサポート

📄 参照： references/accessibility.md

• WCAG 2.2 および Section 508 への準拠
• ARIA 属性とロール
• キーボードナビゲーションキー
• スクリーンリーダーのサポート
• モバイルデバイスのアクセシビリティ

スタイル設定とカスタマイズ

📄 参照： references/styling-customization.md

• CSS のカスタマイズパターン
• ツールバーと項目のスタイル設定
• アイコンとボタンのカスタマイズ
• ホバー時とフォーカス時の状態
• テーマとの統合

高度な機能とテンプレート

📄 参照： references/advanced-features.md

• テンプレートの設定とパターン
• 項目ごとのカスタムテンプレート
• トグルボタン
• リンク項目
• ツールチップ
• その他の Syncfusion コンポーネントのレンダリング
• コマンドとスクロールのカスタマイズ

---

クイックスタートの例

import { ItemDirective, ItemsDirective, ToolbarComponent } from '@syncfusion/ej2-react-navigations';
import './App.css';

const App = () => {
  return (
    <ToolbarComponent id='toolbar'>
      <ItemsDirective>
        <ItemDirective text="Cut" prefixIcon="e-cut-icon" />
        <ItemDirective text="Copy" prefixIcon="e-copy-icon" />
        <ItemDirective text="Paste" prefixIcon="e-paste-icon" />
        <ItemDirective type="Separator" />
        <ItemDirective text="Bold" prefixIcon="e-bold-icon" />
        <ItemDirective text="Italic" prefixIcon="e-italic-icon" />
        <ItemDirective text="Underline" prefixIcon="e-underline-icon" />
      </ItemsDirective>
    </ToolbarComponent>
  );
};

export default App;

App.css で必要な CSS のインポート：

@import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-react-navigations/styles/tailwind3.css';

---

よくあるパターン

ボタンと区切り線を使った基本的なツールバー

ボタンコマンドと、グループ間の視覚的な区切り線を使って、シンプルなツールバーを作成します。

<ToolbarComponent>
  <ItemsDirective>
    {/* Edit commands */}
    <ItemDirective text="Cut" />
    <ItemDirective text="Copy" />
    <ItemDirective type="Separator" />
    {/* Format commands */}
    <ItemDirective text="Bold" />
    <ItemDirective text="Italic" />
  </ItemsDirective>
</ToolbarComponent>

アイコン付きツールバー

prefixIcon を使ってボタンにアイコンを追加し、視覚的にわかりやすくします。

<ItemDirective text="Save" prefixIcon="e-save-icon" />
<ItemDirective text="Print" prefixIcon="e-print-icon" />

レスポンシブなオーバーフロー処理

連続して表示する Scrollable（デフォルト）か、コンパクトに表示する Popup を選択します。

{/* Scrollable mode with navigation arrows */}
<ToolbarComponent overflowMode="Scrollable">
  {/* items */}
</ToolbarComponent>

{/* Popup mode with dropdown */}
<ToolbarComponent overflowMode="Popup">
  {/* items */}
</ToolbarComponent>

入力コンポーネントを含むツールバー

ドロップダウンなどのインタラクティブなコンポーネントをツールバー項目に含めます。

<ItemDirective type="Input" template={<DropDownComponent {...props} />} />

---

主な Props

プロパティ	型	説明
id	string	ツールバーの一意な識別子
overflowMode	"Scrollable" | "Popup"	オーバーフロー項目の処理方法
width	string	ツールバーコンテナーの幅
items	ItemModel[]	ツールバー項目の配列
text	string	ボタン項目に表示するテキスト
prefixIcon	string	先頭位置に表示するアイコンのクラス
suffixIcon	string	末尾位置に表示するアイコンのクラス
type	"Button" | "Separator" | "Input"	項目の種類
align	"Left" | "Center" | "Right"	項目の配置
overflow	"Show" | "Hide" | "None"	Popup モードでの優先度
tabIndex	number	タブ移動の順序
template	function	項目用のカスタムテンプレート

---

よくあるユースケース

1. テキストエディターのツールバー

   • 書式設定ボタン（太字、斜体、下線）
   • 配置オプション
   • 色とフォントの選択ツール
   • 参照先：responsive-modes.md、advanced-features.md

2. ファイル操作のツールバー

   • 新規、開く、保存、名前を付けて保存のボタン
   • 印刷機能
   • 元に戻す／やり直しコマンド
   • 参照先：item-configuration.md、advanced-features.md

3. レスポンシブなモバイルツールバー

   • コンパクトに表示する Popup オーバーフローモード
   • 継続的にアクセスできる Scrollable モード
   • 参照先：responsive-modes.md

4. アクセシブルなコマンドバー

   • キーボードナビゲーションのサポート
   • ARIA 属性
   • スクリーンリーダーに配慮した設計
   • 参照先：accessibility.md

5. ブランドに合わせてカスタマイズしたツールバー

   • カスタム CSS によるスタイル設定
   • テーマとの統合
   • 企業独自のアイコン
   • 参照先：styling-customization.md

---

まとめ

Toolbar コンポーネントは、React アプリケーションにおけるコマンドの整理と実行のための包括的なソリューションを提供します。基本的なセットアップについては getting-started.md から始め、ニーズに応じて個々の機能を確認してください。テンプレートのカスタマイズや複雑なシナリオには advanced-features.md をご利用ください。

ナビゲーションの流れ：

1. Getting Started → 基本的なツールバーのセットアップ
2. Item Configuration → さまざまな種類の項目を追加
3. Responsive Modes → オーバーフローを処理
4. Accessibility → キーボードサポートを確保
5. Styling → 外観をカスタマイズ
6. Advanced Features → テンプレートとカスタムコンポーネント