syncfusion-react-data-manager

Syncfusion React DataManager

DataManager は、React アプリケーションでローカルおよびリモートのデータ操作を管理するゲートウェイコンポーネントです。複雑なサーバー通信コードを記述せずに、データバインディング、クエリ、CRUD 操作、キャッシュ、ミドルウェアのカスタマイズをシームレスに実行できる抽象化レイヤーとして機能します。

次のようなニーズがある場合は、このスキルを使用してください。

• ローカルまたはリモートのデータソースを UI コンポーネントにバインドする
• データをクエリする（フィルター、並べ替え、ページ分割、グループ化、検索）
• CRUD 操作を実行する（挿入、更新、削除、一括編集）
• さまざまなデータソース（JSON、OData、REST API、GraphQL など）を使用する
• パフォーマンス向上のためにデータをキャッシュする
• オフラインモードを実装する
• カスタムヘッダーまたは認証を追加する
• リクエスト／レスポンスのデータを変換する
• React アプリケーションで複雑なデータシナリオに対応する

---

🛑 必須の人間による確認：アダプターの選択（最初にお読みください）

これは、このスキルで最も重要なルールです。省略したり、回避したりすることはできません。

ユーザーがアダプターの種類を明示せずにサービス URL を提示した場合、エージェントは必ず次の操作を行ってください。

1. コード生成を直ちに停止する
2. 読み込む： references/adaptor-decision-gate.md（ファイル全体）
3. 提示する： そのファイル内のテンプレートを使用して、確認事項をユーザーに提示する
4. 待機する： アダプターの選択について、ユーザーから明示的な確認を得る
5. その後に限り、 確認済みのアダプターを使用して DataManager コードを生成する

確認が必要となる条件 — 例

ユーザーのプロンプト	確認が必要ですか？
"Build an employee app using this service URL (http://myapi.com/employees)"	✅ はい — アダプターが指定されていません
"Connect GridComponent to http://myserver/api/data"	✅ はい — 「API」では特定できません
"Use OData v4 endpoint at https://myserver/odata/employees"	❌ いいえ — OData v4 が明示されています
"My backend returns { Items, Count } at https://myserver/api/orders"	❌ いいえ — WebApiAdaptor のパターンが確認できます
"I have a REST service at http://custom-url"	✅ はい — REST だけでは特定できません（UrlAdaptor、WebApiAdaptor、ODataV4 のいずれか）
"Bind the grid to local list data"	❌ いいえ — ローカルバインディングなので、アダプターは不要です

📄 確認用テンプレート、アダプター早見表、識別のための質問、セキュリティルールの全文： → references/adaptor-decision-gate.md

---

⚠️ セキュリティと信頼境界

• このスキルが生成するのはコードのみです。エージェントはデータ操作を実行したり、リモートエンドポイントを取得したりしません。DataManager による操作はすべて、実行時にユーザーのアプリケーション内でのみ行われます。
• 生成されたコードでは、すべてのサードパーティ API レスポンスを信頼できない入力として扱い、検証されていない URL やユーザーが指定した URL へのバインドを避け、すべてのリモートエンドポイントで認証が適用されるようにしてください。

DataManager を使用する場面

DataManager は、次のような場合に最適です。

• 柔軟なデータ管理 → あらゆるデータソース（ローカル、REST、OData、GraphQL）に対応します
• 複雑なクエリ → フィルタリング、並べ替え、ページ分割、グループ化、検索
• CRUD 操作 → 一括処理とトランザクションパターンに対応します
• ミドルウェアのカスタマイズ → リクエスト前後のフック
• オフラインサポート → 接続復旧時にキャッシュおよび同期します
• アダプターの切り替え → コードを変更せずにデータソースを切り替えます

次のような場合は、コンポーネントへの直接バインディング（Grid、Scheduler など）が適しています。

• 複雑なクエリを使わず、基本的なデータバインディングのみが必要な場合
• 非常に大規模なデータセットでパフォーマンスが最優先の場合
• ミドルウェアのカスタマイズが不要な場合

⚠️ 重大なセキュリティ要件

リモートサービスに接続する場合、以下の保護対策を必ず実装してください。

1. HTTPS のみを使用する — 暗号化されていない HTTP 接続は決して使用せず、転送中のすべてのデータを暗号化します。
2. URL には文字列変数を使用する — エンドポイントをマークアップに直接記述せず、プライベートな文字列プロパティに割り当てます。これにより、一元的な検証と保守が容易になります。
3. レスポンスを検証してサニタイズする — サーバー側でスキーマ検証を実装し、想定外のレスポンス形式を拒否して、レスポンスを厳密に型付けされたモデルにマッピングします。
4. リモート呼び出しを監視する — セキュリティ監査証跡として、すべての外部 API リクエストについて、タイムスタンプ、エンドポイント、結果をログに記録します。
5. CORS を安全に実装する — 信頼できる特定のオリジンのみを使用します。本番環境ではワイルドカード * を決して使用せず、HTTPS を必須にします。
6. 間接的なプロンプトインジェクション攻撃を防ぐ — エンドポイントの所有者を確認し、リクエスト署名を実装して、データを使用する前にレスポンスのコンテンツタイプとスキーマを検証します。

