syncfusion-javascript-ribbon

Syncfusion JavaScript リボンコントロール

概要

Syncfusion JavaScript リボンコントロールは、コマンドを次の階層に整理するナビゲーションコンポーネントです。

• タブ：最上位のカテゴリ（ホーム、挿入、表示）
• グループ：タブ内の関連するコマンドセット（クリップボード、フォント、テーブル）
• コレクション：グループ内で項目を整理するコンテナー
• 項目：個々のコントロール（ボタン、ドロップダウン、ギャラリーなど）

主な機能：

• 豊富な設定オプションを備えた8種類の組み込み項目
• 2つのレイアウトモード：クラシック（複数行）と簡易（1行）
• 高度な機能：ファイルメニュー、バックステージ、コンテキストタブ、ギャラリー項目
• カスタマイズ可能なキーチップによるキーボードナビゲーション
• オーバーフロー処理を伴う自動レスポンシブリサイズ
• ユーザー操作に対応する充実したイベントシステム
• 必要な機能だけを読み込めるモジュールベースのアーキテクチャ

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

はじめに

📄 参照： references/getting-started.md

• Ribbon パッケージのインストール
• リボンの基本的な設定と初期化
• モジュールの挿入（デフォルトおよび選択的なモジュール）
• タブ、グループ、コレクション、項目の作成
• CSS のインポートとテーマの設定
• 複数のタブを使った最初の動作例

リボンのアーキテクチャ

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

• カスタムヘッダーを使ったタブの追加
• ヘッダーとアイコンを使ったグループの定義
• グループの配置（行レイアウトと列レイアウト）
• コレクションの追加と項目の整理
• グループランチャーアイコン（showLauncherIcon、カスタマイズ用のlauncherIconCss）
• 折りたたみ可能なグループと優先順位
• グループのオーバーフロー動作

組み込み項目

📄 参照： references/built-in-items.md

• ボタン項目（通常のボタンとトグルボタン）
• チェックボックス項目（ラベル、チェック状態、ラベルの位置）
• ドロップダウン項目（ターゲットコンテンツ、項目のカスタマイズ、必要に応じたポップアップ）
• スプリットボタン項目（主操作＋ドロップダウンメニュー）
• コンボボックス項目（データバインディング、フィルタリング、テンプレート）
• カラーピッカー項目（プリセットを使った色の選択）
• グループボタン項目（単一選択／複数選択）
• 項目の種類の比較と、それぞれの使いどころ

ギャラリー項目

📄 参照： references/gallery-items.md

• ギャラリーの概要とユースケース
• 項目のグループ化
• 項目のコンテンツ、アイコン、属性の定義
• ギャラリー項目の外観のカスタマイズ（cssClass）
• 特定のギャラリー項目の無効化
• グループヘッダーと項目の寸法の設定
• 表示する項目数の設定
• 項目の事前選択（selectedItemIndex）
• ポップアップの寸法の設定
• 項目とポップアップのカスタムテンプレート

レイアウトと表示

📄 参照： references/layouts.md

• クラシックレイアウト（複数行表示）
• 簡易レイアウト（1行表示）
• 項目サイズの定義（大、中、小）
• 項目に許可するサイズの設定
• 項目の配置（行と列）
• グループアイコンの設定とカスタマイズ
• ランチャーアイコンの有効化
• グループの折りたたみ状態と優先順位
• グループのオーバーフローポップアップの有効化
• 最小化状態（折りたたみ／展開）
• レイアウト切り替えボタンの表示／非表示
• タブのアニメーション設定

注： レイアウトの変更処理については、references/events-and-api.md の ribbonLayoutSwitched イベントを参照してください。

ファイルメニュー

📄 参照： references/file-menu.md

• ファイルメニューの表示と設定
• アイコン付きメニュー項目の追加
• クリック時のサブメニュー（showItemOnClick）
• ファイルメニューのヘッダーテキストのカスタマイズ
• メニュー項目のテンプレート
• ファイルメニューのイベント（beforeOpen、select、close）

バックステージメニュー

📄 参照： references/backstage.md

• バックステージの概要とユースケース
• コンテンツ付きバックステージ項目の追加
• フッター項目（isFooter プロパティ）
• 項目間への区切り線の追加
• 戻るボタンのカスタマイズ（テキスト、アイコン）
• バックステージのターゲット要素の設定
• カスタムレイアウト用のテンプレートの使用
• 幅と高さの設定
• バックステージのイベント（項目のクリック、開く、閉じる）

