syncfusion-vue-data-manager

Syncfusion Vue DataManager：総合ガイド

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

次のような場合に、このスキルを参照してください。

• Vue 2、Vue 3、または Quasar で DataManager をセットアップする
• データをバインドする（ローカル配列またはリモート API）
• Query クラスでデータを クエリおよびフィルター処理する
• CRUD 操作（挿入、更新、削除）
• アダプターを選択する（利用可能な 10 種類）
• ミドルウェア／ヘッダーを介して 認証を追加する
• キャッシュで パフォーマンスを最適化する
• データ永続化を使用して オフラインで作業する
• Composition API と Options API の パターンに関するガイダンス

---

🛑 必須のユーザー確認ゲート：アダプターの選択（最初にお読みください）

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

ユーザーがアダプターの種類を明示せずにサービス URL を提示した場合、エージェントは必ず次の操作を行う必要があります。

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

ゲートの適用条件 — 例

ユーザープロンプト	ゲートが必要ですか？
"このサービス URL（http://myapi.com/employees）を使って従業員アプリを作成してください"	✅ はい — アダプターが指定されていません
"GridComponent を http://myserver/api/data に接続してください"	✅ はい — 「API」だけでは曖昧です
"https://myserver/odata/employees の OData v4 エンドポイントを使用してください"	❌ いいえ — OData v4 が明示されています
"バックエンドが https://myserver/api/orders で { Items, Count } を返します"	❌ いいえ — WebApiAdaptor のパターンが確認されています
"http://custom-url に REST サービスがあります"	✅ はい — REST だけでは曖昧です（UrlAdaptor、WebApiAdaptor、ODataV4 のいずれか）
"グリッドをローカルリストデータにバインドしてください"	❌ いいえ — ローカルバインディングのため、アダプターは不要です

📄 ゲートの完全なテンプレート、アダプター早見表、識別のための質問、およびセキュリティルール： → references/adaptor-decision-gate.md

---

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

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

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

リモートサービスにバインドする場合、次の保護策を必ず実装してください。

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

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

主なコンセプトの概要

コンセプト	使用する場面	参照先
セットアップ	インストールと初期設定	setup-vue-2.md、setup-vue-3.md、setup-quasar.md
データバインディング	データソースの接続	data-binding.md
クエリ	フィルタリング、並べ替え、ページネーション	querying.md
CRUD	レコードの挿入、更新、削除	crud-operations.md
アダプター	データソースの種類の選択	adaptors-guide.md
キャッシュ	パフォーマンスの最適化	caching.md
ミドルウェア	認証、変換	middleware.md
ヘッダー	HTTP ヘッダーのカスタマイズ	how-to-headers.md
パラメーター	追加のクエリパラメーターの送信	how-to-parameters.md
オフライン	インターネットに接続せずに作業	how-to-offline.md

---

📊 フレームワークと API の対応状況

機能	Vue 2	Vue 3	Quasar	Composition	Options
セットアップ	✅	✅	✅	-	✅
Composition API	-	✅	✅	✅	-
ローカルデータ	✅	✅	✅	✅	✅
リモートデータ	✅	✅	✅	✅	✅
10 種類のアダプター	✅	✅	✅	✅	✅
CRUD	✅	✅	✅	✅	✅
クエリ	✅	✅	✅	✅	✅
キャッシュ	✅	✅	✅	✅	✅
ミドルウェア	✅	✅	✅	✅	✅

---

🚀 クイックスタート

Vue 3 Composition API（推奨）

import { onMounted, ref } from 'vue';
import { DataManager, Query, ODataV4Adaptor } from '@syncfusion/ej2-data';

export default {
  setup() {
    const items = ref([]);

    onMounted(async () => {
      const dm = new DataManager({
        url: 'url',
        adaptor: new ODataV4Adaptor()
      });

      try {
        const result = await dm.executeQuery(new Query().take(10));
        items.value = result.result;
      } catch (error) {
        console.error('Error:', error);
      }
    });

    return { items };
  }
}

Vue 2 Options API

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

