syncfusion-blazor-ribbon

Syncfusion Blazor Ribbon コンポーネント

Syncfusion Blazor Ribbon コンポーネントを使用して、プロフェッショナルな Office スタイルのリボンインターフェイスを構築できます。このスキルでは、Blazor アプリケーション向けの Ribbon の実装、構成、カスタマイズに関する包括的なガイダンスを提供します。

コンポーネントの概要

Ribbon は、コマンドやツールをタブ、グループ、コレクションに整理する Microsoft Office スタイルの UI コンポーネントです。さまざまな種類の項目、ファイルメニュー、豊富なカスタマイズオプションに対応し、アプリケーションの機能を直感的に操作できるインターフェイスを提供します。

主な概念

• タブ：最上位のナビゲーションコンテナー（ホーム、挿入、デザインなど）
• グループ：タブ内の関連項目を論理的にまとめたもの（クリップボード、フォント、配置）
• コレクション：グループ内の項目を整理するもの（縦または横）
• 項目：個々のコントロール（ボタン、ドロップダウン、チェックボックス、カラーピッカーなど）
• ファイルメニュー：ファイル操作（新規作成、開く、保存）用の特別なドロップダウンメニュー
• ギャラリー：関連項目のビジュアルコレクションを表示するもの（スタイル、テーマ、デザイン）
• コンテキストタブ：選択したオブジェクトやコンテキストに応じて動的に表示されるタブ
• Backstage ビュー：ファイル操作やアプリケーション設定用の全画面メニュー
• KeyTips：アクセシビリティと生産性を高めるキーボードショートカット

Ribbon の構造

SfRibbon (Main Container)
├── RibbonFileMenuSettings (Optional File Menu)
└── RibbonTabs
    └── RibbonTab (Home, Insert, Design...)
        └── RibbonGroups
            └── RibbonGroup (Clipboard, Font...)
                └── RibbonCollections
                    └── RibbonCollection (Row/Column Layout)
                        └── RibbonItems
                            └── RibbonItem (Button, Dropdown, etc.)

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

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージのセットアップ
• 名前空間のインポートとサービスの登録
• テーマの構成
• 最初のタブとグループを使った基本的な Ribbon の初期化
• 最小限の動作するサンプル

Ribbon の構造とレイアウト

📄 参照： references/ribbon-structure.md

• タブの整理と構成
• 向きを制御したグループの作成
• コレクションの階層と行／列のレイアウト
• 項目定義の基本
• 整理に関するベストプラクティス

Ribbon 項目：基本タイプ

📄 参照： references/ribbon-items-basic.md

• クリックハンドラーを備えたボタン項目
• 切り替え状態を備えたチェックボックス項目
• メニューオプションを備えたドロップダウン項目
• ボタンとメニューを組み合わせたスプリットボタン項目
• 無効化された項目と項目のサイズ設定

Ribbon 項目：高度なタイプ

📄 参照： references/ribbon-items-advanced.md

• データバインディングとフィルタリングを備えたコンボボックス項目
• 色を選択するカラーピッカー項目
• 複数選択／単一選択モードを備えたグループボタン項目
• カスタム HTML コンテンツ用のテンプレート項目
• レイアウトに応じた表示を設定する DisplayOptions

ファイルメニューの構成

📄 参照： references/file-menu.md

• ファイルメニューの有効化と構成
• メニュー項目とネストされたサブメニューの追加
• サブメニューの動作（ホバーとクリック）
• カスタムヘッダーテキスト
• ファイルメニューのイベント

イベントと操作

📄 参照： references/events.md

• コンポーネントレベルのイベント（Created、TabSelecting、TabSelected）
• Ribbon の状態イベント（Expanding、Collapsing）
• 項目のクリックイベントと選択イベント
• ランチャーアイコンとオーバーフローポップアップのイベント
• イベントハンドラーのパターンとサンプル

ギャラリー項目

📄 参照： references/gallery.md

• 関連項目のコレクションを表示するギャラリービュー
• カスタムヘッダーを備えたギャラリーグループ
• 項目の寸法とスタイル設定
• 項目数の構成
• 選択項目のインデックス管理
• ポップアップの寸法のカスタマイズ
• ギャラリー項目のテンプレートのカスタマイズ

コンテキストタブ

📄 参照： references/contextual-tabs.md

• タブの表示を動的に制御
• コンテキストタブの構成
• タブの選択状態の管理
• タブを表示および非表示にするメソッド
• コンテキストに応じた UI 要素

バックステージビュー

📄 参照： references/backstage.md

• バックステージメニューの設定
• メニュー項目とフッター項目
• バックステージの区切り線
• 戻るボタンのカスタマイズ
• バックステージテンプレートのカスタマイズ
• 幅と高さの設定
• バックステージのイベント

