syncfusion-angular-toolbar

Syncfusion Angular Toolbar の実装

レスポンシブなオーバーフロー処理と豊富なカスタマイズオプションを備えた、横方向に並ぶコマンドボタンのグループを表示します。

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• 横並びのツールバーレイアウトにアクションボタンを作成する
• ボタングループの間に区切り線を追加する
• 入力コンポーネント（NumericTextBox、DropDownList、CheckBox）を埋め込む
• CSS と Font Awesome アイコンでスタイルをカスタマイズする
• クリックイベントとコマンド操作を処理する
• ツールバー項目にカスタムテンプレートとコンポーネントを描画する
• ツールバーコマンドのツールチップを設定する
• ツールバー項目としてルーティングリンクを追加する
• 状態管理付きのトグルボタンを作成する
• レスポンシブなスクロールモードまたはポップアップオーバーフローモードを実装する
• キーボード操作に対応したアクセシブルなツールバーを構築する

Toolbar の概要

Syncfusion Angular Toolbar は、横方向に並ぶコマンドボタンのコレクションを表示するコンテナーコンポーネントです。複数の項目タイプ（ボタン、区切り線、入力）、カスタムテンプレート、スタイル設定、レスポンシブ動作、アクセシビリティ機能に対応しています。

主な機能：

• ボタン項目： テキスト、アイコン、スタイルを設定できるデフォルトの項目タイプ
• 区切り線： コマンドグループ間の縦方向の区切り
• 入力コンポーネント： NumericTextBox、DropDownList、CheckBox、RadioButton を埋め込み可能
• テンプレート対応： Angular コンポーネントとカスタム HTML を描画
• レスポンシブモード： スクロール（デフォルト）とポップアップによるオーバーフロー処理
• カスタムスタイル： CSS によるカスタマイズ、Font Awesome との統合、テーマ
• ツールチップ： すべてのコマンドに対し、マウスホバー時にヒントテキストを表示
• リンク： ルーティングリンクとアンカー要素を埋め込み可能
• トグルボタン： 再生／一時停止、表示／非表示の機能を備えた状態管理可能なボタン
• キーボード操作： Tab キーに対応し、矢印キーで移動可能
• RTL 対応： テキストとレイアウト方向を右から左に設定可能
• アクセシビリティ： ARIA 属性による WCAG 準拠

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

はじめに

📄 参照： references/getting-started.md

• @syncfusion/ej2-angular-navigations パッケージをインストールする
• Angular 環境と依存関係を設定する
• コンポーネントに ToolbarModule をインポートする
• テーマの CSS をインポートする
• ボタン項目を含む基本的なツールバーを作成する
• アプリケーションを実行してテストする

項目の設定

📄 参照： references/item-configuration.md

• ボタン項目のプロパティ（text、id、prefixIcon、suffixIcon、width、align）を設定する
• コマンドをグループ化するための区切り線項目を追加する
• Input タイプの項目（NumericTextBox、DropDownList、CheckBox、RadioButton）を設定する
• tabIndex プロパティを使用して Tab キーによるナビゲーションを有効にする
• 項目を動的に管理、更新する

スタイルとカスタマイズ

📄 参照： references/styling-customization.md

• CSS でツールバーコンテナーのスタイルをカスタマイズする
• ツールバー項目とボタンのスタイルを設定する
• アイコンとアイコンの色をカスタマイズする
• ホバー時とフォーカス時のスタイルを適用する
• Font Awesome のサードパーティ製アイコンを統合する
• CSS クラスをカスタマイズする（e-toolbar、e-toolbar-item、e-tbar-btn）
• e-icons クラスでアイコンの位置を設定する

コマンドイベントとカスタマイズ

📄 参照： references/command-events.md

• ツールバー項目のクリックイベントハンドラーを実装する
• htmlAttributes プロパティでカスタム HTML 属性を使用する
• cssClass プロパティで複数の CSS クラスを適用する
• id、class、style、role 属性を使ってコマンドをカスタマイズする
• ツールバー操作にイベント駆動型のパターンを適用する
• 項目ごとのアクションと応答を処理する

項目テンプレートとコンポーネント

📄 参照： references/item-templates.md

• template プロパティを使用して項目の描画をカスタマイズする
• ng-template ディレクティブで Angular コンポーネントを描画する
• チェックボックスと入力用テンプレートを文字列リテラルとして指定する
• クエリセレクターでテンプレートを参照する
• Menu コンポーネントをツールバーに統合する
• 複数のコンポーネント（NumericTextBox、DatePicker、Button）を描画する
• カスタム HTML テンプレート構造を作成する

ツールチップとリンク

