syncfusion-angular-dropdowntree

Syncfusion Angular Dropdown Tree の実装

Dropdown Tree コンポーネントを使用すると、ツリー状の階層データから単一または複数の値を選択できます。データバインディング、チェックボックス、テンプレート、アクセシビリティなどの重要な機能を備えており、カテゴリ別の選択肢、組織階層、入れ子構造のデータの表示に最適です。

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

次のような場合に、Dropdown Tree コンポーネントを使用します。

• 階層型の選択 - 入れ子状のツリー構造データ（カテゴリ、ファイル階層、組織ツリー）から選択できるようにする
• 複数選択 - オプションの自動チェック（親子間の同期）を備えた、チェックボックスによる複数項目の選択を有効にする
• 動的データ - ローカル配列、自己参照構造、リモート OData／REST エンドポイントをバインドする
• 表示のカスタマイズ - 項目、値、ヘッダー、フッターのテンプレートを使用して、UI を豊富にカスタマイズする
• 大規模データセット - 遅延読み込みを使用したリモートデータに対応し、パフォーマンスを最適化する
• ローカライズ - さまざまな文化や言語に合わせて、コンポーネントのテキストやメッセージを調整する

コンポーネントの概要

Dropdown Tree は、展開すると強力なフィルタリング、選択、テンプレート機能を備えたツリー全体を表示する、コンパクトなドロップダウン入力を提供します。フラットなドロップダウンとは異なり、階層関係を維持するため、複数階層のデータを直感的に移動できます。

主な特徴：

• 単一または複数の項目の選択
• オプションの自動チェックを備えたチェックボックスによる複数選択
• ローカルの階層型データおよび自己参照データのバインディング
• DataManager を使用したリモートデータバインディング（OData、ODataV4、WebAPI）
• 豊富なテンプレート：項目、値、ヘッダー、フッター、レコードなし、アクション失敗
• キーボードナビゲーションと ARIA 属性による組み込みのアクセシビリティ
• 完全なローカライズ対応

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

はじめに

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

• 依存関係とパッケージの設定
• Angular CLI の設定
• モジュールの登録（@syncfusion/ej2-angular-dropdowns）
• CSS のインポートとテーマの設定
• 基本的なコンポーネントの統合
• ローカルデータを使用した最初の動作例

データバインディング

📄 参照先： references/data-binding.md

• 階層型データ構造（ネストされた配列）
• 自己参照データバインディング（parentValue を持つフラットな配列）
• DataManager を使用したリモートデータ
• OData および ODataV4 アダプター
• WebAPI アダプターの設定
• Query ベースのフィルタリング

チェックボックス機能

📄 参照先： references/checkbox-features.md

• showCheckBox プロパティでチェックボックスを有効にする
• UI を乱さずに複数選択する
• 自動チェックによる階層動作（親子間の同期）
• すべて選択機能（showSelectAll とカスタムラベル）
• チェックボックスの状態の同期
• 中間状態（一部チェック済み）

テンプレートとカスタマイズ

📄 参照先： references/templates.md

• ツリー項目をカスタム表示する項目テンプレート
• 選択した項目を表示する値テンプレート
• ヘッダーおよびフッターのテンプレート
• レコードなしおよびアクション失敗のテンプレート
• 複数選択用のカスタム表示テンプレート（Custom モード）
• テンプレート式と補間

ローカライズ

📄 参照先： references/localization.md

• 対応するローカライズキーとデフォルトメッセージ
• ロケールとカルチャの設定
• ロケール固有の文字列のカスタマイズ
• 主なメッセージ：noRecordsTemplate、actionFailureTemplate、overflowCountTemplate、totalCountTemplate
• 多言語設定

API リファレンス

📄 参照先： references/api-reference.md

• コアプロパティとフィールドマッピング
• TreeSettings の設定オプション
• 共通イベントとコールバック
• プロパティ設定のベストプラクティス
• パフォーマンス最適化のヒント

メソッドとイベント

📄 読む: references/methods-and-events.md

• コンポーネントのメソッド: showPopup(), hidePopup(), refresh(), clearSelection(), expandAll(), collapseAll()
• 選択イベント: change, select
• ポップアップイベント: open, close, beforeOpen
• データイベント: dataBound, actionFailure, filtering
• ライフサイクルイベント: created, destroyed
• ユーザー操作イベント: focus, blur, keyPress
• イベント引数とシグネチャ
• 完全な動作例

クイックスタートの例

階層データを使用した最小限の動作例を示します。

import { Component } from '@angular/core';
import { DropDownTreeModule } from '@syncfusion/ej2-angular-dropdowns';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';

