از وب SDK های تولید شده استفاده کنید

SDK های مشتری Firebase Data Connect به شما امکان می دهند پرس و جوها و جهش های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. همزمان با طراحی طرحواره ها، پرس و جوها و جهش هایی که در سرویس Data Connect خود مستقر می کنید، یک SDK مشتری سفارشی ایجاد می کنید. سپس، شما متدها را از این SDK در منطق کلاینت خود ادغام می کنید.

همانطور که در جاهای دیگر ذکر کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های Data Connect توسط کد مشتری ارسال نمی‌شوند و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری در سرور ذخیره می شود. این بدان معناست که شما باید تغییرات سمت کلاینت مربوطه را برای جلوگیری از شکستن کاربران موجود (مثلاً در نسخه‌های قدیمی‌تر برنامه) اعمال کنید.

به همین دلیل است که Data Connect یک محیط توسعه‌دهنده و ابزاری را در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌واره‌ها، پرسش‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین در حالی که شما نمونه سازی می کنید، SDK های سمت سرویس گیرنده را به طور خودکار تولید می کند.

هنگامی که به‌روزرسانی‌های سرویس و برنامه‌های سرویس گیرنده خود را تکرار کردید، به‌روزرسانی‌های سمت سرور و سرویس گیرنده آماده اجرا هستند.

گردش کار توسعه مشتری چیست؟

اگر شروع به کار را دنبال کنید، با جریان کلی توسعه برای Data Connect آشنا شده اید. در این راهنما، اطلاعات دقیق تری در مورد تولید SDK های وب از طرحواره خود و کار با پرس و جوها و جهش های مشتری پیدا خواهید کرد.

به طور خلاصه، برای استفاده از وب SDK های تولید شده در برنامه های مشتری خود، این مراحل پیش نیاز را دنبال می کنید:

1. Firebase را به برنامه وب خود اضافه کنید.

سپس:

1. طرح برنامه خود را توسعه دهید.
2. کد مشتری خود را با جاوا اسکریپت SDK یا کتابخانه های React یا Angular راه اندازی کنید.
3. برای React و Angular، بسته های Tanstack Query را نصب کنید

4. تنظیم تولید SDK:

   • با دکمه افزودن SDK به برنامه در افزونه Data Connect VS Code
   • با به روز رسانی connector.yaml خود برای JavaScript SDK یا React یا Angular .

5. کتابخانه ها و کدهای تولید شده را با JavaScript SDK یا React یا Angular وارد کنید.

6. فراخوانی‌ها و جهش‌ها را با JavaScript SDK یا React یا Angular اجرا کنید.

7. با راه‌اندازی شبیه‌ساز Data Connect با JavaScript SDK یا React یا Angular آزمایش کنید.

کد مشتری را با Firebase JavaScript SDK پیاده سازی کنید

این بخش نحوه پیاده سازی کلاینت ها با استفاده از Firebase JavaScript SDK را پوشش می دهد.

اگر از React یا Angular استفاده می‌کنید، دستورالعمل‌های راه‌اندازی جایگزین و پیوندهایی به اسناد اضافی درباره ایجاد Data Connect SDK برای چارچوب‌ها را ببینید.

برنامه خود را راه اندازی کنید

ابتدا، برنامه خود را با استفاده از دنباله استاندارد Firebase مقداردهی کنید.

initializeApp({...});

SDK جاوا اسکریپت تولید شده را نصب کنید

از Firebase CLI برای تنظیم SDK های ایجاد شده Data Connect در برنامه های خود استفاده کنید. دستور init باید تمام برنامه های موجود در پوشه فعلی را شناسایی کرده و SDK های تولید شده را به طور خودکار نصب کند.

firebase init dataconnect:sdk

برنامه خود را به سرویس Data Connect متصل کنید.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

SDK ها را هنگام نمونه سازی به روز کنید

اگر افزونه Data Connect VS Code را نصب کرده باشید، SDK های تولید شده را همیشه به روز نگه می دارد.

اگر از افزونه Data Connect VS Code استفاده نمی کنید، می توانید از Firebase CLI برای به روز نگه داشتن SDK های تولید شده استفاده کنید.

firebase dataconnect:sdk:generate --watch

ایجاد SDK در خطوط لوله ساخت

می‌توانید از Firebase CLI برای تولید Data Connect SDK در فرآیندهای ساخت CI/CD استفاده کنید.

firebase dataconnect:sdk:generate

واردات کتابخانه ها

دو مجموعه واردات برای مقداردهی اولیه کد مشتری شما مورد نیاز است: واردات کلی 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 '@dataconnect/generated';

از جستارهای جاوا اسکریپت SDK استفاده کنید

کد تولید شده از قبل با Query Refs از پیش تعریف شده همراه خواهد بود. تنها کاری که باید انجام دهید این است که آن ها را وارد کرده و اجرا کنید.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

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