📄 読む： references/tooltips-links.md

• ホバー時のヒントテキストには tooltipText プロパティを設定します
• Tooltip モジュールをインポートし、ターゲットセレクターを指定して初期化します
• ng-template を使ってアンカー要素を追加します
• ツールバー項目にルーティングリンクを作成します
• 状態を変更するトグルボタンを実装します
• 再生／一時停止、表示／非表示、フィルター切り替えのパターン
• リンクとボタンの状態に関するアクセシビリティ

レスポンシブ対応とスクロール

📄 読む： references/responsive-scrolling.md

• ナビゲーション矢印を備えたスクロール可能なオーバーフローモード（デフォルト）
• デバイスでのスクロールにタッチスワイプジェスチャーを使用します
• モバイルに最適化された表示にはポップアップオーバーフローモードを使用します
• スクロール距離は scrollStep プロパティでカスタマイズします
• 項目がコンテナーの幅を超える場合のオーバーフローを処理します
• ナビゲーションアイコンの無効状態と動作
• ナビゲーションボタンの長押しによる連続スクロール

高度な機能

📄 読む： references/advanced-features.md

• 関連するツールバーボタンをまとめます
• ネストされた項目と階層構造
• 矢印キーと Tab によるキーボードナビゲーション
• WCAG アクセシビリティへの準拠と ARIA 属性
• RTL（右から左）言語への対応
• 大規模なツールバーのパフォーマンスを最適化します
• WAI-ARIA 仕様に標準で準拠

API リファレンスの全容

📄 読む： references/api-reference.md

• ツールバーコンポーネントのプロパティ（12 個のプロパティ）
  • allowKeyboard, cssClass, enableCollision, enableHtmlSanitizer, enablePersistence
  • enableRtl, height, items, locale, overflowMode, scrollStep, width
• ツールバーのイベント（5 個のイベント）
  • beforeCreate (BeforeCreateArgs), clicked (ClickEventArgs), created, keyDown (KeyDownEventArgs), destroyed
• ツールバーのメソッド（7 個のメソッド）
  • addItems, destroy, disable, enableItems, hideItem, refreshOverflow, removeItems
• 項目の設定プロパティ（19 個以上のプロパティ）
  • align, cssClass, disabled, htmlAttributes, id, overflow, prefixIcon, suffixIcon
  • showAlwaysInPopup, showTextOn, tabIndex, template, text, tooltipText, type, visible, width
• 型と列挙型（5 個の列挙型）
  • ItemType, ItemAlign, OverflowMode, OverflowOption, DisplayMode
• API の使用例
  • すべての機能を備えた高度なツールバー
  • 動的な設定を備えたレスポンシブツールバー

クイックスタートの例

import { ToolbarModule } from '@syncfusion/ej2-angular-navigations';
import { Component } from '@angular/core';

