تتيح لك حِزم تطوير البرامج (SDK) لعملاء Firebase Data Connect طلب طلبات البحث وعمليات التحويل من جهة الخادم مباشرةً من تطبيق Firebase. يمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة للعملاء في وقتٍ موازي أثناء تصميم المخططات وطلبات البحث وعمليات التحويل التي يتم نشرها في خدمة Data Connect. بعد ذلك، يمكنك دمج طرق من حزمة SDK هذه في منطق العميل.
كما ذكرنا في مكان آخر، من المهم الإشارة إلى أنّ Data Connect طلبات البحث والطفرات لا يتم إرسالها من خلال رمز العميل ويتم تنفيذها على الخادم. بدلاً من ذلك، عند نشرها، يتم تخزين عمليات Data Connect على الخادم مثل "وظائف السحابة الإلكترونية". وهذا يعني أنّك بحاجة إلى نشر التغييرات المقابلة من جهة العميل لتجنّب إيقاف المستخدمين الحاليين (على سبيل المثال، في الإصدارات القديمة من التطبيق).
لهذا السبب، يوفّر لك Data Connect بيئة مطوّرين وأدوات تسمح لك بإنشاء نماذج أولية للمخططات وطلبات البحث والتغييرات التي يتم نشرها على الخادم. وتنشئ هذه الأداة أيضًا حِزم تطوير البرامج (SDK) من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.
بعد تكرار التحديثات على تطبيقَي الخدمة والعملاء، تصبح التحديثات من جهة الخادم وجانب العميل جاهزة للنشر.
ما هو سير عمل تطوير العملاء؟
إذا اتّبعت خطوات البدء، تم إعلامك بمسار التطوير العام لتطبيق Data Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً حول إنشاء حِزم تطوير برامج (SDK) للويب من مخطّطك والعمل مع طلبات بحث العميل وعمليات التحويل.
باختصار، لاستخدام حِزم تطوير البرامج (SDK) لتطبيقات الويب التي تم إنشاؤها في تطبيقات العملاء، عليك اتّباع الخطوات الأساسية التالية:
- أضِف Firebase إلى تطبيق الويب.
بعد ذلك:
- أنشئ مخطّط تطبيقك.
- ابدأ إعداد رمز العميل باستخدام حزمة تطوير برامج JavaScript (SDK) أو مكتبتَي React أو Angular.
- بالنسبة إلى React وAngular، عليك تثبيت حِزم Tanstack Query.
إعداد عملية إنشاء حزمة SDK:
- باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافات Data Connect لبرنامج VS Code
- من خلال تحديث
connector.yamlلاستخدام حزمة تطوير البرامج (SDK) لـ JavaScript أو React أو Angular
استيراد المكتبات والرمز الذي تم إنشاؤه باستخدام حزمة تطوير برامج JavaScript (SDK) أو React أو Angular
نفِّذ طلبات لإجراء طلبات بحث وتعديلات باستخدام حزمة تطوير البرامج (SDK) لـ JavaScript، أو React أو Angular.
اختبِر الميزة من خلال إعداد محاكي Data Connect باستخدام حزمة تطوير البرامج (SDK) لـ JavaScript أو React أو Angular.
تنفيذ رمز العميل باستخدام حزمة تطوير البرامج (SDK) Firebase JavaScript
يتناول هذا القسم كيفية تنفيذ العملاء باستخدام حزمة تطوير البرامج (SDK) Firebase JavaScript.
إذا كنت تستخدِم React أو Angular، اطّلِع على تعليمات إعداد بديلة وروابط تؤدي إلى مستندات إضافية حول إنشاء حِزم تطوير البرامج (SDK) Data Connect للإطارات الأساسية.
بدء تطبيقك
أولاً، عليك إعداد تطبيقك باستخدام تسلسل Firebase العادي.
initializeApp({...});
إنشاء حزمة تطوير البرامج (SDK) لتطبيقك باستخدام JavaScript
كما هو الحال مع معظم مشاريع Firebase، يتم تنفيذ العمل على Firebase Data Connect العميل الرمز في دليل مشروع على الجهاز. إنّ كلًّا من Firebase CLI وإضافة Data Connect VS Code مهمّان على مستوى الأدوات المحلية لإنشاء رمز العميل وإدارته.
ترتبط خيارات إنشاء حزمة 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@latest لضمان تلبية هذا الاعتماد على التطبيقات المشابهة.
إعداد حزمة تطوير البرامج (SDK) لـ JavaScript
ابدأ تشغيل مثيل Data Connect باستخدام المعلومات التي استخدَمتها لإعداد Data Connect (كلّها متوفّرة في Firebase console علامة التبويب Data Connect).
عنصر ConnectorConfig
تتطلّب حزمة تطوير البرامج (SDK) كائن إعدادات الموصّل.
يتم إنشاء هذا العنصر تلقائيًا من serviceId وlocation في
dataconnect.yaml وconnectorId في connector.yaml.
استيراد المكتبات
هناك مجموعتان من عمليات الاستيراد اللازمة لإعداد رمز العميل: عمليات استيراد 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
سيتضمّن الرمز الذي تم إنشاؤه مراجع طلبات بحث محدّدة مسبقًا. ما عليك سوى استيرادها واستدعاء execute عليها.
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
للتبديل إلى موارد الإنتاج، عليك تعليق الأسطر المتعلّقة بالاتصال بالemualtor.
تنفيذ رمز العميل لكل من React وAngular
Firebase Data Connect يوفّر حزمة تطوير برامج (SDK) تم إنشاؤها باستخدام أدوات ربط لـ React و Angular باستخدام المكتبات المتاحة من شركائنا في Invertase، TanStack Query Firebase.
توفّر هذه المكتبة مجموعة من أدوات الربط التي تسهّل بشكل كبير التعامل مع المهام غير المتزامنة باستخدام 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 SDK لمشروعك، أضِف مفتاح react إلى ملف الإعدادات
connector.yaml.
generate:
javascriptSdk:
react: true
outputDir: "../movies-generated"
package: "@movie-app/movies"
packageJsonDir: "../../"
generate:
javascriptSdk:
angular: true
outputDir: "../movies-generated"
package: "@movie-app/movies"
packageJsonDir: "../../"
استيراد المكتبات
هناك أربع مجموعات من عمليات الاستيراد اللازمة لإعداد رمز العميل في React أو Angular: عمليات استيراد Data Connect العامة وعمليات استيراد TanStack العامة وعمليات الاستيراد المحدّدة لحِزم SDK التي تم إنشاؤها باستخدام JavaScript و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 '@myorg/myconnector';
// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/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 '@myorg/myconnector';
// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@myorg/connector/angular";
استخدام طلبات البحث والطفرات في برنامج React أو Angular client
بعد اكتمال عملية الإعداد، يمكنك دمج طرق من حزمة SDK التي تم إنشاؤها.
في المقتطف التالي، لاحِظ الطريقة التي تبدأ بالبادئة useuseListAllMovies لأجل React والطريقة التي تبدأ بالبادئة injectinjectListAllMovies لأجل Angular، وكلاهما من حزمة SDK التي تم إنشاؤها.
تُطلِق كل هذه العمليات في حزمة تطوير البرامج (SDK) التي تم إنشاؤها، سواء كانت طلبات بحث أو عمليات تعديل، عمليات ربط TanStackQuery:
- تستدعي طلبات البحثعلامة TanStack
useDataConnectQueryوتُرجعها. - تستدعي عمليات التحويل خطاف TanStack
useDataConnectMutationوتُرجعه.
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>
}
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 });
}
}
// 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 '@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);
...
}
// 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;
}),
للتبديل إلى موارد الإنتاج، عليك تعليق الأسطر المتعلّقة بالاتصال بالemualtor.
أنواع البيانات في حزمة SDK
يمثّل خادم Data Connect أنواع بيانات GraphQL الشائعة. يتم تمثيل هذه العناصر في حزمة SDK على النحو التالي.
| نوع ربط البيانات | TypeScript |
|---|---|
| الطابع الزمني | سلسلة |
| التاريخ | سلسلة |
| معرِّف فريد عالمي (UUID) | سلسلة |
| Int64 | سلسلة |
| مزدوج | الرقم |
| عائم | الرقم |
اعتبارات خاصة لإنشاء حِزم SDK
ضبط المسارات بالنسبة إلى node_modules
بالنسبة إلى حزمة تطوير البرامج (SDK) لـ JavaScript، بما أنّ Data Connect يستخدم npm link ل
تثبيت حزمة SDK، يجب إخراج حزمة SDK التي تم إنشاؤها في دليل على
المستوى نفسه لمسار node_modules أو في دليل فرعي يمكنه
الوصول إلى node_modules.
بعبارة أخرى، يجب أن تتمكن حزمة SDK التي تم إنشاؤها من الوصول إلى firebase
وحدة node لكي تعمل بشكل صحيح.
على سبيل المثال، إذا كان لديك 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، يتم تلقائيًا
إنشاء ملفات مصدر حزمة تطوير البرامج (SDK) وتعديلها أثناء تعديل ملفات .gql التي تحدّد المخططات وطلبات البحث
والعمليات. يمكن أن تكون هذه ميزة مفيدة في سير عمل (إعادة) التحميل السريع.
.gql وتعديل مصادر SDK
تلقائيًا.
بدلاً من ذلك، يمكنك استخدام سطر الأوامر لإعادة إنشاء حِزم تطوير البرامج (SDK) عند تغيير ملفات .gql:
firebase dataconnect:sdk:generate --watchإنشاء حِزم SDK للدمج والإصدارات العلنية
في بعض السيناريوهات، مثل إعداد مصادر المشاريع لإرسالها إلى اختبارات التكامل المستمر، يمكنك استدعاء Firebase CLI لإجراء تحديث مجمّع.
في هذه الحالات، استخدِم firebase dataconnect:sdk:generate.