استخدام حِزم تطوير البرامج (SDK) على الويب التي تم إنشاؤها

تتيح لك حِزم تطوير البرامج (SDK) للعميل Firebase Data Connect إرسال طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. ويمكنك إنشاء حِزمة تطوير برامج (SDK) مخصّصة للعميل بالتزامن مع تصميم المخططات وطلبات البحث والتعديلات التي تنشرها في خدمة Data Connect. بعد ذلك، يمكنك دمج طرق من حزمة SDK هذه في منطق برنامجك.

كما ذكرنا في موضع آخر، من المهم الإشارة إلى أنّ Data Connect طلبات البحث وعمليات التعديل لا يتم إرسالها من خلال رمز العميل وتنفيذها على الخادم. في المقابل، عند نشر عمليات Data Connect، يتم تخزينها على الخادم، مثل "وظائف السحابة الإلكترونية". وهذا يعني أنّه عليك نشر تغييرات مقابلة من جهة العميل لتجنُّب إيقاف التطبيق لدى المستخدمين الحاليين (على سبيل المثال، في إصدارات التطبيق القديمة).

لهذا السبب، يوفّر لك Data Connect بيئة تطوير وأدوات تتيح لك إنشاء نماذج أولية للمخططات والطلبات وعمليات التعديل التي يتم نشرها على الخادم. تنشئ أيضًا حِزم تطوير البرامج (SDK) من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.

بعد تكرار التحديثات على خدمتك وتطبيقات العميل، يصبح كلا التحديثَين على جهة الخادم والعميل جاهزًا للنشر.

ما هي خطوات تطوير العملاء؟

إذا اتّبعت الخطوات الواردة في البدء، تعرّفت على سير عملية التطوير بشكل عام في Data Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً حول إنشاء حِزم تطوير البرامج (SDK) للويب من المخطط الخاص بك والتعامل مع طلبات البحث والتعديلات من جهة العميل.

باختصار، لاستخدام حِزم تطوير البرامج (SDK) التي تم إنشاؤها للويب في تطبيقات العميل، عليك اتّباع خطوات المتطلبات الأساسية التالية:

  1. أضِف Firebase إلى تطبيقك على الويب.

بعد ذلك:

  1. طوِّر مخطط تطبيقك.
  2. ابدأ إعداد رمز العميل باستخدام JavaScript SDK أو مكتبات React أو Angular.
  3. بالنسبة إلى React وAngular، ثبِّت حِزم Tanstack Query

  4. إعداد إنشاء حزمة تطوير البرامج (SDK):

  5. استيراد المكتبات والرموز البرمجية التي تم إنشاؤها باستخدام JavaScript SDK أو React أو Angular

  6. تنفيذ طلبات البحث والتعديلات باستخدام JavaScript SDK أو React أو Angular

  7. اختبِر ذلك من خلال إعداد محاكي Data Connect باستخدام حزمة تطوير البرامج (SDK) المستندة إلى JavaScript أو React أو Angular.

تنفيذ رمز العميل باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript

يتناول هذا القسم كيفية تنفيذ العملاء باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript.

إذا كنت تستخدم React أو Angular، اطّلِع على تعليمات الإعداد البديلة والروابط المؤدية إلى مستندات إضافية حول إنشاء حِزم تطوير البرامج (SDK) Data Connectللأُطر.

تهيئة تطبيقك

أولاً، عليك إعداد تطبيقك باستخدام تسلسل Firebase العادي.

initializeApp({...});

تثبيت حزمة JavaScript SDK التي تم إنشاؤها

استخدِم واجهة سطر الأوامر Firebase لإعداد حِزم تطوير البرامج (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، يمكنك استخدام واجهة سطر الأوامر (CLI) في Firebase لإبقاء حِزم SDK التي تم إنشاؤها محدّثة.

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK في مسارات إنشاء البرامج

يمكنك استخدام واجهة سطر الأوامر (CLI) في Firebase لإنشاء حِزم تطوير البرامج (SDK) الخاصة بـ Data Connect في عمليات إنشاء التكامل المستمر/التسليم المستمر.

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) المستندة إلى JavaScript

سيتضمّن الرمز الذي تم إنشاؤه مراجع طلبات بحث محدّدة مسبقًا. كل ما عليك فعله هو استيرادها واستدعاء execute عليها.

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.