@Component({
  imports: [ToolbarModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-toolbar>
      <e-items>
        <e-item text='Cut'></e-item>
        <e-item text='Copy'></e-item>
        <e-item type='Separator'></e-item>
        <e-item text='Paste'></e-item>
        <e-item type='Separator'></e-item>
        <e-item text='Bold'></e-item>
        <e-item text='Italic'></e-item>
        <e-item text='Underline'></e-item>
      </e-items>
    </ejs-toolbar>
  `
})
export class AppComponent { }

styles.css に CSS のインポートを追加します：

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';  
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';  
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';  
@import '../node_modules/@syncfusion/ej2-navigations/styles/material3.css';

よく使われるパターン

パターン 1：シンプルなテキストボタン

<e-item text='Cut'></e-item>
<e-item text='Copy'></e-item>
<e-item text='Paste'></e-item>

使用場面： テキストラベル付きの基本的なアクションボタンが必要な場合。

---

パターン 2：テキスト付きアイコンボタン

<e-item text='Bold' prefixIcon='e-icons e-bold'></e-item>
<e-item text='Italic' prefixIcon='e-icons e-italic'></e-item>
<e-item text='Undo' suffixIcon='e-icons e-undo'></e-item>

使用場面： テキストラベルの前後に視覚的なアイコンを表示したい場合。

---

パターン 3：セパレーター付きのコマンドグループ

<e-item text='Cut'></e-item>
<e-item text='Copy'></e-item>
<e-item type='Separator'></e-item>
<e-item text='Paste'></e-item>
<e-item type='Separator'></e-item>
<e-item text='Bold'></e-item>
<e-item text='Italic'></e-item>

使用場面： 関連するコマンドを視覚的にグループ化する必要がある場合。

---

パターン 4：入力コンポーネントを備えたツールバー

<e-item type='Input'>
  <ng-template #template>
    <ejs-numerictextbox value="10" width="150"></ejs-numerictextbox>
  </ng-template>
</e-item>
<e-item type='Input'>
  <ng-template #template>
    <ejs-dropdownlist [dataSource]='data' width="120"></ejs-dropdownlist>
  </ng-template>
</e-item>

使用場面： ツールバー内に入力フィールド、ドロップダウン、その他のコントロールが必要な場合。

---

パターン 5：チェックボックス付きのカスタムテンプレート

<e-item>
  <ng-template #template>
    <input type='checkbox' id='check1' checked=''>
    <label for='check1'>Enable Feature</label>
  </ng-template>
</e-item>

使用場面： チェックボックスやカスタムコントロールなどのカスタム HTML 要素が必要な場合。

---

パターン 6：ツールバー内のリンク

<e-item>
  <ng-template #template>
    <a href="url" target="_blank">Documentation</a>
  </ng-template>
</e-item>

使用場面： クリック可能なリンクをツールバー項目として追加する必要がある場合。

---

パターン 7：ホバー時のヘルプを表示するツールチップ

<ejs-tooltip target='#Toolbar [title]'>
  <ejs-toolbar id='Toolbar'>
    <e-items>
      <e-item text='Cut' tooltipText='Cut selected content'></e-item>
      <e-item text='Paste' tooltipText='Paste copied content'></e-item>
    </e-items>
  </ejs-toolbar>
</ejs-tooltip>

使用場面： マウスをホバーしたときにヒントテキストを表示したい場合。

---

パターン 8：レスポンシブなスクロール可能ツールバー

<ejs-toolbar width="300px">
  <e-items>
    <e-item text='Cut'></e-item>
    <e-item text='Copy'></e-item>
    
  </e-items>
</ejs-toolbar>

使用場面： コンテナーの幅がコンテンツ全体の幅より狭く、スクロール可能モードになる場合。

---

パターン 9：状態を持つトグルボタン

<ng-template #template>
  <button ejs-button class="e-btn" iconCss="e-play-icon" 
    isToggle="true" (click)="onPlayClick()"></button>
</ng-template>

使用場面： 状態を切り替えるボタン（再生／一時停止、表示／非表示）が必要な場合。

---

パターン 10：Font Awesome アイコン

<link rel="stylesheet" href="url" />

<e-item prefixIcon="fa fa-twitter"></e-item>
<e-item prefixIcon="fa fa-facebook"></e-item>

使用場面： Font Awesome などのサードパーティ製アイコンが必要な場合。

---

主なプロパティ

プロパティ	型	目的	例
text	string	ボタンの表示テキスト	text='Cut'
type	string	項目の種類（Button、Separator、Input）	type='Separator'
prefixIcon	string	テキストの前に表示するアイコンの CSS クラス	prefixIcon='e-icons e-cut'
suffixIcon	string	テキストの後に表示するアイコンの CSS クラス	suffixIcon='e-icons e-undo'
id	string	項目の一意な識別子	id='item1'
width	string	ボタンの幅	width='100px'
align	string	項目の配置（Left、Center、Right）	align='Right'
tooltipText	string	ホバー時に表示するツールチップのヒントテキスト	tooltipText='Cut'
cssClass	string	適用する CSS クラス	cssClass='custom-btn'
htmlAttributes	object	カスタム HTML 属性	[htmlAttributes]='{class: "custom"}'
template	string|object	カスタムテンプレートの内容	[template]='templateVar'
tabIndex	number	Tab キーによるナビゲーション順序	tabIndex=1
scrollStep	number	ピクセル単位のスクロール距離	scrollStep='50'

一般的なユースケース

1. テキストエディターのツールバー - 太字、斜体、下線のボタンと区切り線
2. ファイル操作 - 切り取り、コピー、貼り付け、元に戻す、やり直しのボタン
3. ツールバー内の検索バー - コンテナーの幅に合わせた検索用入力フィールド
4. 書式設定オプション - フォントサイズ、カラーピッカー、配置ボタン
5. ナビゲーションツールバー - 各セクションやページへのリンク
6. モバイルアプリのヘッダー - コンパクトでスクロール可能なレイアウトに表示する、ツールチップ付きのアイコン
7. ドキュメントビューアー - 拡大・縮小、印刷、ダウンロードの切り替え
8. リッチテキストエディター - テンプレートと入力欄を備えた、書式設定用のフルツールバー
9. ダッシュボードのコントロール - 日付ピッカー、フィルター、並べ替えオプション
10. ソーシャルメディアでの共有 - ツールバー内の Font Awesome のソーシャルアイコン