استخدام حِزم تطوير البرامج (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):

   • باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافة Data Connect VS Code
   • من خلال تعديل connector.yaml لحزمة تطوير البرامج (SDK) المستندة إلى JavaScript أو React أو Angular

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

إنشاء حزمة تطوير البرامج (SDK) بلغة JavaScript

كما هو الحال مع معظم مشاريع Firebase، يتم العمل على رمز Firebase Data Connectالعميل في دليل مشروع محلي. يُعدّ كل من إضافة Data Connect في Visual Studio Code وواجهة سطر الأوامر Firebase أداتَين محليتَين مهمتَين لإنشاء رمز العميل وإدارته.

يتم ربط خيارات إنشاء حزمة SDK بعدة إدخالات في ملف dataconnect.yaml الذي تم إنشاؤه عند إعداد مشروعك.

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

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

تحدِّد outputDir المكان الذي يجب أن يتم فيه إخراج حزمة SDK التي تم إنشاؤها.

يمثّل package اسم الحزمة.

تحدّد packageJsonDir مكان تثبيت الحزمة.

في هذه الحالة، يجب تثبيت firebase@latest لضمان استيفاء هذه التبعية.

إعداد JavaScript SDK

ابدأ مثيل Data Connect باستخدام المعلومات التي استخدمتها لإعداد Data Connect (تتوفّر جميعها في علامة التبويب Data Connect في وحدة تحكّم Firebase).

عنصر 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';

استخدام طلبات البحث من حزمة تطوير البرامج (SDK) المستندة إلى JavaScript

سيتضمّن الرمز الذي تم إنشاؤه مراجع طلبات بحث محدّدة مسبقًا. كل ما عليك فعله هو استيرادها واستدعاء 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`

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

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

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

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

تنفيذ رمز العميل لكل من 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

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

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

لإنشاء حزمة تطوير برامج (SDK) لتطبيق React لمشروعك، أضِف مفتاح 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

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

في المقتطف التالي، لاحظ الطريقة التي تبدأ بـ useuseListAllMovies في React والطريقة التي تبدأ بـ injectinjectListAllMovies في Angular، وكلتاهما من حزمة SDK التي تم إنشاؤها.

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

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

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

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

اعتبارات خاصة بشأن إنشاء حزمة تطوير البرامج (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 التي تحدّد المخططات والاستعلامات والتعديلات. يمكن أن تكون هذه الميزة مفيدة في سير عمل إعادة التحميل السريع.

بدلاً من ذلك، يمكنك استخدام واجهة سطر الأوامر لإعادة إنشاء حِزم تطوير البرامج (SDK) كلما تم تغيير ملفات ‎ .gql:

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK لعملية الدمج وإصدارات الإنتاج

في بعض السيناريوهات، مثل إعداد مصادر المشاريع لإرسالها إلى اختبارات CI، يمكنك استدعاء واجهة سطر الأوامر Firebase لإجراء تعديل مجمّع.

في هذه الحالات، استخدِم firebase dataconnect:sdk:generate.