export default {
  data() {
    return { items: [] };
  },
  mounted() {
    const dm = new DataManager({
      url: 'url',
      adaptor: new ODataV4Adaptor()
    });

    dm.executeQuery(new Query().take(10))
      .then((result) => {
        this.items = result.result;
      })
      .catch((error) => {
        console.error('Error:', error);
      });
  }
}

---

📖 ドキュメントのナビゲーション

🛑 アダプター選択ゲート（人による承認 — リモート URL では最初に必ず実施）

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

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

はじめに（フレームワークを選択）

DataManager を初めて使う方はこちらから：

📄 setup-vue-2.md — Options API を使用した Vue 2

• Vue CLI のインストール
• Vue 2 のライフサイクルパターン
• 最初の DataManager の例

📄 setup-vue-3.md — Composition API と Options API を使用した Vue 3

• Vite プロジェクトのセットアップ
• reactive() と ref()
• onMounted のライフサイクル
• パフォーマンスのヒント

📄 setup-quasar.md — Quasar Framework

• Quasar CLI の初期設定
• ブートファイルの設定
• Q-Grid の統合
• ビルドの最適化

---

コア機能

データバインディングについて：

📄 data-binding.md

• ローカルデータバインディング（json プロパティ）
• リモートデータバインディング（url + アダプター）
• HTTP ステータス別のエラー処理
• Promise パターン

データの操作（CRUD）：

📄 crud-operations.md

• insert() — 新しいレコードの追加
• update() — 既存レコードの変更
• remove() — レコードの削除
• saveChanges() を使った一括操作
• update/remove メソッドの keyField

クエリとフィルタリング：

📄 querying.md

• from() — リソースの指定
• select() — フィールドの選択
• where() — 条件のフィルタリング
• orderBy() — 並べ替え
• take/skip — ページネーション
• search() — 全文検索
• group() — データのグループ化

---

データアダプター（10 種類）

適切なアダプターの選択：

📄 adaptors-guide.md

• JsonAdaptor — ローカルのインメモリー配列
• ODataAdaptor — OData v3 サービス
• ODataV4Adaptor — OData v4 エンドポイント
• UrlAdaptor — 汎用 REST API
• WebApiAdaptor — ASP.NET Web API（Items、Count 形式）
• WebMethodAdaptor — ASP.NET Web メソッド
• RemoteSaveAdaptor — クライアント側のクエリ＋サーバー側の CRUD
• GraphQLAdaptor — GraphQL エンドポイント
• CustomDataAdaptor — カスタムのリクエスト／レスポンス
• CustomAdaptor — 組み込みアダプターの拡張

選択用の決定木と比較表が含まれています。

---

高度な機能

パフォーマンスの最適化：

📄 caching.md

• enableCache プロパティ
• キャッシュの仕組み
• 自動クリアのルール
• 有効化／無効化するタイミング

リクエストのカスタマイズ：

📄 middleware.md

• applyPreRequestMiddlewares() — リクエストを変更
• applyPostRequestMiddlewares() — レスポンスを変換
• カスタムヘッダーの追加
• 認証トークンの挿入

---

ハウツーガイド

よくあるタスクをすばやく解決：

📄 how-to-headers.md

• 静的ヘッダーの追加
• リクエストごとの動的ヘッダー
• JWT／Bearer 認証
• コンテンツネゴシエーション

📄 how-to-parameters.md

• 追加のクエリパラメーターの送信
• カスタム API 形式
• アダプターごとに異なるパラメータースタイル

📄 how-to-offline.md

• オフラインモードの有効化
• localStorage への永続化
• 同期戦略
• 競合の解決

🔒 セキュリティ警告： localStorage と sessionStorage は、ブラウザー内にデータを暗号化せずに保存します。永続化された TreeGrid の状態に、機密データ（パスワード、トークン、PII、支払い情報、ユーザーの秘密情報、認証情報）を絶対に保存しないでください。状態の永続化は、UI の状態のみ（展開／折りたたみの状態、ページ番号、並べ替え順、列の表示／非表示、フィルターの選択）の保存に安全です。機密性の高い設定やユーザーデータには、代わりに安全なサーバー側セッションストレージを使用してください。

---

🎯 よくあるパターン

ローカルデータのバインド