キーボードナビゲーションとキーチップ

📄 参照： references/keytips.md

• リボン項目のキーチップ
• ファイルメニューのキーチップ
• バックステージメニューのキーチップ
• レイアウト切り替えのキーチップ
• ランチャーアイコンのキーチップ
• ShowKeyTips および HideKeyTips メソッド
• キーチップのベストプラクティスとガイドライン

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

📄 参照： references/customization.md

• テーマの選択と適用
• 項目のサイズとレイアウトのオプション
• CSS のカスタマイズとクラスの適用
• RTL（右から左）表示のサポート
• オーバーフロー処理とグループの折りたたみ

アクセシビリティ

📄 参照： references/accessibility.md

• WCAG 2.1 への準拠と標準
• キーボードナビゲーション（Tab、Enter、Space、矢印キー）
• ARIA 属性とセマンティックマークアップ
• スクリーンリーダーのサポート
• フォーカス管理と視覚的なインジケーター

クイックスタートの例

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Ribbon
@using Syncfusion.Blazor.SplitButtons

<div style="width: 100%">
    <SfRibbon>
        <RibbonTabs>
            <RibbonTab HeaderText="Home">
                <RibbonGroups>
                    <RibbonGroup HeaderText="Clipboard" Orientation="Orientation.Row">
                        <RibbonCollections>
                            <RibbonCollection>
                                <RibbonItems>
                                    <RibbonItem Type="RibbonItemType.SplitButton">
                                        <RibbonSplitButtonSettings Content="Paste" IconCss="e-icons e-paste" Items="@pasteOptions">
                                        </RibbonSplitButtonSettings>
                                    </RibbonItem>
                                </RibbonItems>
                            </RibbonCollection>
                            <RibbonCollection>
                                <RibbonItems>
                                    <RibbonItem Type="RibbonItemType.Button">
                                        <RibbonButtonSettings Content="Cut" IconCss="e-icons e-cut" OnClick="@OnCut">
                                        </RibbonButtonSettings>
                                    </RibbonItem>
                                    <RibbonItem Type="RibbonItemType.Button">
                                        <RibbonButtonSettings Content="Copy" IconCss="e-icons e-copy" OnClick="@OnCopy">
                                        </RibbonButtonSettings>
                                    </RibbonItem>
                                </RibbonItems>
                            </RibbonCollection>
                        </RibbonCollections>
                    </RibbonGroup>
                </RibbonGroups>
            </RibbonTab>
        </RibbonTabs>
    </SfRibbon>
</div>

@code {
    private List<DropDownMenuItem> pasteOptions = new List<DropDownMenuItem>()
    {
        new DropDownMenuItem{ Text = "Keep Source Format" },
        new DropDownMenuItem{ Text = "Merge Format" },
        new DropDownMenuItem{ Text = "Keep Text Only" }
    };

    private void OnCut(MouseEventArgs args) { /* Handle cut action */ }
    private void OnCopy(MouseEventArgs args) { /* Handle copy action */ }
}

よくあるパターン

1. 複数タブのリボン

関連する機能を、異なるコマンドを含む個別のタブに整理します：

<SfRibbon>
    <RibbonTabs>
        <RibbonTab HeaderText="Home"></RibbonTab>
        <RibbonTab HeaderText="Insert"></RibbonTab>
        <RibbonTab HeaderText="Design"></RibbonTab>
    </RibbonTabs>
</SfRibbon>

2. コマンドのグループ化

関連する項目をグループ化して、整理と UI レイアウトを改善します：

<RibbonTab HeaderText="Home">
    <RibbonGroups>
        <RibbonGroup HeaderText="Clipboard"></RibbonGroup>
        <RibbonGroup HeaderText="Font"></RibbonGroup>
        <RibbonGroup HeaderText="Paragraph"></RibbonGroup>
    </RibbonGroups>
</RibbonTab>

3. ファイルメニューの統合

ファイル操作メニューを含めます：

<SfRibbon>
    <RibbonFileMenuSettings Visible="true" MenuItems="@fileMenuItems">
    </RibbonFileMenuSettings>
    <RibbonTabs></RibbonTabs>
</SfRibbon>

4. データバインドされたコンボボックス

ドロップダウンをデータソースにバインドします：

<RibbonItem Type="RibbonItemType.ComboBox">
    <RibbonComboBoxSettings DataSource="@fontFamilies" 
                             FieldSettings="@fieldSettings"
                             AllowFiltering="true">
    </RibbonComboBoxSettings>
</RibbonItem>

5. トグルボタン

選択状態と未選択状態を持つボタンを作成します：

