syncfusion-react-dropdown-tree

ドロップダウンツリーの実装

ドロップダウンツリーコンポーネントは、ドロップダウンインターフェイス内に、折りたたみ可能なツリー構造で階層データを表示します。ツリーナビゲーションとドロップダウンのアクセシビリティを組み合わせており、チェックボックスによる複数選択、大規模なデータセット向けの遅延読み込み、テンプレートとイベントによる包括的なカスタマイズ、フィルタリング、RTL およびローカライズに対応した完全なアクセシビリティをサポートします。

このスキルを使用するタイミング

次のような場合は、すぐにドロップダウンツリーを使用してください。

• 階層データを表示する - 入れ子になったカテゴリ、組織構造、ファイルツリー、部門の階層を表示します
• 複数選択を可能にする - チェックボックスやキーボード修飾キーを使って、ユーザーが複数の項目を選択できるようにします
• 遅延読み込みをサポートする - 必要に応じて子項目を読み込むことで、大規模なデータセットのパフォーマンスを最適化します
• 表示をカスタマイズする - テンプレートを使って、項目、ヘッダー、フッター、選択値、エラー状態の形式を設定します
• フィルタリングを実装する - 設定可能なフィルタータイプ（StartsWith、EndsWith、Contains）で検索機能を有効にします
• アクセシビリティを確保する - WAI-ARIA 準拠、キーボードナビゲーション、スクリーンリーダーのサポートを提供します
• 複数の言語に対応する - カスタマイズ可能なキーと RTL サポートを使って UI をローカライズします
• リモートデータをバインドする - OData、OData V4、Web API、その他のリモートデータサービスと連携します
• 複雑な選択ロジックを処理する - イベント、自動チェック階層、ノードの選択的な無効化を使用します

コンポーネントの概要

ドロップダウンツリーの機能は次のとおりです。

• 階層表示：ローカルデータ（階層型／自己参照型）およびリモートデータソースを柔軟にバインドできます
• 複数選択モード：自動チェック付きチェックボックス、Ctrl／Shift キーによる複数選択、単一選択（デフォルト）
• 柔軟なテンプレート：項目、値、ヘッダー、フッター、noRecords、actionFailure のテンプレートによるカスタムレンダリング
• パフォーマンスの最適化：大規模なデータセットを効率的に処理する遅延読み込み（オンデマンド読み込み）
• 検索とフィルタリング：フィルタータイプと大文字・小文字の区別を設定できる組み込みフィルターバー
• 包括的なイベント：change、select、dataBound、filtering、beforeOpen、focus、keyPress、ポップアップイベント
• アクセシビリティ：完全な WAI-ARIA（ロール、属性）、キーボードナビゲーション、スクリーンリーダーのサポート、WCAG 2.2 準拠
• ローカライズ：カスタマイズ可能な 4 つのキーとロケールのオーバーライドによる多言語サポート
• RTL サポート：右から左へのレイアウト描画
• ツリー設定：高度な設定（expandOn、autoCheck、loadOnDemand、checkDisabledChildren）
• フィールドマッピング：柔軟なデータ構造をサポート（value、text、child、parentValue、expanded、hasChildren、selectable、iconCss、imageUrl、htmlAttributes）
• 表示モード：選択項目の Default、Delimiter、Custom モード

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

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージの依存関係（npm install コマンド）
• React／TypeScript プロジェクトのセットアップ（Vite、Create React App）
• 基本的なコンポーネントの実装と初期化
• CSS のインポートとテーマの設定
• 最初のレンダリングと最小構成の動作例

データバインディング

📄 参照： references/data-binding.md

• ローカルデータのバインディング（階層型および自己参照型の構造）
• DataManager と各種アダプターを使ったリモートデータ（OData、OData V4、WebAPI、URL）
• value、text、child、parentValue、expanded、hasChildren のフィールドマッピング
• 大規模なデータセット向けのオンデマンド読み込み（遅延読み込み）
• selectable フィールドを使ったノード選択の防止
• リモートデータサービス向けのクエリ設定

