syncfusion-javascript-dropdowntree

Syncfusion Dropdown Tree の実装

---

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

次のような場合は、Dropdown Tree コントロールを使用してください。

• 階層データを表示する：ツリー状の構造を持つコンパクトなドロップダウン形式で表示します
• 複数選択を可能にする：チェックボックスを使って、ツリー項目を複数選択できるようにします
• 大規模なデータセットをオンデマンドで読み込む：遅延読み込みによってパフォーマンスを最適化します
• ツリーの表示をカスタマイズする：項目テンプレート、ヘッダー、フッターを設定します
• 親子間の依存関係を処理する：チェックボックスの状態を自動的に連動させます
• 複数の言語に対応する：ローカライズ機能を使用します
• キーボード操作とアクセシビリティを提供する：支援技術を利用するユーザーに対応します

Dropdown Tree は、組織階層、カテゴリ選択、場所や地域の選択、権限やロールの管理インターフェイスなどの用途に適しています。

---

コンポーネントの概要

Syncfusion Dropdown Tree コントロールを使うと、ツリー構造で表示される階層データから、単一または複数の値を選択できます。主な機能は次のとおりです。

• データバインディング：ローカル（階層型／自己参照型）およびリモート（OData、Web API、DataManager）
• チェックボックス：親子間の自動チェック動作を設定できる複数選択機能
• すべて選択：ヘッダーに組み込みのチェックボックスを表示し、すべての項目を選択／選択解除できます
• テンプレート：項目、値、ヘッダー、フッター、レコードなしの表示内容をカスタマイズできます
• 遅延読み込み：子データをオンデマンドで読み込み、初期の通信量を削減します
• 並べ替え：項目を昇順または降順で表示します
• フィルタリング：ツリー項目を動的に検索、絞り込みできます
• ローカライズ：テキストをカスタマイズして複数の言語に対応します
• アクセシビリティ：キーボード操作とスクリーンリーダーに対応します
• 複数選択モード：ボックス、区切り文字、デフォルト、カスタムの表示モードを使用できます

---

ドキュメントの案内

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージの依存関係
• 開発環境のセットアップ
• CSS のインポートとテーマの設定
• 基本的な HTML の初期化
• TypeScript と ES5 の例を使った、最初の Dropdown Tree の作成

データバインディングとツリー構造

📄 参照： references/data-binding.md

• 階層構造を使ったローカルデータバインディング
• 自己参照型データバインディングのパターン
• リモートデータバインディング（OData、Web API、DataManager）
• オンデマンド読み込み（遅延読み込み）の設定
• フィールドのマッピングとデータ構造の要件
• さまざまなデータソースを使った実践的な例

チェックボックス機能と選択

📄 参照： references/checkbox-features.md

• showCheckBox プロパティを使ったチェックボックスの有効化
• 単一項目の選択
• 親子項目間の自動チェックの連動
• ポップアップヘッダーでの「すべて選択」機能
• 「すべて選択」のテキストと動作のカスタマイズ
• 選択項目のプログラムによる管理

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

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

• リスト表示をカスタマイズする項目テンプレート
• 選択した値の表示に使う値テンプレート
• ポップアップヘッダーをカスタマイズするヘッダーテンプレート
• ポップアップのフッター内容に使うフッターテンプレート
• 空の状態を処理する「レコードなし」テンプレート
• エラー時に使うアクション失敗テンプレート
• テンプレート式の構文とベストプラクティス

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

📄 参照： references/localization-and-accessibility.md

• ローカライズライブラリのセットアップと使用方法
• 複数言語のテキストのカスタマイズ
• デフォルトおよびカスタムのロケール設定
• キーボード操作への対応
• スクリーンリーダーとの互換性
• WCAG アクセシビリティ機能

---

クイックスタートの例

基本設定（TypeScript）

import { DropDownTree } from '@syncfusion/ej2-dropdowns';

// Define hierarchical data
let continents = [
    {
        code: 'AF', 
        name: 'Africa', 
        countries: [
            { code: 'NGA', name: 'Nigeria' },
            { code: 'EGY', name: 'Egypt' }
        ]
    },
    {
        code: 'AS', 
        name: 'Asia',
        expanded: true,
        countries: [
            { code: 'IND', name: 'India', selected: true },
            { code: 'JPN', name: 'Japan' }
        ]
    }
];

// Initialize Dropdown Tree
let ddtree = new DropDownTree({
    fields: { 
        dataSource: continents, 
        value: 'code', 
        text: 'name', 
        child: 'countries' 
    }
});

ddtree.appendTo('#ddtElement');

HTML 要素

<input type="text" id="ddtElement" />

---

