syncfusion-react-listview

Syncfusion React ListView の実装

テンプレート、フィルタリング、選択、データ管理などの高度な機能を備えた、動的でインタラクティブなリストを表示するための Syncfusion React ListView コンポーネントの実装に関する包括的なガイドです。

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

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

• 豊富なテンプレートとカスタマイズ機能を備えた項目リストを表示する
• 単一または複数の項目を選択できるようにする
• リスト項目を動的に追加、削除、更新する
• リストデータをフィルタリングして検索する
• 入れ子またはグループ化されたリストを作成する
• ユーザー操作（スクロール、選択、チェック）を処理する
• カスタムアニメーションとスタイルを適用する
• ドラッグ＆ドロップ操作に対応する
• 仮想化によってパフォーマンスを最適化する
• データバインディング（ローカルまたはリモート）を実装する
• チェックボックスやカスタムアイコンを追加する
• アクセシビリティ機能（WCAG 2.1）を提供する

コンポーネントの概要

ListView コンポーネントは、スクロール可能でインタラクティブなリストに項目のコレクションを表示します。次の機能に対応しています。

• データソース： 配列、オブジェクト、DataManager、リモート API
• 選択モード： なし、単一、複数、またはチェックボックス方式
• テンプレート： 項目テンプレート、ヘッダーテンプレート、グループテンプレート
• データ操作： フィルタリング、並べ替え、グループ化、検索
• パフォーマンス： 1000 件以上の項目に対応する仮想スクロール
• 操作： クリック、選択、スクロールのイベント
• スタイル： 組み込みテーマ、カスタム CSS、RTL 対応
• アクセシビリティ： WCAG 2.1 Level AA 準拠

インストールとセットアップ

ステップ 1：Syncfusion パッケージをインストールする

npm install @syncfusion/ej2-react-lists @syncfusion/ej2-base @syncfusion/ej2-data

ステップ 2：必要なモジュールをインポートする

import { ListViewComponent } from '@syncfusion/ej2-react-lists';
// For additional features:
import { Inject, Virtualization } from '@syncfusion/ej2-react-lists';

ステップ 3：CSS をインポートする

import '@syncfusion/ej2-react-lists/styles/material.css'; // or other themes

クイックスタートの例

import React from 'react';
import { ListViewComponent } from '@syncfusion/ej2-react-lists';

export function BasicListView() {
  const data = [
    { id: '1', text: 'Item 1' },
    { id: '2', text: 'Item 2' },
    { id: '3', text: 'Item 3' }
  ];

  return (
    <ListViewComponent
      id="list"
      dataSource={data}
      fields={{ text: 'text', id: 'id' }}
    />
  );
}

基本概念

1. データバインディング

ローカル配列：

const items = ['Apple', 'Banana', 'Orange'];
<ListViewComponent dataSource={items} />

マッピングを使用したオブジェクト配列：

const data = [
  { productId: 1, productName: 'Laptop', category: 'Electronics' },
  { productId: 2, productName: 'Desk', category: 'Furniture' }
];

<ListViewComponent
  dataSource={data}
  fields={{
    id: 'productId',
    text: 'productName',
    groupBy: 'category'
  }}
/>

2. 選択の処理

const handleSelect = (args) => {
  console.log('Selected item:', args.text, args.id);
};

<ListViewComponent
  dataSource={data}
  select={handleSelect}
/>

3. 項目の管理

• 項目の追加： addItem(data, fields?)
• 項目の削除： removeItem(item)
• 項目の更新： dataSource 内の項目を置き換えて更新する
• 選択項目の取得： getSelectedItems()

4. テンプレート

// Item Template
const itemTemplate = (props) => (
  <div className="e-list-wrapper">
    <span>{props.text}</span>
    <span className="e-list-content">{props.category}</span>
  </div>
);

<ListViewComponent
  dataSource={data}
  fields={fields}
  template={itemTemplate}
/>

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

はじめに

📄 参照： references/getting-started.md

• インストールとインポート
• 基本的なセットアップと最初のコンポーネント
• CSS テーマとスタイル設定
• 最小構成の動作例
• プロジェクト構成

