syncfusion-aspnetcore-ribbon

Syncfusion ASP.NET Core Ribbon コントロール

概要

Razor Tag Helpers を使用して、ASP.NET Core アプリケーションに Syncfusion EJ2 Ribbon コンポーネントを実装するための包括的なスキルです。このスキルでは、インストール、セットアップ、コンポーネント構造、すべてのアイテムタイプ、イベント、テーマ、高度な機能について説明します。Ribbon コンポーネントは、次の機能を備えた多機能なナビゲーションコントロールです。

• タブとグループでコマンドを整理 - 論理的にグループ化されたタブインターフェイス
• 7 種類のアイテムタイプに対応 - Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton
• ファイルメニューと Backstage を提供 - 従来型のファイルメニュー、またはモダンな Backstage ビュー
• 必要に応じて表示されるコンテキストタブ - 必要なときにタブが表示されます（例：画像やテーブルを選択したとき）
• ギャラリーアイテム - スタイル、テンプレート、オプションを視覚的に選択
• レスポンシブレイアウト - Classic（複数行）モードと Simplified（コンパクト）モード
• キーボードナビゲーション - Alt キーとの組み合わせでショートカットを実行する KeyTips
• WCAG 2.1 準拠 - ARIA による完全なアクセシビリティ対応
• 組み込みテーマ - Material、Bootstrap、Fluent、Tailwind、Fabric

ナビゲーションガイド

はじめに

📄 参照先： references/getting-started.md

• NuGet パッケージのインストール
• _ViewImports.cshtml での Tag Helper の登録
• _Layout.cshtml での CSS とスクリプトの設定
• セットアップ一式を含む最初の動作例
• 利用可能なテーマ（Material、Bootstrap、Fluent、Tailwind、Fabric）
• 高度な機能の登録（ASP.NET Core では個別のモジュール注入は不要）
• locale プロパティによるローカライズ
• enablePersistence による状態の永続化

Ribbon の構造

📄 参照先： references/ribbon-structure.md

• コンポーネント階層（Ribbon → Tab → Group → Collection → Item）
• <e-ribbon-tab> によるタブの追加
• <e-ribbon-group> によるグループの追加
• コレクションとアイテムの追加
• Ribbon のコンテンツの整理
• 構造に関するベストプラクティス

アイテムとグループの設定

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

• 7 種類すべてのアイテムタイプ（Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Template）
• 各タイプの正確な RibbonXxxSettings 設定
• グループのプロパティ（header、collapsibility、priority、overflow）
• アイテムのサイズ（Large、Medium、Small）
• 表示オプション（Auto、Classic、Simplified、Overflow）
• 無効状態

タブとグループの管理

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

• タブの管理パターン
• 複数タブのセットアップ例
• グループの整理
• 折りたたみの制御（isCollapsible）
• 優先度の処理（値が大きいほど先に折りたたまれます）
• ランチャーアイコン
• グループのオーバーフロー動作

レイアウトと表示モード

📄 参照先： references/layouts-display-modes.md

• Classic レイアウト（デフォルト、複数行）
• Simplified レイアウト（コンパクト、1 行）
• レイアウトの切り替え
• レスポンシブなサイズ変更の動作
• アイテムサイズの変化（Large → Medium → Small）
• 最小化状態
• レイアウト切り替えオプションの非表示

ファイルメニューと Backstage

📄 参照先： references/file-menu-backstage.md

• ファイルメニューの基本（<e-ribbon-filemenusettings>）
• MenuItem リストによるメニューアイテムの設定
• Backstage ビュー（<e-ribbon-backstagemenusettings>）
• コンテンツを含む Backstage アイテム
• フッターアイテムと区切り線
• 戻るボタンのカスタマイズ

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

📄 参照先： references/contextual-tabs-gallery.md

• 必要に応じて表示されるコンテキストタブ
• 条件による表示の制御
• ギャラリーアイテム（type=Gallery）
• ヘッダー付きのギャラリーグループ
• ギャラリーアイテムのプロパティ（content、iconCss、disabled）
• 視覚的な選択パターン

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

📄 参照先： references/events-accessibility.md

