本頁面由 Cloud Translation API 翻譯而成。

使用產生的 Flutter SDK

Firebase Data Connect 用戶端 SDK 可讓您直接從 Firebase 應用程式呼叫伺服器端查詢和變動。設計要部署至 Data Connect 服務的結構定義、查詢和變動時，您可以平行產生自訂用戶端 SDK。然後將這個 SDK 的方法整合至用戶端邏輯。

如我們在其他地方所述，請務必注意，Data Connect 查詢和突變不會由用戶端程式碼提交，而是在伺服器上執行。而是部署後，Data Connect 作業會儲存在伺服器上，例如 Cloud Functions。也就是說，您需要部署對應的用戶端變更，避免現有使用者 (例如使用舊版應用程式的使用者) 發生問題。

因此 Data Connect 提供開發人員環境和工具，方便您製作伺服器部署的結構定義、查詢和變動原型。此外，在您製作原型時，系統也會自動產生用戶端 SDK。

完成服務和用戶端應用程式的更新疊代後，即可部署伺服器端和用戶端更新。

什麼是客戶開發工作流程？

如果您已按照「開始使用」一文的說明操作，應該已瞭解 Data Connect 的整體開發流程。本指南將詳細說明如何從結構定義產生 Flutter SDK，以及如何處理用戶端查詢和變動。

總而言之，如要在用戶端應用程式中使用產生的 Flutter SDK，請先完成下列必要步驟：

將 Firebase 新增至 Flutter 應用程式。
安裝 flutterfire CLI dart pub global activate flutterfire_cli。
執行 flutterfire configure。

接著：

開發應用程式結構定義。
設定 SDK 產生作業：
- 使用 Data Connect VS Code 擴充功能的「Add SDK to app」(將 SDK 新增至應用程式) 按鈕
- 更新connector.yaml。
初始化用戶端程式碼並匯入程式庫。
實作對查詢的呼叫和異動。
設定及使用 Data Connect 模擬器，並進行疊代。

產生 Flutter SDK

使用 Firebase CLI 在應用程式中設定產生的 SDK。Data Connectinit 指令應會偵測目前資料夾中的所有應用程式，並自動安裝產生的 SDK。

firebase init dataconnect:sdk

在原型設計期間更新 SDK

如果您已安裝 Data Connect VS Code 擴充功能，系統一律會將產生的 SDK 維持在最新狀態。

如果您未使用 Data Connect VS Code 擴充功能，可以透過 Firebase CLI 讓產生的 SDK 維持最新狀態。

firebase dataconnect:sdk:generate --watch

在建構管道中產生 SDK

您可以在 CI/CD 建構程序中使用 Firebase CLI，產生 Data Connect SDK。

firebase dataconnect:sdk:generate

設定用戶端程式碼

初始化 Data Connect 應用程式

首先，請按照標準 Firebase 設定說明初始化應用程式。

然後安裝 Data Connect 外掛程式：

flutter pub add firebase_data_connect

初始化 Data Connect Flutter SDK

使用您設定 Data Connect 時所用的資訊，初始化 Data Connect 執行個體 (所有資訊都可在 Firebase 控制台的「Data Connect」分頁中找到)。

匯入程式庫

如要初始化用戶端程式碼，需要兩組匯入項目：一般 Data Connect 匯入項目，以及特定的產生 SDK 匯入項目。

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

在用戶端使用查詢

產生的程式碼會預先定義查詢參照。您只需要匯入並呼叫 execute 即可。

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

呼叫 SDK 查詢方法

以下是使用這些動作快速鍵函式的範例：

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

選填欄位

部分查詢可能會有選填欄位。在這些情況下，Flutter SDK 會公開建構工具方法，且必須分別設定。

舉例來說，呼叫 createMovie 時，rating 欄位為選用，因此您需要在建構工具函式中提供該欄位。

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi"}).rating(5).execute();

訂閱變更

您可以訂閱變更 (每次執行查詢時都會更新)。

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`

處理列舉欄位的變更

應用程式的結構定義可以包含列舉，可供 GraphQL 查詢存取。

隨著應用程式設計變更，您可能會新增支援的列舉值。舉例來說，假設您在應用程式生命週期的稍後階段，決定將 FULLSCREEN 值新增至 AspectRatio 列舉。

在 Data Connect 工作流程中，您可以使用本機開發工具更新查詢和 SDK。

不過，在您發布用戶端更新版本之前，舊版已部署的用戶端可能會中斷。

具備復原機制的導入範例

產生的 SDK 會強制處理不明的值。也就是說，用戶端程式碼必須將 EnumValue 物件解壓縮為 Known 或 Unknown。

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print("This movie is in Academy aspect");
        break;
      case AspectRatio.WIDESCREEN:
        print("This movie is in Widescreen aspect");
        break;
      case AspectRatio.ANAMORPHIC:
        print("This movie is in Anamorphic aspect");
        break;
      case AspectRatio.IMAX:
        print("This movie is in IMAX aspect");
    }
  } else {
    print("Unknown aspect ratio detected: ${aspectValue.stringValue}");
  }
}

在用戶端使用變異

變動作業的存取方式與查詢作業相同。

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

製作 Flutter 應用程式原型並進行測試

設定用戶端，使用本機模擬器

您可以透過 Data Connect 模擬器，從 Data Connect VS Code 擴充功能或 CLI 進行操作。

無論是哪種情境，將應用程式連線至模擬器的做法都相同。

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

如要切換至正式版資源，請註解連線至模擬器的程式碼行。

Dart SDK 中的資料型別

Data Connect 伺服器代表常見的 GraphQL 資料型別。這些項目在 SDK 中會以以下方式表示。

資料連結類型	Dart
時間戳記	firebase_data_connect.Timestamp
Int (32 位元)	int
日期	DateTime
UUID	字串
Int64	int
浮點值	double
布林值	bool
不限	firebase_data_connect.AnyValue

使用產生的 Flutter SDK 透過集合功能整理內容 你可以依據偏好儲存及分類內容。