基本概念

1. 階層データ構造

階層データでは、入れ子になった配列を使って親子関係を表します。

let hierarchicalData = [
    {
        id: 1,
        name: 'Parent Item',
        children: [
            { id: 2, name: 'Child 1' },
            { id: 3, name: 'Child 2' }
        ]
    }
];

2. 自己参照型データ構造

自己参照型データでは、親 ID の参照を使います。

let selfRefData = [
    { id: 1, name: 'Parent', parentId: null },
    { id: 2, name: 'Child 1', parentId: 1 },
    { id: 3, name: 'Child 2', parentId: 1 }
];

3. 単一選択と複数選択

• 単一選択：項目を1つ選択できます（デフォルトの動作です）。
• 複数選択：allowMultiSelection: true または showCheckBox: true を設定して有効にします。

4. 親子チェックボックスの連動

treeSettings で autoCheck: true を設定すると：

• 親をチェックすると、すべての子も自動的にチェックされます。
• 親のチェックを外すと、すべての子のチェックも自動的に外れます。
• 一部の子だけがチェックされている場合、中間状態になります。

---

FieldsModel の設定

fields プロパティでは、FieldsModel を使用してデータソースのフィールドを Dropdown Tree のプロパティにマッピングします。

FieldsModel のプロパティ

プロパティ	型	説明	例
dataSource	DataManager | Object[]	データの配列または DataManager インスタンス	[{...}, {...}]
value	string	項目の値／IDに使用するフィールド名	'id' または 'code'
text	string	表示テキストに使用するフィールド名	'name' または 'title'
child	string | FieldsModel	子コレクションに使用するフィールド名（階層型）	'children' または 'items'
parentValue	string	親の参照に使用するフィールド名（自己参照型）	'parentId' または 'pid'
hasChildren	string	項目に子があるかどうかを示すフィールド名	'hasChild' または 'hasItems'
expanded	string	展開状態に使用するフィールド名	'expanded' または 'isExpanded'
selected	string	選択状態に使用するフィールド名	'selected' または 'isSelected'
iconCss	string	アイコンの CSS クラスに使用するフィールド名	'iconClass'
imageUrl	string	画像 URL に使用するフィールド名	'imageUrl' または 'icon'
htmlAttributes	string	HTML 属性に使用するフィールド名	'htmlAttrs'
tooltip	string	ツールチップのテキストに使用するフィールド名	'title' または 'tooltip'
selectable	string	項目の選択可否に使用するフィールド名	'canSelect'
query	Query	DataManager 用の外部クエリ	カスタム Query オブジェクト
tableName	string	サーバー側データ用のテーブル名	'EmployeeTable'

FieldsModel の例

カスタムフィールドを使用した階層データ

let ddtree = new DropDownTree({
    fields: {
        dataSource: hierarchicalData,
        value: 'id',
        text: 'name',
        child: 'subitems',
        expanded: 'isExpanded',
        iconCss: 'iconClass'
    }
});
ddtree.appendTo('#ddtElement');

自己参照型データ

let ddtree = new DropDownTree({
    fields: {
        dataSource: selfRefData,
        value: 'id',
        text: 'name',
        parentValue: 'parentId',
        hasChildren: 'hasChild'
    }
});
ddtree.appendTo('#ddtElement');

OData を使用したリモートデータ

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

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Employees',
            adaptor: new ODataV4Adaptor()
        }),
        value: 'EmployeeID',
        text: 'FirstName',
        hasChildren: 'EmployeeID'
    }
});
ddtree.appendTo('#ddtElement');

---

TreeSettingsModel の設定

treeSettings プロパティでは、TreeSettingsModel を使用してツリー固有の動作を設定します。

TreeSettingsModel のプロパティ

プロパティ	型	説明	デフォルト
loadOnDemand	boolean	子項目の遅延読み込みを有効にします	false
autoCheck	boolean	親子チェックボックスの連動を有効にします	false
checkDisabledChildren	boolean	親のチェック時に無効化された子も含めます	false
expandOn	ExpandOn	展開／折りたたみ操作のトリガー	ExpandOn.Auto

ExpandOn の列挙値

値	説明
Auto	デスクトップではダブルクリック、モバイルではシングルタップ
Click	デスクトップとモバイルの両方でシングルクリック／タップ
DblClick	デスクトップとモバイルの両方でダブルクリック／タップ
None	展開／折りたたみを無効にします

TreeSettingsModel の例

遅延読み込みの設定

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    treeSettings: {
        loadOnDemand: true  // Children load when parent expands
    }
});
ddtree.appendTo('#ddtElement');