فراخوانی روش های پرس و جو SDK

در اینجا یک مثال با استفاده از این توابع میانبر عمل آورده شده است:

import { listMovies } from '@dataconnect/generated';
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`

تغییرات فیلدهای شمارش را مدیریت کنید

طرحواره یک برنامه می‌تواند شامل شمارش‌هایی باشد که می‌توان با جستارهای GraphQL به آنها دسترسی داشت.

همانطور که طراحی برنامه تغییر می کند، می توانید مقادیر جدید پشتیبانی شده enum اضافه کنید. به عنوان مثال، تصور کنید که بعداً در چرخه عمر برنامه خود تصمیم می گیرید یک مقدار FULLSCREEN به enum AspectRatio اضافه کنید.

در گردش کار Data Connect ، می‌توانید از ابزار توسعه محلی برای به‌روزرسانی پرسش‌ها و SDK‌های خود استفاده کنید.

با این حال، قبل از اینکه یک نسخه به‌روز از کلاینت‌های خود را منتشر کنید، ممکن است کلاینت‌های مستقر قدیمی‌تر خراب شوند.

مثال اجرای ارتجاعی

همیشه یک شاخه default به دستور switch روی مقادیر enum اضافه کنید، یا یک شاخه else را به بلوک if/else if با مقادیر enum مقایسه کنید. این توسط زبان جاوا اسکریپت/تایپ اسکریپت اعمال نمی شود، اما راهی برای قوی کردن کد کلاینت در صورت اضافه شدن مقادیر enum جدید است.

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

از جهش‌های JavaScript SDK استفاده کنید

جهش‌ها مانند پرس و جوها قابل دسترسی هستند.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

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

به شبیه ساز Data Connect متصل شوید

به صورت اختیاری، می توانید با فراخوانی connectDataConnectEmulator و سپس عبور دادن در نمونه Data Connect به شبیه ساز متصل شوید، مانند:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

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

// Make calls from your app

برای تغییر به منابع تولید، خطوطی را برای اتصال به شبیه ساز بیان کنید.

کد مشتری را برای React و Angular پیاده سازی کنید

Firebase Data Connect با استفاده از کتابخانه‌های موجود در شرکای ما در Invertase، TanStack Query Firebase ، یک SDK تولید شده با قلاب‌هایی برای React و Angular ارائه می‌کند.

این کتابخانه مجموعه‌ای از قلاب‌ها را فراهم می‌کند که مدیریت وظایف ناهمزمان با 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

ng add @angular/fire

React یا Angular SDK خود را ایجاد کنید

همانند وب SDK استاندارد، همانطور که قبلا توضیح داده شد، ابزار Firebase تولید خودکار SDK ها را بر اساس طرح و عملیات شما انجام می دهد.

اگر به تازگی React یا Angular را به پروژه خود اضافه کرده اید، firebase init dataconnect:sdk را مجدداً اجرا کنید تا SDK های تولید شده را مجدداً پیکربندی کنید تا پیوندهای فریمورک اضافی را نیز در بر گیرد.

واردات کتابخانه ها

چهار مجموعه واردات برای مقداردهی اولیه کد کلاینت 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 '@dataconnect/generated';

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

// 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 '@dataconnect/generated';

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

از کوئری ها و جهش ها در کلاینت React یا Angular خود استفاده کنید

با تکمیل راه‌اندازی، می‌توانید روش‌هایی را از SDK تولید شده ترکیب کنید.

در قطعه زیر به روش use -prefixed useListAllMovies برای React و inject -prefixed متد injectListAllMovies برای Angular توجه کنید، هر دو از SDK تولید شده.

import { useListAllMovies } from '@dataconnect/generated/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>
}

import { injectAllMovies, connectorConfig } from '@dataconnect/generated/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 });
  }
}

// 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 به قلاب تولید شده خود منتقل کنید، مانند:

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

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

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

// 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;
}),

برای تغییر به منابع تولید، خطوطی را برای اتصال به شبیه ساز بیان کنید.

انواع داده در SDK

سرور Data Connect نشان دهنده انواع داده های رایج GraphQL است. این موارد در SDK به شرح زیر نشان داده شده است.

SDK ها را هنگام نمونه سازی به روز کنید

اگر افزونه Data Connect VS Code را نصب کرده باشید، SDK های تولید شده را همیشه به روز نگه می دارد.

اگر از افزونه Data Connect VS Code استفاده نمی کنید، می توانید از Firebase CLI برای به روز نگه داشتن SDK های تولید شده استفاده کنید.

firebase dataconnect:sdk:generate --watch

ایجاد SDK در خطوط لوله ساخت

می‌توانید از Firebase CLI برای تولید Data Connect SDK در فرآیندهای ساخت CI/CD استفاده کنید.

firebase dataconnect:sdk:generate