使用產生的 Web SDK

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

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

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

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

什麼是用戶端開發工作流程？

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

您可以透過快速入門應用程式存放區學習用戶端開發，並按照網頁程式碼研究室的說明，建構功能齊全的 Data Connect 應用程式。

總而言之，如要在用戶端應用程式中使用產生的 Web SDK，請按照下列必要步驟操作：

1. 將 Firebase 新增至網頁應用程式。

接著：

1. 開發應用程式結構定義。
2. 使用 JavaScript SDK、React 或 Angular 程式庫初始化用戶端程式碼。
3. 如果是 React 和 Angular，請安裝 Tanstack Query 套件。

4. 設定 SDK 產生作業：

   • 使用 Data Connect VS Code 擴充功能的「Add SDK to app」(將 SDK 新增至應用程式) 按鈕
   • 更新 JavaScript SDK 的 connector.yaml，或是 React 或 Angular。

5. 使用 JavaScript SDK 匯入程式庫和產生的程式碼，或使用 React 或 Angular。

6. 使用 JavaScript SDK、React 或 Angular 實作查詢和變動的呼叫。

7. 使用 JavaScript SDK、React 或 Angular 設定 Data Connect 模擬器，進行測試。

使用 Firebase JavaScript SDK 實作用戶端程式碼

本節說明如何使用 Firebase JavaScript SDK 實作用戶端。

如果您使用 React 或 Angular，請參閱替代設定操作說明，以及為架構產生 Data Connect SDK 的其他說明文件連結。

初始化應用程式

首先，請使用標準 Firebase 序列初始化應用程式。

initializeApp({...});

產生 JavaScript SDK

與大多數 Firebase 專案一樣，您會在專案的本機目錄中處理Firebase Data Connect用戶端程式碼。Data Connect VS Code 擴充功能和 Firebase CLI 都是重要的本機工具，可產生及管理用戶端程式碼。

SDK 生成選項會對應到您初始化專案時生成的 dataconnect.yaml 檔案中的多個項目。

初始化 SDK 生成作業

在 connector.yaml 中，加入 outputDir、package 和 (適用於網頁 SDK) packageJsonDir。

generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir 指定產生的 SDK 輸出位置。

package 指定套件名稱。

packageJsonDir 指定套件的安裝位置。

注意： 我們會將 "firebase": "^10.14.0" 新增為 peerDependency，以利生成。 視依附元件管理工具 (即 pnpm) 而定，這些依附元件可能不會自動安裝。

在此情況下，請安裝 firebase@latest，確保滿足這個對等依附元件。

初始化 JavaScript SDK

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

ConnectorConfig 物件

SDK 需要連接器設定物件。

這個物件會從 dataconnect.yaml 中的 serviceId 和 location，以及 connector.yaml 中的 connectorId 自動產生。

匯入程式庫

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

請注意一般匯入作業中包含的 ConnectorConfig 物件。

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@myorg/myconnector';

使用 JavaScript SDK 的查詢

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

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

呼叫 SDK 查詢方法

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

import { listMovies } from '@movie-app/movies';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

訂閱變更

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

const listRef = listAllMoviesRef();

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

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

使用 JavaScript SDK 中的突變

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

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

連線至 Data Connect 模擬器

您也可以選擇呼叫 connectDataConnectEmulator，然後傳入 Data Connect 例項，連線至模擬器，如下所示：

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

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

注意： 只有在想連線至 Data Connect 模擬器時，才需要呼叫 getDataConnect。否則，產生的 SDK 會自動為您建立 DataConnect 物件的例項。

導入 React 和 Angular 的用戶端程式碼

Firebase Data Connect 會產生 SDK，並使用合作夥伴 Invertase 提供的程式庫，為 React 和 Angular 提供 Hook，TanStack Query Firebase。

這個程式庫提供一系列 Hook，可大幅簡化應用程式中 Firebase 的非同步工作處理程序。

初始化應用程式

首先，如同任何 Firebase 網頁應用程式，請使用標準 Firebase 序列初始化應用程式。

initializeApp({...});

安裝 TanStack Query Firebase 套件

在專案中安裝 TanStack Query 的套件。

