syncfusion-react-dropdownlist

Syncfusion React DropDownList

DropDownList コンポーネントは、ユーザーが単一の値を選択できる、あらかじめ定義された値の一覧を提供します。ローカルおよびリモートのデータバインディング、フィルタリング、グループ化、カスタムテンプレート、仮想スクロール、アクセシビリティ、豊富なカスタマイズに対応しています。

ナビゲーションガイド

はじめに

📄 参照: references/getting-started.md

• インストールとパッケージの設定（@syncfusion/ej2-react-dropdowns）
• tailwind3 テーマでの CSS インポート
• 基本的な DropDownList（関数コンポーネントとクラスコンポーネント）
• データソースのバインド
• ポップアップの高さと幅の設定

データバインディングと値のバインディング

📄 参照: references/data-binding.md

• プリミティブ配列（文字列、数値）のバインド
• fields マッピング（text、value、groupBy、iconCss）を使った JSON オブジェクト配列のバインド
• DataManager を使ったリモートデータ（OData、ODataV4、WebAPI アダプター）
• 値のバインディング：値の事前選択、プリミティブオブジェクトと複合オブジェクトのバインド
• fields.disabled を使った個別項目の無効化

⚠️ ネットワークに関する注意: DataManager をリモートアダプター（ODataAdaptor、ODataV4Adaptor、WebApiAdaptor）とともに使用すると、実行時にコンポーネントから外部への HTTP リクエストが送信されます。本番環境でリモートデータバインディングを設定する前に、すべてのリモートエンドポイントが信頼でき、認証されており、機密データが公開されないことを確認してください。

フィルタリング

📄 参照: references/filtering.md

• allowFiltering を有効にして、入力と同時に検索
• updateData を使った filtering イベントの処理
• デフォルトのフィルタリングを防止 — カスタムハンドラーでは常に args.preventDefaultAction = true を設定してください
• フィルターの種類：startswith、contains、endsWith、大文字と小文字を区別するオプション
• 複数フィールドでのフィルタリング — Predicate と .or() を使って、入力されたテキストを text フィールドと value フィールド（または任意の組み合わせ）に対して照合します
• 最小文字数のガードを備えたリモート／サーバーサイドのフィルタリング
• 発音区別符号のフィルタリング（ignoreAccent）、遅延時間
• フィルター済みテキストの強調表示、カスタム検索ロジック

グループ化とテンプレート

📄 参照: references/grouping-and-templates.md

• groupBy フィールドを使った項目のグループ化
• 固定グループヘッダーとインラインのグループヘッダー
• カスタムグループヘッダーテンプレート
• 項目テンプレート、値（選択済み）テンプレート
• ヘッダーおよびフッターのテンプレート
• レコードなしおよびアクション失敗時のテンプレート

機能と設定

📄 参照: references/features-and-configuration.md

• 並べ替え（sortOrder：昇順、降順）
• 大規模なリストでの仮想スクロール（enableVirtualization）
• ポップアップのサイズ変更（allowResize）
• インクリメンタルサーチ、クリアボタン、読み取り専用、無効化
• RTL 対応、Preact の使用

アクセシビリティ、スタイル設定、ローカライズ

📄 参照: references/accessibility-styling-localization.md

• WCAG 2.2／Section 508 への準拠
• キーボードナビゲーションのショートカット
• ARIA ロールと属性
• cssClass プロパティ — インスタンスごとのスコープ付き CSS クラス、複数クラス、条件付きクラス、組み込みユーティリティクラス（e-error、e-success）
• CSS クラスのカスタマイズ（ラッパー、アイコン、ポップアップ、リスト項目、プレースホルダー）
• テーマ（tailwind3、material3、bootstrap5、fluent2）
• ローカライズ（L10n、noRecordsTemplate、actionFailureTemplate）
• RTL レイアウト（enableRtl）

API リファレンス

📄 参照: references/api.md

• 型、デフォルト値、使用例を含むすべてのプロパティのリファレンス
• シグネチャ、パラメーター、戻り値の型を含むすべてのメソッド
• 引数インターフェイスと使用例を含むすべてのイベント
• インターフェイスの詳細：FieldSettingsModel、ChangeEventArgs、SelectEventArgs、PopupEventArgs、FilteringEventArgs
• プロパティ、メソッド、イベントのクイックリファレンス用まとめ表

ハウツーパターン

📄 参照： references/how-to.md

• 項目を動的に追加、削除、変更する
• 連動（依存）ドロップダウン
• 複数の連動ドロップダウン
• リモートデータのハウツー
• スクロール時にポップアップを閉じる、項目にツールチップを表示する、項目にアイコンを表示する
• 値変更イベント、選択値をクリアする

---

クイックスタートの例

ステップ 1 — パッケージをインストールする パッケージマネージャーを使用します（インストール前に、パッケージが公式 Syncfusion npm レジストリに掲載されていることを確認してください）。

npm install @syncfusion/ej2-react-dropdowns --save