サードパーティ API のレスポンスは、セキュリティリスクをもたらす可能性があります。 エンドポイントの正当性を必ず確認し、リクエストを認証してから、UI コンポーネントにデータをバインドする前に検証してください。

主な概念

データバインディング

json プロパティ（ローカル配列）または url プロパティ（リモート API）を使用して、DataManager をデータソースに接続します。クエリメソッドは、ローカルデータには executeLocal()、リモートデータには executeQuery() を使用します。

Query クラス

Query クラスを使用して構造化クエリを構築します。from()、where()、select()、sortBy()、take()、expand()、group() を連結することで、強力なデータ操作を実行できます。

アダプター

アダプター は、DataManager がさまざまなデータソースと通信できるようにするインターフェースです。

• JsonAdaptor → ローカルの JavaScript 配列
• ODataAdaptor → OData v3 サービス
• ODataV4Adaptor → OData v4 サービス
• UrlAdaptor → 汎用 REST エンドポイント
• WebApiAdaptor → ASP.NET Web API
• RemoteSaveAdaptor → クライアント側クエリとサーバー側 CRUD のハイブリッド
• WebMethodAdaptor → レガシーな ASP.NET ASMX サービス
• GraphQLAdaptor → GraphQL エンドポイント
• CustomAdaptor → 独自サービス向けのカスタム実装

CRUD 操作

• insert() → データソースにレコードを追加します
• update() → 既存のレコードを変更します（keyField は最初のパラメーターです）
• remove() → レコードを削除します（keyField は最初のパラメーターです）
• saveChanges() → 複数の操作を単一のリクエストにまとめます

ミドルウェアとカスタマイズ

• applyPreRequestMiddlewares() → 送信前にリクエストを変更します（認証トークン、ヘッダー）
• applyPostRequestMiddlewares() → バインド前にレスポンスを変換します（書式設定、フィルタリング）
• 独自 API 向けのカスタムアダプター
• リクエスト失敗時のエラーハンドラー

キャッシュとパフォーマンス

• enableCache → 読み込み済みのページを再リクエストしないようにします
• オフラインモード → データをローカルに保存し、接続が復旧したときに同期します
• オンデマンド読み込み → ユーザーのスクロールに応じてデータを遅延読み込みします（仮想スクロール）
• 遅延操作 → Promise ベースの async/await パターン

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

現在のタスクに応じて、参照ファイルを選択してください。

🛑 アダプター選択ゲート（人による承認 — リモート URL に対する必須の最初の手順）

📄 参照: references/adaptor-decision-gate.md

• 開始条件: ユーザーがアダプターを明示的に指定せずにサービス URL を提供した場合
• ゲートの提示テンプレート（コピーしてすぐに使用可能）
• アダプターの詳細な比較表（ODataV4 / OData / WebAPI / URL / GraphQL / Custom）
• コード例付きのアダプター早見表
• 曖昧さを解消するための追加質問
• ゲートの確認後に適用されるセキュリティルール
• ステージ 1 とステージ 3 の統合手順（コンポーネントマッピング JSON で曖昧な URL にフラグを設定）
• ゲートを自動的に解決するキーワード（ユーザーによる確認は不要）

セットアップの開始

📄 参照： references/getting-started.md

• インストール手順（npm）
• プロジェクトのセットアップとインポート
• DataManager の基本的な初期化
• 最初のクエリの実行
• 環境のセットアップ
• よくあるエラーと解決方法

データバインディングの方式

📄 参照： references/data-binding.md

• json プロパティを使用したローカルデータバインディング
• url プロパティを使用したリモートデータバインディング
• クライアント側のクエリに使用する executeLocal()
• サーバーリクエストに使用する executeQuery()
• データソースの切り替え
• レスポンス形式の処理
• 各方式を使う場面

クエリ操作とフィルタリング

📄 参照： references/querying-and-filtering.md

• Query クラスの基本
• where() と Predicate を使ったフィルタリング
• 並べ替え（昇順／降順）
• take() と skip() によるページネーション
• select() によるフィールドの射影
• expand() による関連データの読み込み
• フィールドによるデータのグループ化
• 複数条件を組み合わせた複雑なクエリ
• クエリ操作の連結

CRUD 操作と一括編集

📄 参照： references/crud-operations.md

• insert() → 新しいレコードを追加
• update() → 既存のレコードを変更
• remove() → レコードを削除
• CRUD メソッドのパラメーターにおける keyField
• 一括操作に使用する saveChanges()
• 一括での挿入／更新／削除
• トランザクションのパターン
• 操作前のデータ検証
• レスポンスの処理

アダプターの選択と使用

📄 参照： references/adaptors-guide.md