コンテキストタブ

📄 参照： references/contextual-tabs.md

• コンテキストタブの概要
• タブの表示／非表示の制御
• コンテキストタブの動的な追加
• 選択中のコンテキストタブの設定（isSelected）
• ユースケース（テーブル編集、画像編集、チャートツール）

キーチップ

📄 参照： references/keytips.md

• キーチップによるナビゲーションの有効化
• タブ、グループ、項目へのキーチップの割り当て
• キーチップの表示（Alt + Windows/Command キー）
• キーチップの内容のカスタマイズ
• キーチップによるナビゲーションの流れ

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

📄 参照： references/tooltip-and-help.md

• 項目へのツールチップタイトルの追加
• 説明を使ったツールチップ内容の設定
• ツールチップへのアイコンの追加
• ツールチップの外観のカスタマイズ（cssClass）
• ヘルプペインテンプレートの設定
• ヘルプペインの位置と内容

サイズ変更の動作

📄 参照： references/resizing.md

• クラシックモードでの自動サイズ変更
• 簡易モードでの自動サイズ変更
• 項目サイズの固定値の定義（allowedSizes）
• 項目の初期サイズの設定（activeSize）
• 項目サイズの遷移について

イベントと API

📄 参照： references/events-and-api.md

• タブ選択イベント（tabSelected、tabSelecting）
• リボンの展開／折りたたみイベント
• レイアウト切り替えイベント（ribbonLayoutSwitched - クラシック／簡易モードの変更に応答）
• ランチャーアイコンのクリックイベント
• オーバーフローポップアップイベント（open、close）
• Button、CheckBox、DropDown 項目のイベント
• SplitButton、ColorPicker、Gallery のイベント
• ComboBox のフィルタリングおよび選択イベント
• 共通 API メソッド（addTab、removeTab、addGroup、addItem など）
• 高度な API メソッド（selectTab、getItem、getRootElement、refreshLayout、updateTab/Group/Item/Collection）

クイックスタートの例

import { Ribbon, RibbonTabModel, RibbonItemType, RibbonFileMenu } from "@syncfusion/ej2-ribbon";
import { MenuItemModel } from "@syncfusion/ej2-navigations";

// Inject required modules
Ribbon.Inject(RibbonFileMenu);

// Define tabs with groups and items
let tabs: RibbonTabModel[] = [{
    header: "Home",
    groups: [{
        header: "Clipboard",
        collections: [{
            items: [{
                type: RibbonItemType.SplitButton,
                splitButtonSettings: {
                    iconCss: "e-icons e-paste",
                    content: "Paste",
                    items: [
                        { text: "Keep Source Format" },
                        { text: "Merge Format" },
                        { text: "Keep Text Only" }
                    ]
                }
            }]
        }, {
            items: [{
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Cut",
                    iconCss: "e-icons e-cut"
                }
            }, {
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Copy",
                    iconCss: "e-icons e-copy"
                }
            }]
        }]
    }]
}, {
    header: "Insert",
    groups: [{
        header: "Tables",
        collections: [{
            items: [{
                type: RibbonItemType.DropDown,
                dropDownSettings: {
                    iconCss: "e-icons e-table",
                    content: "Table",
                    items: [
                        { text: "Insert Table" },
                        { text: "Draw Table" }
                    ]
                }
            }]
        }]
    }]
}];

// Define file menu items
let fileMenuItems: 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" }
];

// Create Ribbon instance
let ribbon: Ribbon = new Ribbon({
    tabs: tabs,
    fileMenu: {
        menuItems: fileMenuItems,
        visible: true
    }
});

// Render to element
ribbon.appendTo("#ribbon");

よくあるパターン

タブを動的に追加する

// Add a new tab to existing ribbon
ribbon.addTab({
    header: "View",
    groups: [{
        header: "Views",
        collections: [{
            items: [{
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Print Layout",
                    iconCss: "e-icons e-print"
                }
            }]
        }]
    }]
});

レイアウトを切り替える

// Switch to Simplified layout
ribbon.activeLayout = "Simplified";

// Switch to Classic layout
ribbon.activeLayout = "Classic";

項目のクリックイベントを処理する