عندما يتغيّر تصميم التطبيق، يمكنك إضافة قيم جديدة متوافقة مع التعداد. على سبيل المثال، لنفترض أنّك قرّرت في وقت لاحق من دورة حياة تطبيقك إضافة القيمة FULLSCREEN إلى تعداد AspectRatio.

في سير عمل Data Connect، يمكنك استخدام أدوات التطوير المحلية لتعديل الاستعلامات وحِزم SDK.

ومع ذلك، قبل طرح إصدار محدَّث من برامجك، قد تتعطّل البرامج القديمة التي تم نشرها.

مثال على عملية تنفيذ مرنة

أضِف دائمًا فرع default إلى عبارة switch بشأن قيم التعداد، أو فرع else إلى كتلة if/else if تقارن قيم التعداد. لا تفرض لغة JavaScript/TypeScript ذلك، ولكنّها الطريقة التي يمكن من خلالها جعل رمز العميل قويًا في حال تمت إضافة قيم جديدة إلى التعداد.

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) في JavaScript

يمكن الوصول إلى عمليات التغيير بالطريقة نفسها التي يتم بها الوصول إلى طلبات البحث.

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 حزمة تطوير برامج (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

Angular

ng add @angular/fire

إنشاء حزمة تطوير البرامج (SDK) الخاصة بتطبيق React أو Angular

كما هو الحال مع حزمة تطوير البرامج (SDK) العادية على الويب، كما هو موضّح سابقًا، تتعامل أدوات Firebase مع الإنشاء التلقائي لحِزم تطوير البرامج (SDK) استنادًا إلى المخطط والعمليات.

إذا أضفت React أو Angular إلى مشروعك للتو، أعِد تشغيل firebase init dataconnect:sdk لإعادة ضبط حِزم SDK التي تم إنشاؤها لتضمين روابط إضافية للإطار.

استيراد المكتبات

هناك أربع مجموعات من عمليات الاستيراد مطلوبة لإعداد رمز العميل 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 '@dataconnect/generated';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/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 '@dataconnect/generated';

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

استخدام طلبات البحث وعمليات التعديل في عميل React أو Angular

بعد اكتمال عملية الإعداد، يمكنك دمج طرق من حزمة SDK التي تم إنشاؤها.

في المقتطف التالي، لاحظ الطريقة التي تبدأ بـ use useListAllMovies في React والطريقة التي تبدأ بـ inject injectListAllMovies في Angular، وكلتاهما من حزمة تطوير البرامج (SDK) التي تم إنشاؤها.

تفاعُل

تستدعي جميع هذه العمليات في حزمة SDK التي تم إنشاؤها، سواء كانت طلبات بحث أو عمليات تغيير، روابط TanStackQuery:

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>
}

Angular

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

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 إلى الخطاف الذي تم إنشاؤه، كما يلي:

تفاعُل 

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);
  ...
}

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

للتبديل إلى موارد الإنتاج، علِّق على الأسطر الخاصة بالاتصال بالمحاكي.

أنواع البيانات في حزمة SDK

يمثّل خادم Data Connect أنواع بيانات GraphQL الشائعة. يتم تمثيل هذه القيم في حزمة SDK على النحو التالي.

نوع Data Connect TypeScript
الطابع الزمني سلسلة
تاريخ سلسلة
معرِّف فريد عالمي (UUID) سلسلة
Int64 سلسلة
مزدوج الرقم
عائم الرقم

تحديث حِزم SDK أثناء إنشاء النماذج الأولية

إذا كانت إضافة Data Connect VS Code مثبَّتة، ستحرص دائمًا على أن تكون حِزم SDK التي تم إنشاؤها حديثة.

إذا كنت لا تستخدم إضافة Data Connect في VS Code، يمكنك استخدام واجهة سطر الأوامر (CLI) في Firebase لإبقاء حِزم SDK التي تم إنشاؤها محدّثة.

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK في مسارات إنشاء البرامج

يمكنك استخدام واجهة سطر الأوامر (CLI) في Firebase لإنشاء حِزم تطوير البرامج (SDK) الخاصة بـ Data Connect في عمليات إنشاء التكامل المستمر/التسليم المستمر.

firebase dataconnect:sdk:generate