データバインディングとレンダリング

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

• ローカル配列のデータソース
• フィールドを使用したオブジェクトのマッピング
• DataManager を使用したリモートデータ
• リモートデータに対するクエリのフィルタリング
• 必要に応じた読み込みとページネーション
• 動的なデータ更新

項目の管理（CRUD）

📄 参照： references/item-management.md

• 項目を動的に追加する
• 参照を使って項目を削除する
• 既存の項目を更新する
• 一括操作
• リスト内の項目を検索する
• 入れ子になったリスト項目を管理する

選択とフィルタリング

📄 参照： references/selection-filtering.md

• 単一項目の選択
• 複数項目の選択
• チェックボックス方式の選択
• プログラムによる選択
• リスト項目のフィルタリング
• 検索機能
• 選択イベントとコールバック

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

📄 参照： references/templating-customization.md

• カスタム項目テンプレート（JSX、関数、文字列）
• headerTemplate を使用したヘッダーテンプレート
• groupTemplate を使用したグループヘッダーテンプレート
• テンプレートのデータコンテキストと変数
• デバイスに応じた動的なテンプレート
• クラスを使用した CSS のカスタマイズ
• RTL テンプレートへの対応

高度な機能

📄 参照： references/advanced-features.md

• グループ化と並べ替え
• 階層構造の入れ子リスト（最大 3 レベル）
• チェックボックスの状態管理
• アニメーションとエフェクト
• カスタムアイコンと画像の表示
• 項目の有効化・無効化状態
• 複雑なダッシュボード向けのレイアウトパターン

レイアウトと配置のパターン ⭐ 新機能

📄 参照： references/layout-alignment-patterns.md

• 患者ポータルのパターン： ListView とカード、予約、処方箋、メッセージ
• 予約ダッシュボード： フィルター、スケジューラー、分析機能を備えた 3x2 のグリッドレイアウト
• モニタリングダッシュボード： KPI、アラート、チケットを備えた 3x3 のグリッドレイアウト
• よくある配置の問題（スクロール、境界線、間隔）の修正
• モバイル／タブレット／デスクトップ向けのレスポンシブなグリッドレイアウト
• 各パターンの完全なコード例

パフォーマンスと仮想化

📄 参照： references/performance-virtualization.md

• 大規模なデータセット（1000 件以上）向けの仮想スクロール
• 仮想化の有効化
• 項目の高さの更新
• メモリ最適化のヒント
• ページネーションとの併用
• パフォーマンスのベストプラクティス
• データセットのサイズに関する推奨事項

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

📄 参照： references/api-reference.md

• プロパティの完全なドキュメント
• メソッドのシグネチャとパラメーター
• イベントハンドラーの引数
• すべてのプロパティのデフォルト値
• プロパティの型の仕様
• 各 API の使用例

アクセシビリティとイベント

📄 参照： references/accessibility-events.md

• WCAG 2.1 への準拠
• キーボード操作
• スクリーンリーダーのサポート
• ARIA 属性
• フォーカス管理
• イベントのライフサイクル
• イベントの引数とデータ

よくあるパターン

パターン 1：選択機能付きリスト

ユーザーが項目をクリック → 選択イベントが発生 → UI を更新

const [selected, setSelected] = React.useState(null);

const handleSelect = (args) => {
  setSelected(args);
};

<ListViewComponent
  dataSource={items}
  select={handleSelect}
/>

パターン 2：項目の追加と削除

const listViewRef = React.useRef(null);

const addItem = () => {
  listViewRef.current.addItem([{ text: 'New Item', id: Date.now() }]);
};

const removeItem = (item) => {
  listViewRef.current.removeItem(item);
};

<ListViewComponent ref={listViewRef} dataSource={items} />

パターン 3：フィルター付きリスト

const [filteredData, setFilteredData] = React.useState(items);

const handleFilter = (searchText) => {
  const filtered = items.filter(item =>
    item.text.toLowerCase().includes(searchText.toLowerCase())
  );
  setFilteredData(filtered);
};