• 使用するアダプターの選び方（判断ツリー）
• ローカル配列向けの JsonAdaptor
• OData アダプター（v3 および v4）
• REST API アダプター（Url、WebApi）
• ハイブリッド方式の RemoteSaveAdaptor
• レガシー ASMX（WebMethodAdaptor）
• GraphQL エンドポイントの統合
• カスタムアダプターの実装
• CORS と crossDomain の設定
• プラットフォーム固有のレスポンス処理

ミドルウェアとリクエストのカスタマイズ

📄 参照： references/middleware-customization.md

• 認証トークン用のリクエスト前ミドルウェア
• カスタムヘッダーの挿入
• リクエストの変換
• レスポンスマッピング用のリクエスト後ミドルウェア
• エラーハンドラー関数
• ミドルウェア内でのデータ検証とフィルタリング
• カスタムアダプターの実装
• ミドルウェアの実行順序とタイミング

キャッシュとオフラインモード

📄 参照： references/caching-offline-mode.md

• パフォーマンス向上のための enableCache プロパティ
• キャッシュがクリアされるタイミング（並べ替え、フィルタリング、CRUD）
• オフラインモードの実装
• ローカルストレージへの永続化
• 再接続後の同期方式
• キャッシュサイズとメモリ管理
• ベストプラクティスとパフォーマンスパターン

高度な機能とパターン

📄 参照： references/advanced-features.md

• オンデマンド読み込みとページネーションのパターン
• 仮想スクロールのセットアップ
• 遅延データ読み込み
• 遅延実行（Promise API）
• DataManager での async/await
• セッションをまたいだ状態の永続化
• メモリ管理
• エラー処理の戦略
• パフォーマンス最適化のヒント
• よくある落とし穴と解決方法

クイックスタートの例

import React, { useEffect, useState } from 'react';
import { DataManager, WebApiAdaptor, Query } from '@syncfusion/ej2-data';

export default function DataManagerDemo() {
  const [items, setItems] = useState([]);

  useEffect(() => {
    // Create DataManager with remote data source
    const dataManager = new DataManager({
      url: 'url',
      adaptor: new WebApiAdaptor(),
      crossDomain: true
    });

    // Execute query with filtering, sorting, paging
    dataManager.executeQuery(
      new Query()
        .where('Freight', 'greaterthan', 500) // Filter
        .sortBy('OrderDate') // Sort
        .take(10) // Pagination
    ).then((e) => {
      setItems(e.result); // Bind results
    });
  }, []);

  return (
    <div>
      <h2>Orders</h2>
      <ul>
        {items.map((item) => (
          <li key={item.OrderID}>{item.CustomerID} - ${item.Freight}</li>
        ))}
      </ul>
    </div>
  );
}

よくあるユースケース

ケース 1：フィルタリングしながらローカルデータを表示する → JsonAdaptor + Query + where() を使ってクライアント側でフィルタリングします

ケース 2：認証を使用してサーバーデータを取得する → WebApiAdaptor + applyPreRequestMiddlewares() を使ってトークンを挿入します

ケース 3：オフラインで作業し、後で同期する → enableCache + オフラインモード + saveChanges() を使って一括同期します

ケース 4：複雑なネストされたデータの関係 → ODataV4Adaptor または RemoteSaveAdaptor + expand() を使って関連データを取得します

ケース 5：GraphQL バックエンド → カスタムクエリビルダーとともに GraphQLAdaptor を使います

ケース 6：レガシー ASP.NET ASMX サービス → 適切なレスポンスマッピングとともに WebMethodAdaptor を使います

主なプロパティとオプション

プロパティ	型	目的
json	Array	オブジェクトのローカル JavaScript 配列
url	string	リモートサーバーのエンドポイント URL
adaptor	Adaptor	JsonAdaptor、ODataAdaptor、WebApiAdaptor など
enableCache	boolean	冗長なリクエストを防ぐためにページをキャッシュします
offline	boolean	ローカルストレージを使用してオフラインモードを有効にします
crossDomain	boolean	異なるドメインへの CORS リクエスト

比較：DataManager と直接バインディング

機能	DataManager	直接バインディング
柔軟なアダプター	✓ 簡単に切り替え可能	✗ 1 つのデータソースに固定
複雑なクエリ	✓ チェーン可能な Query クラス	✗ フィルタリング機能が限定的
CRUD 操作	✓ バッチ処理を含む完全なサポート	✗ 基本的な操作
ミドルウェア	✓ 前後のフック	✗ なし
キャッシュ	✓ 組み込み	✗ 手動で実装
オフラインモード	✓ 組み込み	✗ 手動で実装
パフォーマンス（小規模なデータセット）	≈ 同等	✓ やや高速
パフォーマンス（大規模なデータセット）	✓ 遅延読み込みをサポート	✗ 一度にすべてを読み込み

柔軟性、キャッシュ、ミドルウェアが必要なデータ駆動型アプリケーションを構築する場合は、DataManager を使用してください。

複雑なクエリやオフラインサポートが不要な、シンプルで一度限りの表示には、直接バインディングを使用してください。