// Vue 3 Composition API
import { ref } from 'vue';
import { DataManager, Query, JsonAdaptor } from '@syncfusion/ej2-data';

const items = ref([]);

const data = [
  { OrderID: 10248, CustomerID: 'VINET', Freight: 32.38 },
  { OrderID: 10249, CustomerID: 'TOMSP', Freight: 11.61 }
];

const dm = new DataManager({ json: data, adaptor: new JsonAdaptor() });
items.value = dm.executeLocal(new Query().take(10));

エラー処理を伴うリモートデータ

const dataManager = new DataManager({
  url: 'url',
  adaptor: new WebApiAdaptor()
});

dataManager.executeQuery(new Query().take(10))
  .then((result) => {
    console.log('Success:', result.result);
  })
  .catch((error) => {
    const statusCode = error.status;
    if (statusCode === 401) {
      console.error('Unauthorized - please login');
    } else if (statusCode === 404) {
      console.error('Data not found');
    } else if (statusCode === 0) {
      console.error('Network error');
    }
  });

Vue 3 Composition API を使ったフィルタリング

import { ref, computed } from 'vue';
import { Query } from '@syncfusion/ej2-data';

const dm = new DataManager({ json: allData });
const searchText = ref('');

const filteredData = computed(() => {
  if (!searchText.value) return allData;
  
  return dm.executeLocal(
    new Query().where('CustomerID', 'contains', searchText.value)
  );
});

認証ミドルウェア

🔒 セキュリティ警告： localStorage と sessionStorage は、ブラウザー内にデータを暗号化せずに保存します。永続化された TreeGrid の状態に、機密データ（パスワード、トークン、PII、支払い情報、ユーザーの秘密情報、認証情報）を絶対に保存しないでください。状態の永続化は、UI の状態のみ（展開／折りたたみの状態、ページ番号、並べ替え順、列の表示／非表示、フィルターの選択）の保存に安全です。機密性の高い設定やユーザーデータには、代わりに安全なサーバー側セッションストレージを使用してください。

const dataManager = new DataManager({
  url: 'url',
  adaptor: new WebApiAdaptor()
});

// Apply middleware to add auth token
dataManager.applyPreRequestMiddlewares([
  async (context) => {
    const token = localStorage.getItem('auth_token');
    context.request.headers['Authorization'] = `send_token`;
  }
]);

---

🔧 DataManager の設定

const dataManager = new DataManager({
  // Data source
  url: 'url',        // Remote endpoint
  json: localArray,                            // Local array
  
  // Adaptor selection
  adaptor: new WebApiAdaptor(),              // Adaptor type
  
  // Headers & auth
  headers: [...],
  
  // Network settings
  crossDomain: true,                          // Enable CORS
  offline: false,                             // Offline mode
  enableCache: true,                          // Caching
  
  // Persistence
  enablePersistence: true,                    // Enable state persistence
  id: 'dataManager_vue',                      // Persistence ID
  ignoreOnPersist: ['temp', 'debug'],        // Properties to exclude
  timeZoneHandling: true                      // Timezone offset handling
});

---

❌ よくあるエラーと解決策

エラー	原因	解決策
401 Unauthorized	認証トークンがない／期限切れ	新しいトークンを使うミドルウェアを追加
404 Not Found	エンドポイント URL の誤り	API エンドポイント URL を確認
0（Network Error）	インターネット接続なし	オフラインモードを有効化
Cross-Origin Error	CORS が有効でない	crossDomain: true を設定

---

✅ ベストプラクティス

1. 必ずアダプターを設定する — バックエンドに適したアダプターを選択します
2. CRUD メソッドに keyField を渡す — update／delete では最初のパラメーターとして必須です
3. async／await を使用する — .then()／.catch() より読みやすくなります
4. エラー処理を追加する — HTTP エラーを捕捉します
5. キャッシュを有効にする — サーバーへのリクエストを減らします
6. ミドルウェアを使用する — 認証を全体に追加します
7. 両方の API をテストする — Composition と Options のパターン
8. ネットワークエラーに対応する — ステータスコード 0 はインターネットに接続されていないことを意味します
9. 型付きインターフェースを使用する — TypeScript に対応しています

---