<ListViewComponent dataSource={filteredData} />

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

<ListViewComponent
  dataSource={items}
  showCheckBox={true}
  fields={{ id: 'id', text: 'text', isChecked: 'checked' }}
/>

パターン 5：カードコンテナー内の ListView（新機能）

<div style={{
  border: '1px solid #e0e0e0',
  borderRadius: '4px',
  overflow: 'hidden',
  display: 'flex',
  flexDirection: 'column'
}}>
  <div style={{
    padding: '16px',
    backgroundColor: '#f5f5f5',
    borderBottom: '1px solid #e0e0e0'
  }}>
    <h3 style={{ margin: 0 }}>Messages</h3>
  </div>
  <div style={{ flex: 1, overflow: 'auto', minHeight: 0 }}>
    <ListViewComponent
      dataSource={items}
      height="100%"
      width="100%"
    />
  </div>
</div>

パターン 6：グリッドレイアウト内の ListView（新機能）

<div style={{
  display: 'grid',
  gridTemplateColumns: 'repeat(3, 1fr)',
  gap: '16px'
}}>
  {/* Card 1 - ListView */}
  <div style={{ border: '1px solid #e0e0e0', display: 'flex', flexDirection: 'column' }}>
    <div style={{ padding: '12px', backgroundColor: '#f5f5f5' }}>Appointments</div>
    <div style={{ flex: 1, overflow: 'auto', minHeight: 0 }}>
      <ListViewComponent dataSource={appointments} height="300px" />
    </div>
  </div>
  {/* Card 2, Card 3, etc. */}
</div>

パターン 7：複数の ListView を使用したダッシュボード（新機能）

以下のガイドを参照してください：レイアウトと配置のパターンガイド

• 🏥 患者ポータル： 予約、メッセージ、処方箋のグリッド
• 📅 予約ダッシュボード： フィルターとスケジューラーを備えた 3x2 のグリッド
• 📊 モニタリングダッシュボード： KPI、ログ、アラート、チケットを備えた 3x3 のグリッド

主なプロパティ

プロパティ	型	デフォルト	用途
dataSource	Array/DataManager	[]	表示するデータ
fields	FieldSettingsModel	defaultMappedFields	データをフィールドにマッピング
template	string/function/JSX	null	カスタム項目テンプレート
headerTemplate	string/function/JSX	null	カスタムヘッダーテンプレート
groupTemplate	string/function/JSX	null	カスタムグループテンプレート
showCheckBox	boolean	false	チェックボックスを表示
checkBoxPosition	'Left'|'Right'	'Left'	チェックボックスの位置
sortOrder	'None'|'Ascending'|'Descending'	'None'	データの並べ替え順
enableVirtualization	boolean	false	仮想スクロール
height	number|string	''	リストの高さ
width	number|string	''	リストの幅
cssClass	string	''	カスタム CSS クラス
enabled	boolean	true	コンポーネントの有効化／無効化
enableRtl	boolean	false	右から左への表示のサポート
animation	AnimationSettings	{...}	項目のアニメーション

主要なメソッド

メソッド	用途
addItem(data, fields?)	リストに新しい項目を追加します
removeItem(item)	リストから項目を削除します
removeMultipleItems(items)	複数の項目を一度に削除します
selectItem(item)	項目を選択します
selectMultipleItems(items)	複数の項目を選択します
unselectItem(item?)	項目の選択を解除します
getSelectedItems()	現在の選択項目を取得します
findItem(item)	項目の詳細を検索します
checkItem(item)	チェックボックス項目にチェックを入れます
uncheckItem(item)	チェックボックス項目のチェックを外します
checkAllItems()	すべての項目にチェックを入れます
uncheckAllItems()	すべての項目のチェックを外します
enableItem(item)	無効な項目を有効にします
disableItem(item)	項目を無効にします
hideItem(item)	項目を非表示にします
showItem(item)	非表示の項目を表示します
back()	ネストされたリストから戻ります
refreshItemHeight()	項目の高さを更新します（仮想化）
destroy()	コンポーネントをクリーンアップします

主要なイベント