@Component({
  selector: 'app-dropdown-tree',
  template: `<ejs-dropdowntree id='dropdowntree' 
                [fields]='fields' 
                placeholder='Select a category'></ejs-dropdowntree>`,
  standalone: true,
  imports: [DropDownTreeModule, FormsModule, ReactiveFormsModule]
})
export class AppComponent {
  // Hierarchical data structure with nested arrays
  public data = [
    {
      nodeId: '01', nodeText: 'Music',
      nodeChild: [
        { nodeId: '01-01', nodeText: 'Gouttes.mp3' }
      ]
    },
    {
      nodeId: '02', nodeText: 'Videos', expanded: true,
      nodeChild: [
        { nodeId: '02-01', nodeText: 'Naturals.mp4' },
        { nodeId: '02-02', nodeText: 'Wild.mpeg' }
      ]
    }
  ];

  // Field mapping: value=nodeId, text=nodeText, child=nodeChild
  public fields = { 
    dataSource: this.data, 
    value: 'nodeId', 
    text: 'nodeText', 
    child: 'nodeChild' 
  };
}

よくあるパターン

パターン 1: チェックボックスによる複数選択

@Component({
  template: `<ejs-dropdowntree id='dropdowntree' 
                [fields]='fields' 
                [showCheckBox]='true' 
                [showSelectAll]='true'
                selectAllText='Check All' 
                unSelectAllText='Uncheck All'></ejs-dropdowntree>`,
  standalone: true,
  imports: [DropDownTreeModule, FormsModule, ReactiveFormsModule]
})
export class CheckboxExample {
  public data = [
    { id: 1, name: 'Music', hasChild: true, expanded: true },
    { id: 2, pid: 1, name: 'Hot Singles' },
    { id: 3, pid: 1, name: 'Rising Artists' }
  ];
  public fields = { 
    dataSource: this.data, 
    value: 'id', 
    text: 'name', 
    parentValue: 'pid', 
    hasChildren: 'hasChild' 
  };
}

使用する場面: ユーザーが1回の操作で複数の項目を選択できるようにし、便利な「すべて選択」オプションを提供します。未チェック時のラベルには selectAllText を、チェック時のラベルには unSelectAllText を使用します。

パターン 2: 自動チェック（親子の同期）

@Component({
  template: `<ejs-dropdowntree [fields]='fields' 
                [showCheckBox]='true' 
                [treeSettings]='{ autoCheck: true }'></ejs-dropdowntree>`
})
export class AutoCheckExample {
  public fields = { dataSource: this.data, /* ... */ };
}

使用する場面: 階層の整合性を保ちます。親をチェックするとすべての子も自動的にチェックされ、最後の子のチェックを外すと親のチェックも外れます（一部選択時は中間状態になります）。

パターン 3: OData によるリモートデータ

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';

@Component({
  template: `<ejs-dropdowntree [fields]='fields'></ejs-dropdowntree>`
})
export class RemoteDataExample {
  public data = new DataManager({
    url: 'url',
    adaptor: new ODataV4Adaptor,
    crossDomain: true
  });
  
  public fields = {
    dataSource: this.data,
    query: new Query().from('Employees').select('EmployeeID,FirstName').take(5),
    value: 'EmployeeID',
    text: 'FirstName',
    hasChildren: 'EmployeeID'
  };
}

使用する場面: リモートサーバーから階層データを取得して初期読み込みを抑え、大規模なデータセットに対応します。

パターン 4: カスタム項目の表示

@Component({
  template: `<ejs-dropdowntree [fields]='fields' 
                [itemTemplate]='itemTemplate'></ejs-dropdowntree>`
})
export class TemplateExample {
  public itemTemplate = '<div><strong>${name}</strong> - ${type}</div>';
  public fields = { dataSource: this.data, /* ... */ };
}

使用する場面: 各ツリー項目に、書式設定された豊富なコンテンツ（名前、アイコン、メタデータ）を表示します。

主な機能

機能	用途
階層データ	項目を親子関係（カテゴリ、部署、ファイルツリー）で整理します
チェックボックス	ドロップダウン UI に影響を与えずに複数選択を可能にします
自動チェック	親子の選択状態を自動的に同期します
リモートバインディング	OData、REST API、またはカスタムエンドポイントからデータを取得します
テンプレート	項目の表示、ヘッダー、フッター、選択値の形式をカスタマイズします
アクセシビリティ	キーボードでの完全なナビゲーション、ARIA 属性、スクリーンリーダーをサポートします
ローカライズ	複数の言語と地域別の形式をサポートします
すべて選択	1回のクリックですべての項目をすばやく選択または選択解除できます