• リボンイベント（tabSelected、tabSelecting、itemClick など）
• KeyTips の設定（enableKeyTips、keyTip プロパティ）
• キーボードナビゲーション
• WCAG 2.1 への準拠
• ARIA 属性のサポート
• RTL のサポート（enableRtl）

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

📄 参照先： references/customization-theming.md

• 組み込みテーマの一覧（5 種類）
• テーマ CSS のインポートパス
• テーマ切り替えの実装
• CSS カスタマイズクラス
• ダークモードのサポート
• カスタムアイコンとスタイル設定

ツールチップとヘルプ

📄 参照先： references/tooltips-help-pane.md

• RibbonTooltipSettings を使用した項目のツールチップ
• タイトルとコンテンツのプロパティ
• カスタムツールチップ HTML
• ヘルプペインのコンポーネントパターン
• コンテキストに応じたヘルプの実装

メソッドとプロパティ

📄 参照先： references/methods-and-properties.md

• リボンのメソッド（getComponent、destroy）
• キーイベントとコールバック
• プロパティへのアクセスパターン
• プログラムによる制御
• 状態管理

トラブルシューティング

📄 参照先： references/troubleshooting.md

• よくある問題と解決策
• タグヘルパーの登録に関する問題
• データバインディングの問題
• イベント処理のトラブルシューティング
• パフォーマンスの最適化
• スタイル設定の問題
• ASP.NET Core 固有の注意点

主なプロパティとイベント

必須プロパティ：

• id - リボンの一意な識別子
• activeLayout - Classic または Simplified に設定します
• isMinimized - リボンを折りたたむ／展開する（true/false）
• enableKeyTips - キーボードショートカットを有効にする（true/false）
• enableRtl - 右から左への表示をサポートする（true/false）
• hideLayoutSwitcher - レイアウト切り替えボタンを非表示にする（true/false）
• layoutSwitcherKeyTip - レイアウト切り替えボタンの KeyTip 文字
• helpPaneTemplate - 右側のヘルプペインに使用する CSS セレクターまたは HTML 文字列
• enablePersistence - ページの再読み込み後もリボンの状態を保持する（true/false）
• locale - 組み込み UI テキストのロケール文字列（例："en-us"、"fr-FR"）

主なイベント：

• created - コンポーネントの作成後に発生します
• tabSelected - タブの選択後に発生します（args.selectedIndex、args.previousIndex、args.isContextual）
• tabSelecting - タブの選択前に発生します（選択を防ぐには args.cancel を使用し、args.isInteracted で操作の有無を確認します）
• ribbonCollapsing - リボンが折りたたまれる前に発生します（折りたたみを防ぐには args.cancel を使用します）
• ribbonExpanding - リボンが展開される前に発生します（展開を防ぐには args.cancel を使用します）
• ribbonLayoutSwitched - レイアウトの切り替え後に発生します（args.activeLayout）
• launcherIconClick - グループのランチャーアイコンがクリックされたときに発生します（args.groupId）
• overflowPopupOpen - オーバーフローポップアップが開いたときに発生します（args.element、args.cancel）
• overflowPopupClose - オーバーフローポップアップが閉じたときに発生します（args.element、args.cancel）

クイックスタート

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

@using Syncfusion.EJ2
@using Syncfusion.EJ2.Ribbon
@using Syncfusion.EJ2.Navigations

<ejs-ribbon id="ribbon">
    <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
            <e-ribbon-groups>
                <e-ribbon-group header="Clipboard">
                    <e-ribbon-collections>
                        <e-ribbon-collection>
                            <e-ribbon-items>
                                <e-ribbon-item type=Button>
                                    <e-ribbon-buttonsettings iconCss="e-icons e-paste" content="Paste"></e-ribbon-buttonsettings>
                                </e-ribbon-item>
                            </e-ribbon-items>
                        </e-ribbon-collection>
                    </e-ribbon-collections>
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
        <e-ribbon-tab header="Insert">
            <e-ribbon-groups>
                <e-ribbon-group header="Tables">
                    <e-ribbon-collections>
                        <e-ribbon-collection>
                            <e-ribbon-items>
                                <e-ribbon-item type=Button>
                                    <e-ribbon-buttonsettings iconCss="e-icons e-table" content="Table"></e-ribbon-buttonsettings>
                                </e-ribbon-item>
                            </e-ribbon-items>
                        </e-ribbon-collection>
                    </e-ribbon-collections>
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
    </e-ribbon-tabs>
