کیت‌های توسعه نرم‌افزار (SDK) کلاینت Firebase Data Connect به شما امکان می‌دهند کوئری‌ها و جهش‌های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. شما همزمان با طراحی طرحواره‌ها، کوئری‌ها و جهش‌هایی که در سرویس Data Connect خود پیاده‌سازی می‌کنید، یک SDK کلاینت سفارشی ایجاد می‌کنید. سپس، متدهای این SDK را در منطق کلاینت خود ادغام می‌کنید.
همانطور که در جای دیگری اشاره کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های Data Connect توسط کد کلاینت ارسال و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری روی سرور ذخیره می‌شوند. این بدان معناست که برای جلوگیری از اختلال در عملکرد کاربران موجود (به عنوان مثال، در نسخه‌های قدیمی‌تر برنامه)، باید تغییرات مربوطه در سمت کلاینت را اعمال کنید.
به همین دلیل است که Data Connect یک محیط توسعه‌دهنده و ابزار در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌ها، کوئری‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین، همزمان با نمونه‌سازی شما، SDKهای سمت کلاینت را به طور خودکار تولید می‌کند.
وقتی به‌روزرسانی‌های مکرر را برای سرویس و برنامه‌های کلاینت خود انجام دادید، به‌روزرسانی‌های سمت سرور و کلاینت آماده‌ی استقرار هستند.
گردش کار توسعه کلاینت چیست؟
اگر بخش « شروع به کار» را دنبال کرده باشید، با جریان کلی توسعه برای Data Connect آشنا شده‌اید. در این راهنما، اطلاعات دقیق‌تری در مورد تولید Web SDKها از طرحواره خود و کار با کوئری‌ها و جهش‌های کلاینت پیدا خواهید کرد.
به طور خلاصه، برای استفاده از Web SDK های تولید شده در برنامه‌های کلاینت خود، این مراحل پیش‌نیاز را دنبال خواهید کرد:
- فایربیس را به برنامه وب خود اضافه کنید.
سپس:
- طرحواره برنامه خود را توسعه دهید.
- کد کلاینت خود را با SDK جاوا اسکریپت یا کتابخانه‌های React یا Angular مقداردهی اولیه کنید.
- برای React و Angular، بسته‌های Tanstack Query را نصب کنید.
تنظیم تولید SDK:
- با دکمه‌ی «افزودن SDK به برنامه» در افزونه‌ی Data Connect VS Code ما
- با به‌روزرسانی
connector.yamlخود برای SDK جاوا اسکریپت ، یا React یا Angular .
کتابخانه‌ها و کد تولید شده را با جاوا اسکریپت SDK ، یا React یا Angular وارد کنید.
فراخوانی‌های کوئری‌ها و جهش‌ها را با SDK جاوااسکریپت ، یا React یا Angular پیاده‌سازی کنید.
با تنظیم شبیه‌ساز Data Connect با SDK جاوا اسکریپت ، یا React یا Angular ، آن را آزمایش کنید.
پیاده‌سازی کد کلاینت با Firebase JavaScript SDK
این بخش نحوه پیاده‌سازی کلاینت‌ها با استفاده از Firebase JavaScript SDK را پوشش می‌دهد.
اگر از React یا Angular استفاده می‌کنید، به دستورالعمل‌های تنظیم جایگزین و پیوندهایی به مستندات اضافی در مورد تولید SDK های Data Connect برای چارچوب‌ها مراجعه کنید.
برنامه خود را مقداردهی اولیه کنید
ابتدا، برنامه خود را با استفاده از توالی استاندارد 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 برای تولید SDK های Data Connect در فرآیندهای ساخت 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 Ref های از پیش تعریف شده ارائه می‌شود. تنها کاری که باید انجام دهید این است که آنها را وارد کرده و فراخوانی کنید تا اجرا شوند.
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!");
}
از جهش‌های موجود در 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 در فایربیس
بسته‌های 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
کیت توسعه نرم‌افزار (SDK) ری‌اکت یا انگولار خود را ایجاد کنید
همانند SDK استاندارد وب، همانطور که قبلاً توضیح داده شد، ابزار Firebase تولید خودکار SDKها را بر اساس طرحواره و عملیات شما مدیریت می‌کند.
اگر به تازگی React یا Angular را به پروژه خود اضافه کرده‌اید، firebase init dataconnect:sdk دوباره اجرا کنید تا SDK های تولید شده را مجدداً پیکربندی کنید تا شامل اتصالات اضافی فریم ورک شوند.
کتابخانه‌ها را وارد کنید
برای مقداردهی اولیه کد کلاینت React یا Angular شما، چهار مجموعه import مورد نیاز است: importهای عمومی Data Connect ، importهای عمومی TanStack و importهای خاص برای JS و SDKهای تولید شده توسط React.
به نوع 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 تولید شده هستند، توجه کنید.
واکنش نشان دهید
تمام این عملیات در SDK تولید شده، چه کوئری‌ها و چه جهش‌ها، اتصالات TanStackQuery را فراخوانی می‌کنند:
- کوئری‌ها، هوک
useDataConnectQueryاز TanStack را فراخوانی کرده و برمی‌گردانند. - جهش‌ها قلاب
useDataConnectMutationمربوط به TanStack را فراخوانی کرده و برمی‌گردانند.
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 به شرح زیر نمایش داده شده‌اند.
| نوع اتصال داده | تایپ اسکریپت |
|---|---|
| مهر زمانی | رشته |
| تاریخ | رشته |
| شناسه کاربری | رشته |
| بین‌رشته‌ای64 | رشته |
| دو برابر | شماره |
| شناور | شماره |
به‌روزرسانی SDKها هنگام نمونه‌سازی اولیه
اگر افزونه‌ی Data Connect VS Code را نصب کرده باشید، این افزونه همیشه SDKهای تولید شده را به‌روز نگه می‌دارد.
اگر از افزونه Data Connect VS Code استفاده نمی‌کنید، می‌توانید از Firebase CLI برای به‌روز نگه داشتن SDKهای تولید شده استفاده کنید.
firebase dataconnect:sdk:generate --watchتولید SDK در خطوط لوله ساخت
شما می‌توانید از Firebase CLI برای تولید SDK های Data Connect در فرآیندهای ساخت CI/CD استفاده کنید.
firebase dataconnect:sdk:generate