syncfusion-react-ribbon

Syncfusion React Ribbon

コンポーネントの概要

Syncfusion React Ribbon コンポーネントは、Microsoft Office に着想を得たコマンド中心のユーザーインターフェイスを作成するための、プロフェッショナルで高機能なツールバーです。関連するコマンドを視覚的に区別されたタブやグループに整理する直感的な階層構造を備えており、ユーザーはアクションをすばやく見つけて実行できます。

主な機能

• タブ付きリボンインターフェイス：コマンドを目的別のタブに整理して、ナビゲーションとグループ化を容易にします
• 2 種類のレイアウトモード：クラシック（複数行）とシンプル（1 行）のレイアウトに対応し、動的に切り替えられます
• 複数の項目タイプ：ボタン、チェックボックス、ドロップダウン、分割ボタン、コンボボックス、カラーピッカー、グループボタン、ギャラリー、カスタムテンプレート
• レスポンシブなサイズ変更：利用可能なスペースに応じて、項目のサイズ（大、中、小）を自動調整します
• ファイルメニューと Backstage ビュー：従来のファイルメニューまたはモダンな Backstage インターフェイスを備えた、完全なファイルメニューです
• コンテキストタブ：ユーザーの選択やアプリケーションの状態に応じて、タブを動的に表示／非表示にします
• ギャラリー対応：グループ化、フィルタリング、カスタム項目テンプレートを備えた、視覚的に選択できるギャラリーです
• KeyTips とキーボードナビゲーション：KeyTip に対応した、アクセシビリティを優先するキーボードナビゲーションです
• グループのオーバーフロー管理：グループの優先度や専用のオーバーフローポップアップを制御し、スペースをより有効に活用できます
• 豊富なカスタマイズ：カスタム CSS クラス、項目テンプレート、アイコン、レイアウトを制御できます
• 包括的なイベント処理：itemClick、tabSelected、fileMenuSelect などを利用して、細かく制御できます
• 複数のテーマに対応：Material、Bootstrap、Fluent、Tailwind CSS のテーマとダークモードに対応します
• RTL とアクセシビリティ：右から左に記述する言語を完全にサポートし、ARIA 属性による WCAG 準拠を実現します
• ヘルプペインとの統合：状況に応じた支援やドキュメントを提供するヘルプペインを内蔵しています

階層構造：

• Ribbon（ルートコンテナー）- メインのツールバーコンポーネント
  • Tabs（例：Home、Insert、View、Design）- コマンドを目的別にグループ化
    • Groups（例：Clipboard、Font、Styles）- 関連するコマンドのカテゴリ
      • Collections（論理的な項目コンテナー）- 項目の配置を支援
        • Items（ボタン、ドロップダウン、ギャラリー、カラーピッカーなど）- 個々のコマンドとコントロール

ドキュメント

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージのセットアップ
• リボンコンポーネントの基本的な実装
• CSS のインポートとテーマ
• 最初の動作するサンプル
• TypeScript の設定

リボンの構造

📄 参照： references/ribbon-structure.md

• タブの作成と設定
• グループの整理と階層構造
• コレクションと項目コンテナー
• タブヘッダーのプロパティ
• グループヘッダーとアイコン
• 項目のサイズと向き

項目とグループ

📄 参照： references/items-and-groups.md

• 組み込みの項目タイプ（Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Template）
• 項目のプロパティとアイコン
• 項目のサイズ（大、中、小）とアクティブなサイズの制御
• カスタムクラスを使用した項目の CSS カスタマイズ
• RibbonTooltipSettings を使用した項目のツールチップ
• カスタム描画用の項目テンプレート
• 無効状態と表示オプション
• グループの向き（行と列）
• グループのオーバーフロー動作と優先度

タブとグループの設定

📄 参照： references/tabs-and-groups.md

• タブの追加と管理
• タブレベルの設定と CSS カスタマイズ
• カスタムクラスとテーマを使用したタブのスタイル設定
• グループのプロパティと整理
• グループヘッダーとアイコン
• グループの折りたたみとランチャーアイコン
• タブ／グループの動的な管理

レイアウトと表示モード

📄 お読みください： references/layouts-display-modes.md

• クラシックレイアウト（従来の複数行形式）
• シンプルレイアウト（コンパクトな1行形式）
• レイアウトの切り替えとレイアウト切り替えボタン
• 項目の表示オプション（Auto、Classic、Simplified、Overflow）
• レスポンシブなサイズ変更の動作
• サイズ変更時の項目サイズの調整
• 最小化状態（リボンの折りたたみ）

ファイルメニューとバックステージ

📄 お読みください： references/file-menu-backstage.md

• ファイルメニューの設定と表示
• カスタムレンダリング用のファイルメニュー項目テンプレート
• ファイルメニューのポップアップテンプレート
• ファイルメニューのアニメーション設定
• ファイルメニューのツールチップ設定
• イベント処理全般（beforeOpen、open、beforeClose、close、beforeItemRender、select）
• バックステージビューの実装
• 高度なオプションを使用したバックステージ項目の設定
• バックステージの寸法（幅、高さ）と配置
• バックステージのKeyTip連携
• バックステージのツールチップ設定
• フッター項目と区切り線
• 戻るボタンのカスタマイズ
• カスタムバックステージテンプレート
• バックステージ内のナビゲーション