</ejs-ribbon>

ファイルメニューを使用する場合

@{
    List<MenuItem> fileOptions = new List<MenuItem>() {
        new MenuItem { Text = "New", IconCss = "e-icons e-file-new" },
        new MenuItem { Text = "Open", IconCss = "e-icons e-folder-open" },
        new MenuItem { Text = "Save", IconCss = "e-icons e-save" }
    };
}

<ejs-ribbon id="ribbon">
    <e-ribbon-filemenusettings visible="true" menuItems=fileOptions></e-ribbon-filemenusettings>
    <e-ribbon-tabs>
        
    </e-ribbon-tabs>
</ejs-ribbon>

よく使われるパターン

パターン：複数のグループを含む複数タブのリボン

<ejs-ribbon id="ribbon">
    <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
            <e-ribbon-groups>
                <e-ribbon-group header="Clipboard" orientation=Row>
                    
                </e-ribbon-group>
                <e-ribbon-group header="Font" orientation=Row enableGroupOverflow=true>
                    
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
        <e-ribbon-tab header="View">
            <e-ribbon-groups>
                <e-ribbon-group header="Views" orientation=Row>
                    
                </e-ribbon-group>
            </e-ribbon-groups>
        </e-ribbon-tab>
    </e-ribbon-tabs>
</ejs-ribbon>

パターン：グループ内の複数の項目タイプ

@{
    List<string> fontOptions = new List<string>() { "Arial", "Calibri", "Cambria", "Georgia" };
}

<e-ribbon-group header="Formatting">
    <e-ribbon-collections>
        <e-ribbon-collection>
            <e-ribbon-items>
                
                <e-ribbon-item type=ComboBox>
                    <e-ribbon-comboboxsettings dataSource=fontOptions index=0 width="120px"></e-ribbon-comboboxsettings>
                </e-ribbon-item>
                
                <e-ribbon-item type=ColorPicker allowedSizes=Small>
                    <e-ribbon-colorpickersettings value="#123456"></e-ribbon-colorpickersettings>
                </e-ribbon-item>
                
                <e-ribbon-item type=Button allowedSizes=Small>
                    <e-ribbon-buttonsettings iconCss="e-icons e-bold" isToggle=true></e-ribbon-buttonsettings>
                </e-ribbon-item>
            </e-ribbon-items>
        </e-ribbon-collection>
    </e-ribbon-collections>
</e-ribbon-group>

パターン：イベント処理

<ejs-ribbon id="ribbon"
    tabSelected="onTabSelected"
    tabSelecting="onTabSelecting"
    ribbonLayoutSwitched="onLayoutSwitched"
    launcherIconClick="onLauncherClick">
    
</ejs-ribbon>

<script>
    function onTabSelected(args) {
        console.log('Tab selected:', args.selectedIndex);
        console.log('Previous tab:', args.previousIndex);
        console.log('Is contextual:', args.isContextual);
    }

    function onTabSelecting(args) {
        console.log('Tab selecting:', args.selectedIndex);
        // args.cancel = true; // Prevent selection if needed
    }

    function onLayoutSwitched(args) {
        console.log('Layout changed to:', args.activeLayout); // 'Classic' or 'Simplified'
    }

    function onLauncherClick(args) {
        console.log('Launcher clicked for group:', args.groupId);
    }
</script>

ワークフローパターン

ユーザーがリボン機能を必要としている場合：

1. 範囲を特定する：タブの構成、項目の種類、ファイルメニュー、必要なイベントを確認します
2. 「Getting Started」から始める：インストールと基本設定を行います
3. 機能に応じてリファレンスを選ぶ：
   • 項目の設定 → items-and-groups.md
   • レイアウト／レスポンシブ表示 → layouts-display-modes.md
   • ファイルメニュー → file-menu-backstage.md
   • キーボード／アクセシビリティ → events-accessibility.md
   • 外観と操作感 → customization-theming.md
4. コピーして使用できるサンプルに従ってパターンを実装する
5. 問題をデバッグする → troubleshooting.md

---