チェックボックスと複数選択

📄 参照： references/checkbox-selection.md

• showCheckBox プロパティによるチェックボックスサポートの有効化
• 複数選択のワークフローと選択した値へのアクセス
• 自動チェックの階層動作（親子間の同期）
• カスタマイズ可能な selectAllText と unSelectAllText によるすべて選択機能
• 一部選択時の中間チェックボックス状態
• 無効なノードに対する CheckDisabledChildren の動作

テンプレート

📄 参照： references/templates.md

• リスト項目をカスタムレンダリングするための項目テンプレート
• 選択項目の表示をカスタマイズする値テンプレート
• 項目の上に静的コンテンツを表示するヘッダーテンプレート
• 項目の下に静的コンテンツを表示するフッターテンプレート
• 空の状態を処理する NoRecords テンプレート
• エラー状態を処理する ActionFailure テンプレート
• 複数選択の表示をカスタマイズする CustomTemplate
• テンプレート式の構文とデータアクセスパターン

複数選択とフィルタリング

📄 参照： references/multi-selection-filtering.md

• allowMultiSelection プロパティと Ctrl／Shift キーによる操作
• 表示モード：Default、Delimiter、Custom
• delimiterChar と mode の設定
• allowFiltering とフィルターバーの実装
• フィルターの種類：StartsWith、EndsWith、Contains
• filterBarPlaceholder のカスタマイズ
• ignoreCase と ignoreAccent のオプション

ツリーの設定と構成

📄 参照： references/tree-settings.md

• 遅延読み込みを実装する loadOnDemand
• 階層的なチェックボックス同期を行う autoCheck
• expandOn の動作（Auto、Click、DblClick、None）
• 無効なノードを処理する checkDisabledChildren
• ツリーの展開と折りたたみの制御

フィールドマッピングとカスタムデータ構造

📄 参照： references/field-mapping.md

• コアフィールド：value、text、dataSource、child、parentValue
• ノードの状態フィールド：expanded、hasChildren、selected、selectable
• 表示を拡張するフィールド：iconCss、imageUrl、htmlAttributes
• リモートデータ用の Query と tableName
• 階層データのネストされたフィールドマッピング

高度な機能と API リファレンス

📄 参照： references/advanced-features.md

• プロパティ（説明と例を含む 60 以上のプロパティ）
• メソッド（getSelectedNodes、getCheckedNodes、setCheckedNodes など）
• イベント（change、select、dataBound、filtering、beforeOpen、focus、keyPress、popup）
• イベント引数（プロパティの説明を含む EventArgs 構造体）
• スタイリングと CSS のカスタマイズ
• パフォーマンス最適化の手法

アクセシビリティとローカライズ

📄 参照： references/accessibility-localization.md

• WCAG 2.2 および Section 508 の準拠基準
• WAI-ARIA の属性とロール（listbox、treeitem、checkbox、group など）
• キーボード操作のショートカット（Alt+Down、矢印キー、Enter、Space など）
• スクリーンリーダーと支援技術のサポート
• ローカライズキー（noRecordsTemplate、actionFailureTemplate、overflowCountTemplate、totalCountTemplate）
• locale プロパティによるカルチャのカスタマイズ
• enableRtl による RTL（右から左）言語のサポート

クイックスタート

階層データを使用した基本的なドロップダウンツリー

import { DropDownTreeComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-dropdowns/styles/material.css';

function App() {
  const data = [
    { id: '1', name: 'Electronics', expanded: true },
    { id: '2', name: 'Laptops', parentId: '1' },
    { id: '3', name: 'Phones', parentId: '1' },
    { id: '4', name: 'Appliances' },
  ];

  return (
    <DropDownTreeComponent
      id="dropdowntree"
      fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId', hasChildren: 'hasChild' }}
      placeholder="Select an item"
    />
  );
}

export default App;

チェックボックスと自動チェックを使用する場合

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId', hasChildren: 'hasChild' }}
  showCheckBox={true}
  showSelectAll={true}
  treeSettings={{ autoCheck: true }}
  placeholder="Select items"
/>

フィルタリングを使用する場合

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId' }}
  allowFiltering={true}
  filterType="Contains"
  filterBarPlaceholder="Search items..."
  placeholder="Select an item"
/>

カスタムテンプレートを使用する場合

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId' }}
  itemTemplate={(props) => (
    <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
      <span>{props.name}</span>
      <small style={{ color: '#999' }}>({props.category})</small>
    </div>
  )}
  valueTemplate={(props) => <span>{props.name}</span>}
  placeholder="Select item"
/>

一般的なパターン

パターン 1：自己参照データのバインド

親参照を持つフラットなデータ構造の場合：

const data = [
  { id: 1, name: 'Discover Music', hasChild: true, expanded: true },
  { id: 2, pid: 1, name: 'Hot Singles' },
  { id: 3, pid: 1, name: 'Rising Artists' },
  { id: 7, name: 'Sales and Events', hasChild: true },
  { id: 8, pid: 7, name: '100 Albums' },
];

<DropDownTreeComponent
  id="dropdowntree"
  fields={{
    dataSource: data,
    value: 'id',
    text: 'name',
    parentValue: 'pid',
    hasChildren: 'hasChild',
  }}
/>

パターン 2：選択変更のイベント処理

const handleChange = (args) => {
  console.log('Old values:', args.oldValue); // string[]
  console.log('New values:', args.value); // string[]
  console.log('User interaction:', args.isInteracted); // boolean
};

const handleSelect = (args) => {
  console.log('Action:', args.action); // 'select' or 'unselect'
  console.log('Item data:', args.itemData); // object
};

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  onChange={handleChange}
  onSelect={handleSelect}
/>

パターン 3：自動チェックを使用した複数選択

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  showCheckBox={true}
  treeSettings={{ autoCheck: true }}
  mode="Default"
  delimiterChar=", "
  placeholder="Select multiple items"
/>

パターン 4：大規模データセットの遅延読み込み

const remoteData = new DataManager({
  url: 'url',
  adaptor: new UrlAdaptor(),
});

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: remoteData, value: 'id', text: 'name', hasChildren: 'hasChild' }}
  treeSettings={{ loadOnDemand: true }}
  placeholder="Loading..."
/>

パターン 5：IconCss を使用した項目のカスタムスタイル設定

const data = [
  { id: 1, name: 'Documents', iconCss: 'e-folder', hasChild: true },
  { id: 2, pid: 1, name: 'Resume.pdf', iconCss: 'e-pdf' },
  { id: 3, pid: 1, name: 'Report.docx', iconCss: 'e-docx' },
];

<DropDownTreeComponent
  id="dropdowntree"
  fields={{
    dataSource: data,
    value: 'id',
    text: 'name',
    iconCss: 'iconCss',
    parentValue: 'pid',
    hasChildren: 'hasChild',
  }}
/>

パターン 6：RTL とローカライズのサポート

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  enableRtl={true}
  locale="ar"
  placeholder="اختر عنصرا"
/>

主要なプロパティの概要