無効化された子にも対応する自動チェック

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    treeSettings: {
        autoCheck: true,
        checkDisabledChildren: true  // Disabled items get checked too
    }
});
ddtree.appendTo('#ddtElement');

カスタムの展開トリガー

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    treeSettings: {
        expandOn: 'Click'  // Single-click to expand/collapse
    }
});
ddtree.appendTo('#ddtElement');

---

📋 API プロパティのリファレンス

📄 例と型の仕様を含む、API プロパティの完全なドキュメント

🔗 api-properties.md を開く

内容：

• ✅ 55 以上のプロパティ - すべてのプロパティについて、型、デフォルト値、説明を記載
• ✅ 10 のカテゴリ - 基本、選択、テンプレート、ポップアップ、フィルタリング、並べ替え、スタイル、状態、HTML セキュリティ、ローカライズ
• ✅ 100 以上の例 - 各プロパティの実用的なコードサンプル
• ✅ 型の仕様 - 型情報とデフォルト値の詳細
• ✅ ベストプラクティス - 使用パターンと推奨事項

---

🔧 API メソッドのリファレンス

📄 パラメーターの詳細と例を含む、API メソッドの完全なドキュメント

🔗 api-methods.md を開く

内容：

• ✅ 16 個のメソッド - すべてのコンポーネントメソッドを詳しく解説
• ✅ 6 つのカテゴリ - ライフサイクル、データと値、ポップアップ、DOM、イベント管理、モジュールの注入
• ✅ パラメーター仕様 - パラメーターの型、説明、戻り値の型を網羅
• ✅ 動作するサンプル - 各メソッドの本番環境ですぐに使えるコード
• ✅ ユースケース - 各メソッドをいつ、どのように使うか

---

🎯 API イベントリファレンス

📄 イベント引数のプロパティとサンプルを含む、API イベントの完全なドキュメントです

🔗 api-events.md を開く

内容：

• ✅ 13 個のイベント - すべてのコンポーネントイベントを詳しく解説
• ✅ 7 つのカテゴリ - 選択、データ、フィルタリング、ポップアップ、フォーカス、キーボード、ライフサイクル
• ✅ 8 種類のイベント引数 - プロパティのマッピングを網羅（30 個以上のプロパティ）
• ✅ イベントの詳細 - 各イベントが発生するタイミングと提供されるデータ
• ✅ 実際のサンプル - 実用的なイベント処理の実装例

---

よく使われるパターン

パターン 1：チェックボックスを使用した複数選択

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    showSelectAll: true,
    treeSettings: { autoCheck: true },
    change: (args) => {
        console.log('Selected items:', args.value);
    }
});
ddtree.appendTo('#ddtElement');

使用する場面：親子関係に基づいて複数の項目を選択する必要がある場合。

パターン 2：大規模なデータセットをオンデマンドで読み込む

let ddtree = new DropDownTree({
    fields: { 
        dataSource: dataManager, 
        value: 'id', 
        text: 'name',
        parentValue: 'parentId'
    },
    treeSettings: { loadOnDemand: true }
});
ddtree.appendTo('#ddtElement');

使用する場面：大規模な階層構造（1000 個以上の項目）を扱う場合。

パターン 3：テンプレートを使用したカスタム項目表示

let ddtree = new DropDownTree({
    fields: { dataSource: data, text: 'name', value: 'id' },
    itemTemplate: '<div class="item-row"><span>${name}</span> <small>${department}</small></div>',
    valueTemplate: '<span class="selected-badge">${name}</span>'
});
ddtree.appendTo('#ddtElement');

使用する場面：追加のデータフィールドを表示する必要がある場合。

パターン 4：フィルタリングを使用したリモートデータ

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

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'https://api.example.com/items',
            adaptor: new ODataV4Adaptor()
        }),
        value: 'id',
        text: 'name'
    },
    allowFiltering: true,
    filterBarPlaceholder: 'Search items...',
    filterType: 'Contains'
});
ddtree.appendTo('#ddtElement');

使用する場面：検索機能を使ってリモートサービスからデータを取得する場合。

パターン 5：区切り文字モードを使用した「すべて選択」のカスタマイズ

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    showSelectAll: true,
    selectAllText: 'Select All Items',
    unSelectAllText: 'Clear All',
    mode: 'Delimiter',
    delimiterChar: '; ',
    allowMultiSelection: true
});
ddtree.appendTo('#ddtElement');

使用する場面：分かりやすいチェックボックスのテキストと、区切り文字で区切られた表示を使いたい場合。

パターン 6：動的なデータ更新

let ddtree = new DropDownTree({
    fields: { dataSource: [], value: 'id', text: 'name', child: 'items' }
});
ddtree.appendTo('#ddtElement');