回應

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

Angular

ng add @angular/fire

產生 React 或 Angular SDK

如先前所述，與標準網頁 SDK 相同，Firebase 工具會根據您的結構定義和作業，自動產生 SDK。

如要為專案產生 React SDK，請在 connector.yaml 設定檔中新增 react 金鑰。

回應

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

Angular

generate:
  javascriptSdk:
    angular: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

匯入程式庫

如要初始化 React 或 Angular 用戶端程式碼，需要四組匯入項目：一般 Data Connect 匯入項目、一般 TanStack 匯入項目，以及為 JS 和 React 產生的 SDK 匯入的特定項目。

請注意一般匯入作業中包含的 ConnectorConfig 型別。

回應

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/react";

Angular

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@myorg/myconnector';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@myorg/connector/angular";

在 React 或 Angular 用戶端中使用查詢和變異

設定完成後，您就可以納入所產生 SDK 的方法。

在下列程式碼片段中，請注意 React 的 use 前置方法 useListAllMovies，以及 Angular 的 inject 前置方法 injectListAllMovies，兩者都來自產生的 SDK。

回應

在產生的 SDK 中，所有這類作業 (包括查詢和突變) 都會呼叫 TanStackQuery 繫結：

• 查詢並傳回 TanStack useDataConnectQuery hook
• 異動會呼叫並傳回 TanStack useDataConnectMutation Hook

import { useListAllMovies } from '@movies-app/movies/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

Angular

注意： ng add @angular/fire 會自動為您執行這項操作，但如果您選擇手動設定，可以使用下列程式碼：

import { injectAllMovies, connectorConfig } from '@movies-app/movies/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

使用 React 和 Angular 自動重新載入查詢

您可以設定查詢，在資料變更時自動重新載入。

回應

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause Tanstack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

Angular

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

連線至 Data Connect 模擬器

您也可以呼叫 connectDataConnectEmulator 連線至模擬器，然後將 Data Connect 例項傳遞至產生的 Hook，如下所示：

React

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@movies-app/movies';
import { useListAllMovies } from '@movies-app/movies/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

Angular

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

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

注意： 只有在想連線至 Data Connect 模擬器時，才需要呼叫 getDataConnect。否則，產生的 SDK 會自動為您建立 DataConnect 物件的例項。

SDK 中的資料類型

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

資料連結類型	TypeScript
時間戳記	字串
日期	字串
UUID	字串
Int64	字串
雙人床	數字
浮點值	數字

產生 SDK 的特別注意事項

設定相對於 node_modules 的路徑

如果是 JavaScript SDK，由於 Data Connect 會使用 npm link 安裝 SDK，因此產生的 SDK 必須輸出至與 node_modules 路徑同層級的目錄，或可存取 node_modules 的子目錄。

換句話說，產生的 SDK 必須有權存取 firebase 節點模組，才能正常運作。

舉例來說，如果 node_modules 位於 my-app/ 中，輸出目錄應為 my-app/js-email-generated，這樣 js-email-generated 才能從父項 node_modules 資料夾匯入。

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

或者，如果您有單一存放區，且模組位於根目錄，則可將輸出目錄放在單一存放區的任何資料夾中。

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

注意： 如果專案是在個別目錄結構中設定，您可以提供目錄的絕對路徑。

在原型設計期間更新 SDK

如果您使用 Data Connect VS Code 擴充功能及其 Data Connect 模擬器，以互動方式製作原型，系統會在您修改定義結構定義、查詢和變異的 .gql 檔案時，自動產生及更新 SDK 來源檔案。在熱重載工作流程中，這項功能相當實用。

在其他情況下，如果您使用 Firebase CLI 的 Data Connect 模擬器，可以監控 .gql 更新，並自動更新 SDK 來源。

或者，您也可以在 .gql 檔案變更時，使用 CLI 重新產生 SDK：

firebase dataconnect:sdk:generate --watch

產生 SDK，用於整合及發布正式版

在某些情況下 (例如準備專案來源以提交 CI 測試時)，您可以呼叫 Firebase CLI 進行批次更新。

在這些情況下，請使用 firebase dataconnect:sdk:generate。