プロパティ	型	説明
コア
id	string	コンポーネントの一意な識別子
fields	FieldsModel	データソースとフィールドのマッピング設定
placeholder	string	入力欄のプレースホルダーテキスト
enabled	boolean	コンポーネントを有効／無効にします（デフォルト：true）
選択
showCheckBox	boolean	チェックボックスによる複数選択を有効にします（デフォルト：false）
showSelectAll	boolean	「すべて選択」チェックボックスを表示します（デフォルト：false）
selectAllText	string	「すべて選択」ラベルのテキスト
unSelectAllText	string	「すべて選択解除」ラベルのテキスト
allowMultiSelection	boolean	Ctrl／Shift キーによる複数選択を有効にします
テンプレート
itemTemplate	string | Function	アイテムのカスタム表示
valueTemplate	string | Function	選択した値のカスタム表示
headerTemplate	string | Function	ヘッダーコンテンツのカスタム表示
footerTemplate	string | Function	フッターコンテンツのカスタム表示
noRecordsTemplate	string | Function	空の状態のテンプレート
actionFailureTemplate	string | Function	エラー状態のテンプレート
フィルタリング
allowFiltering	boolean	検索／フィルターバーを有効にします（デフォルト：false）
filterType	TreeFilterType	フィルターの種類：StartsWith、EndsWith、Contains
filterBarPlaceholder	string	フィルターバーのプレースホルダーテキスト
ignoreCase	boolean	大文字と小文字を区別せずにフィルタリングします（デフォルト：true）
ignoreAccent	boolean	フィルタリング時に発音区別符号を無視します
ツリー設定
treeSettings	TreeSettingsModel	ツリーの動作設定（autoCheck、loadOnDemand、expandOn）
表示
mode	string	表示モード：Default、Delimiter、Custom
delimiterChar	string	複数選択時の区切り文字（デフォルト：", "）
customTemplate	string	複数選択表示のカスタムテンプレート
ローカライズと RTL
locale	string	ロケールコード（デフォルト："en"）
enableRtl	boolean	右から左へのレイアウトを有効にします
enablePersistence	boolean	ページの再読み込み後も状態を保持します
スタイル設定
cssClass	string	ルートとポップアップに適用する CSS クラス
width	string | number	コンポーネントの幅
popupHeight	string | number	ポップアップの高さ
htmlAttributes	object	コンポーネントの HTML 属性

選択ガイド

データバインディングの選択：

• ローカル階層型 - 小規模から中規模のデータセット向けに、child プロパティを持つ入れ子の JSON オブジェクトを使用します
• ローカル自己参照型 - 構造化データ向けに、parentValue フィールドを持つフラットな配列を使用します
• DataManager によるリモート接続 - 大規模なデータセット、動的読み込み、リアルタイムデータには OData／Web API を使用します

選択モードの選択：

• 単一選択 - デフォルト（チェックボックスなし、複数選択なし）。読み取り専用の視覚的な選択です
• チェックボックス - 明示的な複数選択には showCheckBox={true} を使用します
• 複数選択 - Ctrl／Shift キーによるキーボード選択には allowMultiSelection={true} を使用します
• 自動チェック - チェックボックスと treeSettings={{ autoCheck: true }} を組み合わせて、階層を同期します

テンプレートの選択：

• itemTemplate - ツリー項目ごとのカスタム書式設定（名前と説明、アイコン、バッジ）
• valueTemplate - 入力フィールド内のカスタム表示（結合テキスト、書式設定された値）
• headerTemplate - リスト上部の静的コントロール（説明、検索のヘルプ、カスタムコントロール）
• footerTemplate - リスト下部の静的コンテンツ（件数の概要、アクションボタン）
• noRecordsTemplate - データがない場合、または検索結果がない場合の空の状態
• actionFailureTemplate - データの取得に失敗した場合のエラーメッセージ

遅延読み込みを使用する場合：

• 大規模なデータセット（1000 件以上の項目）
• パフォーマンスが重要なアプリケーション
• ページネーションを使用してリモート API からデータを取得する場合
• 階層のレベル数が多い場合

フィルタリングを使用する場合：

• 検索が必要な大規模なデータセット
• ユーザーが項目を見つけやすくする場合
• 選択時の認知負荷を軽減する場合

Next Steps

• Get started → Read getting-started.md
• Bind data → Read data-binding.md
• Add checkboxes → Read checkbox-selection.md
• Enable filtering → Read multi-selection-filtering.md
• Configure trees → Read tree-settings.md
• Map fields → Read field-mapping.md
• Customize → Read templates.md
• Access APIs → Read advanced-features.md
• Enhance UX → Read accessibility-localization.md