syncfusion-angular-ribbon

Syncfusion Angular Ribbon コンポーネント

コンポーネントの概要

Syncfusion Angular Ribbon は、Microsoft Office のようなタブ付きリボン形式でアプリケーションのコマンドを整理する、プロフェッショナルなコマンドインターフェイスコンポーネントです。次の機能を備えています。

• 階層的なコマンド構成： タブ → グループ → コレクション → アイテムの順に、論理的なコマンド構造を構成できます
• 7 種類の組み込みアイテム： Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Gallery
• 2 種類のレイアウトモード： クラシック（複数行）とシンプル（折りたたみ可能）に対応し、自動でサイズを調整します
• ファイルメニューとバックステージビュー： 従来型のファイルメニュー、またはドキュメント操作用の最新のバックステージインターフェイスを利用できます
• コンテキストタブ： ユーザーの選択や状況に応じて動的に表示されるタブです
• レスポンシブなサイズ調整： 使用可能な幅に合わせてアイテムのサイズ（Large、Medium、Small）を自動調整します
• キーボードナビゲーション： キーボード中心のワークフローに対応する、完全なキーチップサポートを備えています
• アクセシビリティ機能： ARIA 属性とスクリーンリーダーに対応し、WCAG に準拠しています
• RTL サポート： アラビア語、ヘブライ語、ペルシャ語、ウルドゥー語に対応した右から左へのレイアウトです
• ギャラリーアイテム： テーマ、スタイル、配色を視覚的に選択するパネルです
• ヘルプペイン： テンプレートに対応したカスタマイズ可能なヘルプペインです
• 高度なイベントシステム： タブの選択、折りたたみ／展開、ランチャーのクリック、アイテム操作に対応する包括的なイベントを備えています
• 高い設定自由度： 20 以上のリボンプロパティ、30 以上のアイテムプロパティ、10 以上のイベントを備えた幅広い API を提供します

主な概念と階層

重要な概念：

• タブ： 主な機能カテゴリー（Home、Insert、View）を整理します
• グループ： タブ内の関連するコマンド（Clipboard、Font、Alignment）をまとめます
• コレクション： グループ内のアイテムを視覚的にまとめ、整理しやすくします
• アイテム： 7 種類（Button、DropDown、ColorPicker など）の個別のコマンドです
• レイアウト： 自動切り替えに対応した、クラシック（複数行）またはシンプル（折りたたみ可能）なレイアウトです
• ファイルメニュー／バックステージ： アプリケーションレベルの操作（New、Open、Save、Print）を行います

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

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージの設定（Ivy と ngcc）
• CSS テーマのインポートと依存関係
• 最初の Ribbon の作成
• タブとグループの追加
• 基本的なアイテムとアプリケーションの実行

タブ、グループ、アイテムの構成

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

• タブの階層とプロパティ
• タブへのグループの追加
• Ribbon のコレクションとアイテム
• アイテムサイズの設定（Large、Medium、Small）
• 方向の設定（Row／Column）
• 複数のタブとグループの例

アイテムの種類と設定

📄 参照： references/item-types.md

• 7 種類の組み込みアイテムすべて
• Button アイテム（トグル、無効状態）
• CheckBox、DropDown、SplitButton アイテム
• ComboBox、ColorPicker、GroupButton アイテム
• 各種類の完全なコード例
• アイテム設定のモデルとプロパティ

Ribbon のレイアウトとサイズ調整

📄 参照： references/layouts.md

• クラシックレイアウト（デフォルトの複数行形式）
• シンプルレイアウト（折りたたみに対応）
• レイアウトの切り替え
• アイテムサイズの許容値と設定
• レスポンシブなサイズ調整の動作
• レイアウトの例とベストプラクティス

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

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

• ファイルメニューの設定と表示状態
• アイコンとアクションを指定したメニューアイテムの追加
• ファイルメニューの代替としてのバックステージビュー
• バックステージのアイテムとコンテンツ
• フッターアイテムと区切り線
• 戻るボタンのカスタマイズ
• ターゲット要素の配置
• ファイルメニューとバックステージの完全な例

高度な機能

📄 参照： references/advanced-features.md

• コンテキストタブ（動的なタブ作成）
• キーボード操作用のキーチップ
• 視覚的に選択できるギャラリー項目
• ヘルプペインのテンプレート
• ツールチップの設定
• サイズ変更時の動作とレスポンシブデザイン
• 右から左に記述する言語へのRTLサポート
• アクセシビリティ機能とWCAG準拠

イベントとインタラクティブ機能

📄 参照： references/events.md