コンテキストタブとギャラリー

📄 お読みください： references/contextual-tabs-gallery.md

• コンテキストタブの作成
• コンテキストタブの表示制御
• コンテキストタブのプログラムによる表示／非表示
• ギャラリー項目の設定
• ギャラリーのグループと項目
• ギャラリー項目テンプレート
• ギャラリーのフィルタリングと選択
• ポップアップの幅と高さ

イベントとアクセシビリティ

📄 お読みください： references/events-accessibility.md

• リボンのイベント（itemClick、tabSelectedなど）
• イベント処理とコールバック
• KeyTipを使用したキーボードショートカット
• KeyTipの設定
• アクセシビリティへの準拠（WCAG）
• ARIA属性
• スクリーンリーダーのサポート
• RTLのサポート
• フォーカス管理
• キーボードナビゲーション

カスタマイズとテーマ設定

📄 お読みください： references/customization-theming.md

• 利用可能な組み込みテーマ（Material、Bootstrap、Fluent、Tailwind）
• テーマのインポートと適用
• CSSのカスタマイズ
• カスタムアイコンフォント
• Theme Studioとの連携
• ダークモードのサポート
• レスポンシブデザインに関する考慮事項
• カスタムCSSクラス

ツールチップとヘルプペイン

📄 お読みください： references/tooltips-help-pane.md

• 項目のツールチップ実装
• カスタムツールチップテンプレート
• ヘルプペインの設定
• ヘルプペインのテンプレートとコンテンツ
• コンテキストヘルプとの連携

トラブルシューティング

📄 お読みください： references/troubleshooting.md

• よくある問題と解決方法
• パフォーマンス最適化のヒント
• スタイルと表示に関する問題
• イベント処理の問題
• モジュール注入に関するトラブルシューティング
• レスポンシブ動作に関する問題

クイックスタート

タブとグループを備えた基本的なリボン

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
@import "@syncfusion/ej2-tailwind3-theme/styles/ribbon/index.css";

function App() {
  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-paste", content: "Paste" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

ファイルメニューを備えたリボン

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" },
    { text: "Save as", iconCss: "e-icons e-save", id: "saveas" }
  ];

  return (
    <RibbonComponent id="ribbon" fileMenu={{ visible: true, menuItems: fileOptions }}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

一般的なパターン

パターン1：複数の項目タイプを含む複数タブのリボン

異なる項目タイプ（ボタン、ドロップダウン、コンボ）を含む複数のタブで、プロフェッショナルなリボンを構成します。

パターン2：クラシックレイアウトとシンプルレイアウトに対応したレスポンシブリボン

画面サイズやユーザーの設定に応じて、クラシック（複数行）レイアウトとシンプル（1行）レイアウトを切り替えるリボンを作成します。

パターン3：コンテキスト対応リボン

ユーザーが特定のオブジェクトやコンテンツタイプを選択したときに、コンテキストタブを動的に表示／非表示にします。

パターン4：バックステージビューを備えたファイルメニュー

ファイルメニューとバックステージを組み合わせて、包括的なドキュメント管理とアプリケーション設定を実現します。

パターン5：ギャラリーベースの項目選択

ギャラリーを使用して、スタイル、テンプレート、書式設定オプションを視覚的に選択できるようにします。

主なプロパティと機能

RibbonComponent:

• fileMenu - ファイルメニューの表示と項目を設定します
• backStageMenu - バックステージビューを有効にして設定します
• activeLayout - レイアウトモード（Classic、Simplified）を設定します
• isMinimized - リボンをプログラムで最小化／展開します
• hideLayoutSwitcher - レイアウト切り替えボタンを非表示にします

RibbonTabDirective:

• header - タブのタイトルテキスト
• cssClass - タブのスタイル設定用カスタム CSS クラス

RibbonGroupDirective:

• header - グループのタイトル
• orientation - 項目の配置（Row、Column）
• groupIconCss - グループのオーバーフロー用カスタムアイコン
• showLauncherIcon - ランチャーアイコンを表示します
• enableGroupOverflow - グループ専用のオーバーフローポップアップ
• isCollapsible - リサイズ時にグループを折りたためるようにします
• priority - 折りたたみ／展開の優先度

RibbonItemDirective:

• type - 項目の種類（Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Gallery、Template）
• allowedSizes - 使用可能な項目サイズ（Large、Medium、Small）
• activeSize - 項目の現在の表示サイズ
• cssClass - 項目のスタイル設定用カスタム CSS クラス
• ribbonTooltipSettings - タイトルと内容を含むツールチップ設定
• itemTemplate - 項目のレンダリング用カスタムテンプレート
• displayOptions - レイアウト内での表示設定（Auto、Classic、Simplified、Overflow）
• disabled - 項目を有効／無効にします
• 設定オブジェクト：buttonSettings、dropDownSettings、splitButtonSettings など

完全な例や高度なシナリオについては、上記の各リファレンスファイルをご覧ください。