let tabs: RibbonTabModel[] = [{
    header: "Home",
    groups: [{
        header: "Actions",
        collections: [{
            items: [{
                type: RibbonItemType.Button,
                buttonSettings: {
                    content: "Save",
                    iconCss: "e-icons e-save",
                    clicked: () => {
                        console.log("Save button clicked");
                        // Your save logic here
                    }
                }
            }]
        }]
    }]
}];

コンテキストタブを有効にする

let ribbon: Ribbon = new Ribbon({
    tabs: tabs,
    contextualTabs: [{
        visible: true,
        isSelected: true,
        tabs: [{
            header: "Table Design",
            groups: [{
                header: "Styles",
                collections: [{
                    items: [{
                        type: RibbonItemType.Gallery,
                        gallerySettings: {
                            groups: [{
                                header: "Table Styles",
                                items: [
                                    { content: "Light" },
                                    { content: "Dark" }
                                ]
                            }]
                        }
                    }]
                }]
            }]
        }]
    }]
});

主なプロパティ

• tabs：タブ設定の配列（必須）
• activeLayout："Classic" | "Simplified"（デフォルト："Classic"）
• fileMenu：メニュー項目を含むファイルメニューの設定
• backStageMenu：項目とコンテンツを含む Backstage の設定
• contextualTabs：コンテキストタブ設定の配列
• enableKeyTips：キーチップによるナビゲーションの有効／無効（デフォルト：false）
• isMinimized：true の場合、タブヘッダーのみを表示（デフォルト：false）
• hideLayoutSwitcher：レイアウト切り替えボタンの表示／非表示（デフォルト：false）
• helpPaneTemplate：右側のヘルプペイン用カスタムテンプレート
• launcherIconCss：グループランチャーアイコン用の CSS クラス
• selectedTab：現在選択されているタブのインデックス（デフォルト：0）

よくあるユースケース

ユースケース 1：ドキュメントエディターのリボン

ユーザーがテキスト書式設定機能を備えたフル機能のドキュメントエディターを必要とする場合：

• Font、Paragraph、Styles の各グループを含む Home タブを作成する
• ComboBox を使ってフォントファミリーとサイズを選択する
• テキストの書式設定（太字、斜体、下線）用に GroupButton を追加する
• テキストとハイライトの色用に ColorPicker を含める
• Tables と Pictures の各グループを含む Insert タブを実装する
• 新規作成、開く、保存の操作用に File メニューを追加する

ユースケース 2：データグリッドアプリケーション

ユーザーがデータを重視したリボンインターフェースを必要とする場合：

• 基本操作（追加、編集、削除）用に Home タブを作成する
• インポート／エクスポート、フィルター、並べ替えの各グループを含む Data タブを追加する
• 定義済みのデータテンプレート用に Gallery 項目を使う
• 表示オプション（グリッドスタイル、ズーム）を含む View タブを実装する
• 行が選択されているときに表示するコンテキストタブを追加する
• コンパクトに表示するために簡易レイアウトを使う

ユースケース 3：コンテキストタブを備えたデザインツール

ユーザーがオブジェクト固有のコマンドを必要とする場合：

• 汎用ツール用の基本タブ（Home、Insert、View）を作成する
• 選択したオブジェクト用のコンテキストタブ（Image Tools、Shape Tools）を追加する
• スタイルのプリセットとテンプレート用に Gallery を使う
• ファイル操作と設定用にバックステージを実装する
• キーボード操作に慣れたユーザー向けにキーチップを有効にする
• 元に戻す／やり直しボタンを含むヘルプペインを追加する

ユースケース 4：モバイル対応アプリケーション

小さな画面でもリボンを動作させる必要がある場合：

• 簡易レイアウトをデフォルトとして使用します
• グループのオーバーフローポップアップを有効にします（enableGroupOverflow: true）
• インテリジェントな折りたたみのために項目の優先度を設定します
• 重要な項目に許可するサイズを定義します
• コンテンツ領域を最大限に確保するため、最小化状態を使用します
• 分析用にオーバーフローポップアップのイベントを実装します

ユースケース 5：キーボード主導のワークフロー

キーボードナビゲーションを優先する場合：

• キーチップを有効にします（enableKeyTips: true）
• すべてのタブ、グループ、項目に論理的なキーチップを割り当てます
• キーボードショートカットのヒントを含むツールチップを追加します
• キーボード操作のフィードバック用にタブ選択イベントを実装します
• 切り替え可能なオプションにはチェックボックス項目を使用します
• キーボードショートカット一覧を記載したヘルプペインを追加します