• タブ選択イベント（tabSelected、tabSelecting）
• リボンの折りたたみ／展開イベント
• Backstage項目のクリックイベント
• イベント引数とキャンセル
• イベント処理のパターン
• イベントの完全な例

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

📄 参照： references/customization-and-styling.md

• CSSクラスのカスタマイズ
• テーマの統合と切り替え
• スタイル設定用のCSS変数
• スタイルのカスタマイズ例
• グループアイコンのカスタマイズ
• 項目のカスタマイズと外観
• ランチャーアイコンの使用

クイックスタートの例

ホームタブと挿入タブを備えた最小限のリボンの例を示します。

import { Component } from "@angular/core";
import { RibbonModule } from '@syncfusion/ej2-angular-ribbon';
import { RibbonButtonSettingsModel, RibbonSplitButtonSettingsModel } from '@syncfusion/ej2-angular-ribbon';

@Component({
  imports: [ RibbonModule ],
  standalone: true,
  selector: "app-root",
  template: `
    <ejs-ribbon id="ribbon">
      <e-ribbon-tabs>
        <e-ribbon-tab header="Home">
          <e-ribbon-groups>
            <e-ribbon-group header="Clipboard" orientation="Row">
              <e-ribbon-collections>
                <e-ribbon-collection>
                  <e-ribbon-items>
                    <e-ribbon-item type="SplitButton" [splitButtonSettings]="pasteSettings"></e-ribbon-item>
                  </e-ribbon-items>
                </e-ribbon-collection>
                <e-ribbon-collection>
                  <e-ribbon-items>
                    <e-ribbon-item type="Button" [buttonSettings]="cutButton"></e-ribbon-item>
                    <e-ribbon-item type="Button" [buttonSettings]="copyButton"></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="Illustrations" orientation="Row">
              <e-ribbon-collections>
                <e-ribbon-collection>
                  <e-ribbon-items>
                    <e-ribbon-item type="Button" [buttonSettings]="chartButton"></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>
  `,
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  public pasteSettings = { 
    iconCss: "e-icons e-paste", 
    items: [{ text: "Keep Source Format" }, { text: "Merge format" }], 
    content: "Paste" 
  };
  public cutButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-cut", content: "Cut" };
  public copyButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-copy", content: "Copy" };
  public chartButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-chart", content: "Chart" };
}

---

よくあるパターン

パターン1：複数タブのコマンドインターフェイス

1. 主要な機能（ホーム、挿入、表示、書式設定）ごとに複数のタブを定義します
2. 各タブ内に関連するコマンドのグループを追加します
3. コレクションを設定して項目を視覚的に整理します
4. 適切な項目タイプ（Button、DropDown、ColorPicker）を使用します
5. activeLayout をClassicまたはSimplifiedに設定します
6. タブ固有のアクションには tabSelected イベントを処理します

パターン2：Backstageを使用したファイルメニューの統合

1. ドキュメント操作用に fileMenu または backStageMenu を設定します
2. 新規作成、開く、保存、印刷、エクスポートのメニュー項目を追加します
3. Backstageのアイコンには iconCss を、コンテンツ領域にはコンテンツを設定します
4. イベントハンドラーでメニュー項目のクリックを処理します
5. 設定やアカウントのオプションにはフッター項目を使用します
6. Backstage内のナビゲーション用に戻るボタンを設定します

パターン3：サイズの優先順位を設定したレスポンシブなサイズ変更

1. 項目に allowedSizes 配列（Large、Medium、Small）を設定します
2. 初期表示サイズには activeSize を設定します
3. リボンは幅に応じて項目サイズを自動的に調整します
4. 主要なコマンドには Large を、補助的なコマンドには Small を使用します
5. カスタムのサイズ変更ロジックには ribbonCollapsing イベントを処理します
6. さまざまなビューポート幅でレスポンシブ動作をテストします

パターン4：動的なコマンド用のコンテキストタブ

1. タブ設定を含む contextualTabs 配列を定義します
2. ユーザーの選択やコンテキストに応じて visible プロパティを設定します
3. isSelected を使用して、コンテキストタブをプログラムから有効にします
4. コンテキストに応じたコマンド用に、タブ固有のグループと項目を追加します
5. コンテキストタブの有効化を検出するには tabSelected を処理します
6. ユーザー操作に応じて動的に表示を切り替えます

パターン5：キーチップを使ったキーボード操作

1. リボンコンポーネントで enableKeyTips を有効にします
2. タブに keyTip プロパティを割り当てます（ホームの場合はAlt+H）
3. グループと個々の項目にもキーチップを追加します
4. レイアウト切り替え用に layoutSwitcherKeyTip を設定します
5. ファイルメニューとBackstageの項目にキーチップを設定します
6. 一貫性のあるキーチップパターン（Alt+文字の組み合わせ）に従います

パターン6：視覚的な選択用のギャラリー項目

1. 視覚的なパネルには type="Gallery" を設定した項目を使用します
2. グループと項目を含む gallerySettings を定義します
3. 表示用に itemCount、popupWidth、popupHeight を設定します
4. カスタムのギャラリー項目のレンダリングにはテンプレートを使用します
5. ギャラリー項目のクリック時に選択イベントを処理します
6. よくある用途：テーマ、スタイル、色、表のデザイン

---

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

リボンの基本設定

プロパティ	型	デフォルト	使用する場面
tabs	RibbonTabModel[]	[]	グループと項目を含むリボンタブを定義します
activeLayout	LayoutType	'Classic'	レイアウトモード（ClassicまたはSimplified）を設定します
selectedTab	number	0	現在アクティブなタブのインデックスを設定または取得します
isMinimized	boolean	false	リボンの最小化状態を制御します

レイアウトと外観

プロパティ	型	デフォルト	使用する場面
width	string | number	'100%'	リボンコンテナーの幅を設定します
cssClass	string	''	スタイルやテーマ用のカスタム CSS クラスを適用します
hideLayoutSwitcher	boolean	false	クラシック／シンプルレイアウトの切り替えボタンを非表示にします
tabAnimation	object	null	タブ切り替えアニメーションの設定を行います

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

プロパティ	型	デフォルト	使用する場面
enableKeyTips	boolean	false	キーボード操作用のキーチップ（Alt+ショートカット）を有効にします
layoutSwitcherKeyTip	string	''	レイアウト切り替えボタンのキーチップを設定します
launcherIconCss	string	''	すべてのグループのランチャーアイコンに適用するデフォルトの CSS クラス

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

プロパティ	型	デフォルト	使用する場面
fileMenu	FileMenuSettingsModel	null	従来のファイルメニュー（新規、開く、保存、印刷）を設定します
backStageMenu	BackStageMenuModel	null	最新のバックステージビュー（ファイルメニューを置き換えます）を設定します

高度な機能

プロパティ	型	デフォルト	使用する場面
contextualTabs	RibbonContextualTabModel[]	[]	コンテキストや選択内容に応じて表示されるタブを定義します
helpPaneTemplate	string	''	ヘルプペインのコンテンツ用カスタムテンプレート

グローバリゼーション

プロパティ	型	デフォルト	使用する場面
locale	string	'en-US'	ローカライズ用の言語／地域設定を指定します
enableRtl	boolean	false	右から左へのレイアウト（アラビア語、ヘブライ語、ペルシア語、ウルドゥー語）を有効にします
enablePersistence	boolean	false	ページの再読み込み後もリボンの状態を保存します

タブの設定

プロパティ	型	デフォルト	使用する場面
header	string	''	タブの表示テキスト（ホーム、挿入、表示）
groups	RibbonGroupModel[]	[]	タブ内のグループの配列
id	string	''	タブの一意な識別子
keyTip	string	''	キーボードショートカットのキーチップ（ホームの場合は H）

グループの設定

プロパティ	型	デフォルト	使用する場面
header	string	''	グループの表示テキスト（クリップボード、フォント、配置）
orientation	ItemOrientation	'Column'	レイアウトの方向（行または列）
enableGroupOverflow	boolean	false	グループが収まらない場合にオーバーフロードロップダウンを表示します
isCollapsible	boolean	true	シンプルレイアウトでグループを折りたためるようにします
showLauncherIcon	boolean	false	ダイアログ／ペインを開くためのランチャーアイコンを表示します
groupIconCss	string	''	オーバーフロー／ランチャー内のグループアイコンに適用する CSS クラス

項目の設定

プロパティ	型	デフォルト	使用する場面
type	RibbonItemType	'Button'	項目の種類：Button、CheckBox、DropDown、SplitButton、ComboBox、ColorPicker、GroupButton、Gallery
id	string	''	項目の一意な識別子
allowedSizes	RibbonItemSize[]	['Large', 'Medium', 'Small']	項目をリサイズできるサイズ（レスポンシブ動作）
activeSize	RibbonItemSize	'Medium'	項目の現在の表示サイズ
disabled	boolean	false	ユーザー操作を防ぐために項目を無効にします
displayOptions	DisplayMode	'Auto'	表示を制御します（Auto、Classic、Simplified、Overflow）
cssClass	string	''	項目のスタイル設定に使用するカスタム CSS クラス
keyTip	string	''	項目のキーボードショートカット用キー ヒント
ribbonTooltipSettings	TooltipSettingsModel	null	ツールチップの設定（id、title、content、iconCss、cssClass）
itemTemplate	string	''	項目のレンダリングに使用するカスタムテンプレート
buttonSettings	RibbonButtonSettingsModel	null	ボタン固有の設定（iconCss、content、clicked）
dropDownSettings	RibbonDropDownSettingsModel	null	DropDown 固有の設定（iconCss、content、items）
splitButtonSettings	RibbonSplitButtonSettingsModel	null	SplitButton 固有の設定（iconCss、items、clicked）
checkBoxSettings	RibbonCheckBoxSettingsModel	null	CheckBox 固有の設定（label、checked、change）
colorPickerSettings	RibbonColorPickerSettingsModel	null	ColorPicker 固有の設定（value、change）
comboBoxSettings	RibbonComboBoxSettingsModel	null	ComboBox 固有の設定（dataSource、value、fields）
groupButtonSettings	RibbonGroupButtonSettingsModel	null	GroupButton 固有の設定（items、selected）
gallerySettings	RibbonGallerySettingsModel	null	Gallery の設定（groups、items、itemCount、popupWidth、popupHeight、template）

ファイルメニューの設定

プロパティ	型	デフォルト	使用する場面
visible	boolean	false	ファイルメニューボタンの表示／非表示
text	string	'File'	ファイルメニューボタンのテキスト
menuItems	FileMenuItemModel[]	[]	メニュー項目の配列（New、Open、Save、Print）
itemTemplate	string	''	メニュー項目に使用するカスタムテンプレート
popupTemplate	string	''	ポップアップ全体に使用するカスタムテンプレート
keyTip	string	''	ファイルメニューのキー ヒント（File の F）
ribbonTooltipSettings	TooltipSettingsModel	null	ファイルメニューボタンのツールチップ設定

Backstage の設定

プロパティ	型	デフォルト	使用する場面
visible	boolean	false	Backstage ビューの表示／非表示
text	string	'File'	Backstage ボタンのテキスト
items	BackStageItemModel[]	[]	Backstage 項目（id、text、iconCss、content、separator、isFooter）
backButton	BackButtonModel	null	戻るボタンの設定（text、iconCss、visible）
width	string	'auto'	Backstage の幅
height	string	'auto'	Backstage の高さ
target	HTMLElement	null	Backstage の位置を決める要素
template	string	''	Backstage コンテンツに使用するカスタムテンプレート
keyTip	string	''	Backstage ボタンのキー ヒント
ribbonTooltipSettings	TooltipSettingsModel	null	Backstage ボタンのツールチップ設定

コンテキストタブの設定

プロパティ	型	デフォルト	使用する場面
visible	boolean	false	コンテキストタブグループの表示／非表示
isSelected	boolean	false	コンテキストタブがアクティブかどうか
tabs	RibbonTabModel[]	[]	コンテキストグループ内のタブの配列

主なイベント

イベント	引数	使用するタイミング
(tabSelected)	TabSelectedEventArgs	タブの選択後（タブのインデックスとデータを取得）
(tabSelecting)	TabSelectingEventArgs	タブの選択前（キャンセル可能、選択を検証）
(ribbonCollapsing)	RibbonCollapsingEventArgs	リボンの折りたたみ前（キャンセル可能）
(ribbonExpanded)	RibbonExpandedEventArgs	リボンの展開後
(launcherClick)	LauncherClickEventArgs	ランチャーアイコンのクリック時（ダイアログ／ペインを開く）
(overflowPopupOpen)	OverflowPopupEventArgs	オーバーフローポップアップが開く前（キャンセル可能）
(overflowPopupClose)	OverflowPopupEventArgs	オーバーフローポップアップが閉じる前（キャンセル可能）
(layoutSwitched)	LayoutSwitchedEventArgs	レイアウトがクラシック／簡易の間で切り替わるとき
(backStageItemClick)	BackStageItemClickEventArgs	バックステージ項目のクリック時

ファイルメニューのイベント

イベント	引数	使用するタイミング
beforeOpen	BeforeOpenCloseMenuEventArgs	ファイルメニューが開く前（キャンセル可能）
open	OpenCloseMenuEventArgs	ファイルメニューが開いた後
beforeClose	BeforeOpenCloseMenuEventArgs	ファイルメニューが閉じる前（キャンセル可能）
close	OpenCloseMenuEventArgs	ファイルメニューが閉じた後
beforeItemRender	MenuEventArgs	メニュー項目の描画前（描画をカスタマイズ）
select	MenuEventArgs	メニュー項目の選択時

---