⚠️ サプライチェーンに関する注意： @syncfusion/ej2-react-dropdowns は、Syncfusion Inc. が公開しているサードパーティ製パッケージです。本番環境へのデプロイ前に、必ず package.json で特定の検証済みバージョンを固定し（例："@syncfusion/ej2-react-dropdowns": "27.x.x"）、ロックファイル（package-lock.json または yarn.lock）を使って整合性を検証してください。

ステップ 2 — CSS のインポートを追加する src/App.css に追加します。

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

ステップ 3 — コンポーネントを使用する：

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
import './App.css';

export default function App() {
  const sportsData: string[] = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <DropDownListComponent
      id="ddlelement"
      dataSource={sportsData}
      placeholder="Select a game"
    />
  );
}

よく使われるパターン

フィールドをマッピングした JSON オブジェクトデータ

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

export default function App() {
  const countryData = [
    { Id: 'au', Country: 'Australia' },
    { Id: 'br', Country: 'Brazil' },
    { Id: 'cn', Country: 'China' },
    { Id: 'in', Country: 'India' },
  ];
  const fields = { text: 'Country', value: 'Id' };

  return (
    <DropDownListComponent
      dataSource={countryData}
      fields={fields}
      placeholder="Select a country"
    />
  );
}

フィルタリング（入力と同時に検索）

import { DropDownListComponent, FilteringEventArgs } from '@syncfusion/ej2-react-dropdowns';
import { Query } from '@syncfusion/ej2-data';

export default function App() {
  const searchData = [
    { Index: 's1', Country: 'Alaska' },
    { Index: 's2', Country: 'California' },
    { Index: 's3', Country: 'Florida' },
  ];
  const fields = { text: 'Country', value: 'Index' };

  function onFiltering(args: FilteringEventArgs) {
    args.preventDefaultAction = true; // prevent built-in filter from running alongside custom logic
    let query = new Query();
    query = args.text !== '' ? query.where('Country', 'startswith', args.text, true) : query;
    args.updateData(searchData, query);
  }

  return (
    <DropDownListComponent
      dataSource={searchData}
      fields={fields}
      allowFiltering={true}
      filtering={onFiltering}
      placeholder="Select a country"
    />
  );
}

値を事前選択する

<DropDownListComponent
  dataSource={sportsData}
  value="Cricket"
  placeholder="Select a game"
/>

グループ化された項目

const vegetableData = [
  { Vegetable: 'Cabbage', Category: 'Leafy and Salad', Id: 'item1' },
  { Vegetable: 'Chickpea', Category: 'Beans', Id: 'item6' },
  { Vegetable: 'Garlic',   Category: 'Bulb and Stem', Id: 'item9' },
];
const fields = { groupBy: 'Category', text: 'Vegetable', value: 'Id' };

<DropDownListComponent dataSource={vegetableData} fields={fields} placeholder="Select a vegetable" />

主なプロパティ

プロパティ	型	目的
dataSource	any[] | DataManager	リスト項目のデータ
fields	FieldSettingsModel	text、value、groupBy、iconCss、disabled をマッピングします
value	string | number	選択済み／事前選択された値
placeholder	string	入力欄のプレースホルダーテキスト
allowFiltering	boolean	検索フィルタリングを有効にします
filtering	event	カスタムフィルターロジックのハンドラー
popupHeight	string	ポップアップリストの高さ（デフォルトは自動）
popupWidth	string	ポップアップリストの幅（デフォルトは入力欄に合わせます）
sortOrder	SortOrder	'None'、'Ascending'、'Descending'
enableVirtualization	boolean	大量のデータ向けの仮想スクロール
allowResize	boolean	ユーザーによるポップアップのサイズ変更
enabled	boolean	コンポーネント全体を有効／無効にします
readonly	boolean	読み取り専用モード
showClearButton	boolean	選択をクリアする ✕ ボタンを表示します
enableRtl	boolean	右から左へのレイアウト

よくあるユースケース

シンプルな静的リスト → string[] を dataSource に渡せば完了です。

API からのデータ → WebApiAdaptor とともに DataManager を使用します。references/data-binding.md を参照してください。⚠️ リモートアダプターは外部への HTTP 接続を開きます。エンドポイントが信頼できることを確認してください。

入力と同時に検索／フィルタリングする → allowFiltering={true} を設定し、filtering イベントを処理します。references/filtering.md を参照してください。

カテゴリ別の項目 → groupBy フィールドをマッピングします。references/grouping-and-templates.md を参照してください。

カスタムの項目レイアウト → itemTemplate を使用します。references/grouping-and-templates.md を参照してください。

大規模なデータセット（1 万件以上の項目） → enableVirtualization を有効にし、VirtualScroll をインジェクトします。references/features-and-configuration.md を参照してください。

依存するドロップダウン → 1 つ目のドロップダウンの change イベントで、2 つ目のドロップダウンの dataSource を再読み込みします。references/how-to.md を参照してください。