<RibbonItem Type="RibbonItemType.GroupButton">
    <RibbonGroupButtonSettings Selection="GroupButtonSelection.Single" Items="@alignmentOptions">
    </RibbonGroupButtonSettings>
</RibbonItem>

主なプロパティと設定

コンポーネントレベル

• Tabs：RibbonTab オブジェクトのコレクション
• FileMenuSettings：ファイルメニューの表示と項目を設定します
• Created：リボンの初期化時に発生するイベント

タブレベル

• HeaderText：ユーザーに表示されるタブ名
• Visible：タブを動的に表示／非表示にします

グループレベル

• HeaderText：グループのラベル
• Orientation：Row または Column のレイアウト
• PopupHeaderText：オーバーフローポップアップ内のテキスト（EnableGroupOverflow=true の場合）

項目レベル

• Type：Button、Checkbox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Template
• Disabled：個々の項目を無効にします
• DisplayOptions：Auto、Classic、Simplified、Overflow
• AllowedSizes：Small、Medium、Large

よくある使用例

1. ドキュメントエディター

ファイル操作、書式設定、スタイルコントロールを備えたワープロのリボンを構築します。

2. スプレッドシートアプリケーション

数式、データ分析、セルの書式設定を備えたスプレッドシートのリボンを作成します。

3. デザインツール

描画ツール、色、オブジェクト操作機能を備えたデザインアプリケーションのリボンを実装します。

4. コンテンツ管理システム

公開オプション、コンテンツ整理、ワークフロー制御機能を備えた CMS のリボンを設計します。

5. 管理ダッシュボード

ユーザー管理、設定、システム制御機能を備えた管理ツールのリボンを作成します。

6. メールクライアント

メッセージ操作（返信、転送、削除、アーカイブ）を備えたメールのリボンを構築します。

7. メディアエディター

編集ツール、エフェクト、エクスポートオプションを備えた画像／動画エディターのリボンを実装します。

インストールの前提条件

• .NET 6.0 以上
• Blazor Server または WebAssembly プロジェクト
• Syncfusion.Blazor.Ribbon NuGet パッケージ
• Syncfusion.Blazor.Themes NuGet パッケージ

テーマのサポート

利用可能なテーマ：

• Bootstrap 5（デフォルト）
• Material Design
• Fluent UI（Microsoft）
• Tailwind CSS
• Fabric Office
• Material Dark

テーマは、index.html または App.razor で CSS をインポートして適用します。

パフォーマンスに関する考慮事項

• 特定のレイアウトで不要な項目を非表示にするには、DisplayOptions を使用します
• 複雑な項目設定には遅延読み込みを実装します
• 画面サイズが小さい場合は、オーバーフロー処理を検討します
• 過剰なレンダリングを避けるため、テンプレートは適切に使用します

ブラウザーのサポート

• Chrome（最新）
• Firefox（最新）
• Safari（最新）
• Edge（最新）
• モバイルブラウザー（レスポンシブ）

キーボード操作

• Tab：タブ間を移動します
• Enter/Space：項目を選択するか、メニューを開きます
• 矢印キー：グループ内や項目間を移動します
• Escape：開いているメニューやポップアップを閉じます

関連コンポーネント

• Toolbar - 基本的なツールバー向けの、よりシンプルな代替コンポーネント
• Menu - 単独で使用できるメニューコンポーネント
• TabsComponent - リボン形式を使わないタブ付きコンテンツ
• AppBar - アプリケーションのヘッダーバー

トラブルシューティングのヒント

リボンが表示されない場合：

• NuGet パッケージがインストールされていることを確認します
• _Imports.razor の名前空間インポートを確認します
• Program.cs でサービスが登録されていることを確認します

項目が表示されない場合：

• タブと項目の Visible プロパティを確認します
• DisplayOptions の設定を確認します
• Disabled プロパティが true に設定されていないことを確認します

スタイルの問題がある場合：

• テーマ CSS が index.html で参照されていることを確認します
• 競合する CSS ルールがないか確認します
• CssClass プロパティの構文を確認します

イベントが発生しない場合：

• イベントハンドラーが @ を付けてバインドされていることを確認します
• パラメーターの型がイベント引数と一致しているか確認します
• コンポーネントのライフサイクルを確認します（初期化には Created イベントを使用します）

次のステップ

1. Getting Started から始めて、コンポーネントをインストールし、セットアップします
2. Ribbon Structure を学び、タブ、グループ、項目の構成を理解します
3. Item Types（Basic と Advanced）を確認し、さまざまなコントロールのオプションを把握します
4. ファイル操作用に File Menu を追加します
5. ユーザー操作に対応する Events を実装します
6. 本番アプリ向けに Styling と Accessibility でカスタマイズします

詳しくは、Syncfusion Blazor Ribbon の公式ドキュメントをご覧ください。