// Later, update data
let newData = [{ id: 1, name: 'Item 1', items: [] }];
ddtree.fields.dataSource = newData;
ddtree.refresh();  // Re-render

使用する場面：初期化後にデータが動的に変化する場合。

パターン 7：検証を伴うプログラムによる値の設定

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', child: 'items' },
    showCheckBox: true,
    change: (args) => {
        if (args.value.length > 5) {
            console.warn('Maximum 5 items can be selected');
            // Reset to previous value
            ddtree.value = args.oldValue;
        }
    }
});
ddtree.appendTo('#ddtElement');

使用する場面：選択に制約を適用する必要がある場合。

---

ユースケースと実装ガイド

組織階層のナビゲーション

シナリオ：複数選択と役割の割り当てを伴う、部門／従業員の選択

let employees = [
    { id: 1, name: 'IT Department', hasChild: true },
    { id: 2, pid: 1, name: 'John Doe', department: 'IT' },
    { id: 3, pid: 1, name: 'Jane Smith', department: 'IT' },
    { id: 4, name: 'HR Department', hasChild: true },
    { id: 5, pid: 4, name: 'Mike Johnson', department: 'HR' }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: employees, 
        value: 'id', 
        text: 'name', 
        parentValue: 'pid',
        hasChildren: 'hasChild'
    },
    showCheckBox: true,
    treeSettings: { autoCheck: true },
    itemTemplate: '<div>${name} <span class="text-muted">${department}</span></div>',
    change: (args) => {
        assignRolesToSelectedEmployees(args.value);
    }
});
ddtree.appendTo('#employeeSelection');

地理的な場所／地域の選択

シナリオ：遅延読み込みを使用した、国 → 州 → 市の選択

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

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'api/locations',
            adaptor: new WebApiAdaptor()
        }),
        value: 'id',
        text: 'name',
        parentValue: 'parentId',
        hasChildren: 'hasChildren'
    },
    treeSettings: { 
        loadOnDemand: true  // Load children on demand
    },
    allowFiltering: true,
    filterBarPlaceholder: 'Search locations...',
    change: (args) => {
        updateMapWithSelectedLocation(args.value);
    }
});
ddtree.appendTo('#locationPicker');

カテゴリベースの商品フィルタリング

シナリオ：商品カテゴリを項目数とアイコンとともに表示

let categories = [
    { 
        id: 'cat1', 
        name: 'Electronics', 
        count: 125,
        icon: 'e-icons e-mobile',
        products: [
            { id: 'prod1', name: 'Mobile Phones', count: 45, icon: 'e-icons e-phone' },
            { id: 'prod2', name: 'Laptops', count: 30, icon: 'e-icons e-laptop' }
        ]
    }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: categories, 
        value: 'id', 
        text: 'name', 
        child: 'products',
        iconCss: 'icon'
    },
    itemTemplate: `
        <div class="category-item">
            <i class="\${icon}"></i>
            <span>\${name}</span>
            <span class="badge">\${count}</span>
        </div>
    `,
    change: (args) => {
        filterProductsByCategories(args.value);
    }
});
ddtree.appendTo('#categorySelector');

権限／役割の管理

シナリオ：選択的な有効化を伴う、複数レベルの権限階層

let permissions = [
    { id: 'admin', name: 'Admin', hasChild: true },
    { id: 'admin-users', pid: 'admin', name: 'Manage Users' },
    { id: 'admin-system', pid: 'admin', name: 'System Settings' },
    { id: 'user', name: 'User', hasChild: true, disabled: true },
    { id: 'user-profile', pid: 'user', name: 'Edit Profile' }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: permissions, 
        value: 'id', 
        text: 'name', 
        parentValue: 'pid',
        hasChildren: 'hasChild'
    },
    showCheckBox: true,
    showSelectAll: true,
    selectAllText: 'Grant All Permissions',
    unSelectAllText: 'Revoke All Permissions',
    treeSettings: { autoCheck: true },
    change: (args) => {
        savePermissionsToRole(args.value);
    }
});
ddtree.appendTo('#permissionSelector');

---

次のステップ

1. references/getting-started.md から始めて、依存関係をインストールし、最初のコントロールを作成します
2. データソースを選択し、references/data-binding.md の該当するパターンに従います
3. 複数選択が必要な場合は、チェックボックスを有効にします（references/checkbox-features.md）
4. 必要に応じて、テンプレートで外観をカスタマイズします（references/templates-and-customization.md）
5. 実装時に必要に応じて、この API ドキュメントを参照します

特定の機能や高度なシナリオの実装についてサポートが必要な場合は、上記の該当するガイドを参照してください。