イベント	発生するタイミング
select	項目が選択されたとき
actionBegin	何らかの操作が開始されたとき
actionComplete	何らかの操作が完了したとき
actionFailure	リモートデータの取得に失敗したとき
scroll	ユーザーが上端または下端までスクロールしたとき

よくあるユースケース

1. 設定リストの表示： アイコン付きのグループ化された項目
2. 連絡先リスト： 画像付きの複数行テンプレート
3. ネストされたナビゲーション： 階層を掘り下げて表示
4. 絞り込み可能な検索： 動的なデータの絞り込み
5. ToDo リスト： チェックボックスと項目の削除
6. 製品カタログ： ページネーションと絞り込み
7. チャットメッセージ： 日付による逆順のグループ化
8. 通知フィード： 操作機能付きのスクロール
9. 複数選択ピッカー： チェックボックスとボタン
10. 階層メニュー： 戻るナビゲーション付きのネストされた項目

ヒントとベストプラクティス

一般的なベストプラクティス

• ✅ 表示するデータに合わせて fields を正しくマッピングしてください
• ✅ プレーンテキストを超えるリッチな UI にはテンプレートを使用してください
• ✅ 1000 件を超える項目では仮想化を有効にしてください
• ✅ 大量のリモートデータを絞り込み／並べ替えするには DataManager を使用してください
• ✅ 再レンダリングを防ぐため、テンプレートとコールバックをメモ化してください
• ✅ 軽量なカスタマイズには cssClass を使用してください
• ✅ ユーザー操作を処理するには select イベントを使用してください
• ✅ コンポーネントのアンマウント時に destroy() でクリーンアップしてください
• ❌ すべての項目のテンプレートに複雑なコンポーネントを描画しないでください
• ❌ 適切な fields マッピングの設定を忘れないでください

配置とレイアウトのベストプラクティス ⭐

• ✅ フレックスレイアウトを使用する場合は、親コンテナーに必ず明示的な height を設定してください
• ✅ スクロール可能にするには、フレックスの子要素に overflow: 'auto' と minHeight: 0 を設定してください
• ✅ ヘッダーが縮まないように flexShrink: 0 を使用してください
• ✅ 一貫した間隔を保つには、個別のマージンではなくテンプレート内で gap を使用してください
• ✅ ListView がコンテナー全体を埋めるよう、width: '100%' と height: '100%' を設定してください
• ✅ ListView を display: 'flex' と flexDirection: 'column' を指定したフレックスコンテナーで囲んでください
• ✅ ダッシュボードのレイアウトには、適切な gridColumn／gridRow を指定した CSS Grid を使用してください
• ✅ カードコンテナーに overflow: 'hidden' を設定し、境界線の角丸を維持してください
• ❌ 既定のマージンに頼らないでください。配置がずれる原因になります
• ❌ フレックスコンテナーの設定を省略しないでください。ListView には適切な親コンテキストが必要です
• ❌ フレックス内のスクロールコンテナーに minHeight: 0 を設定し忘れないでください

トラブルシューティング

項目が表示されませんか？

• dataSource にデータが設定されていることを確認してください
• fields のマッピングがデータ構造に一致していることを確認してください
• text フィールドが正しくマッピングされていることを確認してください

選択が機能しませんか？

• select イベントハンドラーがバインドされていることを確認してください
• 項目に有効な id フィールドがあることを確認してください
• 項目が無効になっていないことを確認してください

パフォーマンスに問題がありますか？

• enableVirtualization={true} を有効にしてください
• テンプレートの複雑さを軽減してください
• クライアント側ではなくリモートで絞り込むには DataManager を使用してください

スタイルに問題がありますか？

• CSS テーマファイルをインポートしてください
• cssClass がルート要素に適用されていることを確認してください
• CSS の詳細度の競合を調べてください

---

次のステップ：

• ユースケースに応じた適切なリファレンスファイルを読んでください
• API リファレンスでプロパティとメソッドの全ドキュメントを確認してください
• WCAG 準拠のため、アクセシビリティガイドを確認してください
• 特定の機能に関するコード例を確認してください