بدء استخدام Firebase Data Connect باستخدام React

في هذا التشغيل السريع، ستنشئ قاعدة بيانات صغيرة نموذجية وتنشرها وتصل إليها من واجهة مستخدم أمامية في React.

المتطلبات الأساسية

لإكمال هذا التشغيل السريع، ستحتاج إلى ما يلي:

  • بيئة Node.js مع NPM
  • حساب Google

برنامج تعليمي

برنامج تعليمي

1. إعداد مشروعك

أنشئ دليلًا جديدًا وأعِدّ مشروع Firebase فيه. عند المطالبة، حدِّد الخيارات التالية:

  • إنشاء مشروع جديد في Firebase
  • عدم إنشاء مخطط باستخدام Gemini (في هذا البرنامج التعليمي، ستستخدم مخططًا نموذجيًا مُعدًا مسبقًا )
  • إنشاء مثيل جديد في Cloud SQL
  • إنشاء نموذج React
mkdir myproj ; cd myproj
npx -y firebase-tools@latest login --reauth
npx -y firebase-tools@latest init dataconnect

2. مراجعة تعريفات GraphQL النموذجية

في Data Connect، يمكنك تحديد جميع مخططات قاعدة البيانات والعمليات باستخدام GraphQL. عند إعداد مشروعك، أنشأ Firebase CLI بعض التعريفات النموذجية لمساعدتك في البدء.

dataconnect/schema/schema.gql (مقتطف)
type Movie @table {
  title: String!
  imageUrl: String!
  genre: String
}

type MovieMetadata @table {
  movie: Movie! @unique
  rating: Float
  releaseYear: Int
  description: String
}
dataconnect/example/queries.gql (مقتطف)
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

3. نشر المخططات والعمليات

عند إجراء تغييرات على مخططات قاعدة البيانات أو طلبات البحث أو عمليات التعديل، عليك نشرها حتى تصبح التغييرات سارية على قاعدة البيانات.

npx -y firebase-tools@latest deploy --only dataconnect

4. تعبئة قاعدة البيانات ببيانات نموذجية

ستمنحك هذه البيانات الأولية محتوى يمكنك الاطّلاع عليه عند اختبار نموذج التطبيق. يُرجى العِلم أنّه في هذه الخطوة، أنت تنفّذ GraphQL عشوائيًا، وهو أمر مسموح به للمهام الإدارية.

npx -y firebase-tools@latest \
         dataconnect:execute dataconnect/seed_data.gql

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

يستخدم هذا الأمر تعريفات GraphQL لإنشاء مكتبة JavaScript خاصة بقاعدة البيانات، تتضمّن تعريفات أنواع كاملة. يمكنك استخدام هذه المكتبة في تطبيق العميل لتنفيذ جميع عمليات قاعدة البيانات.

يمكنك إنشاء مكتبات لمنصات متعددة، بما في ذلك Kotlin لنظام Android، Swift لنظام iOS وFlutter، عن طريق إضافة تعريفات إلى connector.yaml.

npx -y firebase-tools@latest dataconnect:sdk:generate
حزمة تطوير برامج (SDK) لـ React تم إنشاؤها تلقائيًا (مقتطف)
export interface ListMoviesData {
  movies: ({
    id: UUIDString;
    title: string;
    imageUrl: string;
    genre?: string | null;
  } & Movie_Key)[];
}

export function useListMovies(
  options?: useDataConnectQueryOptions&<ListMoviesData>
): UseDataConnectQueryResult&<ListMoviesData, undefined>;

6. إعداد تطبيق ويب

نفِّذ هذه الأوامر لإضافة تطبيق ويب جديد إلى مشروع Firebase.

npx -y firebase-tools@latest \
          apps:create web react-example
npx -y firebase-tools@latest \
          apps:sdkconfig web \
          -o web-app/src/firebase-config.json
cd web-app
npm i firebase \
            @tanstack/react-query \
            @tanstack-query-firebase/react

7. كتابة عميل React نموذجي

استبدِل محتوى web-app/src/App.jsx بتطبيق React البسيط هذا.

يُرجى العِلم أنّ التطبيق يُكمل عملية الوصول اللازمة إلى قاعدة البيانات باستخدام دالة من حزمة تطوير البرامج (SDK) التي تم إنشاؤها. تستخدم حزمة تطوير البرامج (SDK) التي تم إنشاؤها لـ React مكتبة TanStack Query للتعامل مع إدارة الحالة.

import { initializeApp } from 'firebase/app';
import firebaseConfig from './firebase-config.json';
import {
  QueryClient,
  QueryClientProvider
} from '@tanstack/react-query';

import { useListMovies } from '@dataconnect/generated/react';
import './App.css';

const app = initializeApp(firebaseConfig);
const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Movies />
    </QueryClientProvider>
  );
}

function Movies() {
  const { isLoading, data } = useListMovies();
  if (isLoading) {
    return <h1>...</h1>
  }
  return (
    <>
      {data?.movies.map(
        movie => <h1 key={movie.id}>{movie.title}</h1>
      )}
    </>
  );
}

export default App;

8. تجربة تطبيق الويب

ابدأ خادم التطوير للاطّلاع على التطبيق النموذجي أثناء عمله.

npm run dev

الخطوات التالية

تجربة إضافة Data Connect إلى VS Code

عند التطوير باستخدام Data Connect، ننصحك بشدة باستخدام إضافة Data Connect إلى VS Code. حتى إذا لم تكن تستخدم Visual Studio Code كبيئة التطوير الأساسية ، توفّر الإضافة عدة ميزات تجعل تطوير المخططات والعمليات أكثر ملاءمة:

  • خادم لغة GraphQL يوفّر عمليات التحقّق من البنية واقتراحات الإكمال التلقائي الخاصة بـ Data Connect
  • أزرار CodeLens متوافقة مع الرمز البرمجي تتيح لك قراءة البيانات وكتابتها من ملفات تعريف المخطط تعريفات وتنفيذ طلبات البحث وعمليات التعديل من تعريفات العمليات
  • مزامنة حزم تطوير البرامج (SDK) التي تم إنشاؤها تلقائيًا مع تعريفات GraphQL
  • إعداد مبسّط لمحاكي محلي
  • نشر مبسّط للإصدار العلني

استخدام محاكي Data Connect للتطوير المحلي

على الرغم من أنّ هذا البرنامج التعليمي أوضح لك كيفية نشر Data Connect مخططات وعمليات مباشرةً في الإصدار العلني، من المحتمل ألا تريد إجراء تغييرات على قاعدة بيانات الإصدار العلني أثناء تطوير تطبيقك بنشاط. بدلاً من ذلك، يمكنك إعداد Data Connect المحاكي وإجراء أعمال التطوير عليه بدلاً من الإصدار العلني. يُعد المحاكي مثيلاً محليًا من PGlite يعمل بطريقة مشابهة لمثيل Postgres نشط على CloudSQL.

التعرّف على كيفية كتابة المخططات و العمليات لتطبيقك

عند تطوير التطبيقات باستخدام Data Connect، يُعد تصميم المخططات والعمليات من أولى مهام التطوير وأهمها التي ستُكملها.

  • Gemini في Firebase Console هو أداة ذكاء اصطناعي يمكنها إنشاء مخططات Data Connect من وصف لتطبيقك باللغة الطبيعية. يمكن أن تساعدك هذه الأداة في البدء بسرعة كبيرة، خاصةً إذا لم يسبق لك العمل مع قواعد البيانات العلائقية.
  • بدلاً من ذلك، يمكنك كتابة مخططات قاعدة البيانات وطلبات البحث وعمليات التعديل مباشرةً باستخدام GraphQL. ابدأ بصفحة تصميم Data Connect مخططات وانتقِل إلى الصفحات التالية للتعرّف على كيفية كتابة العمليات.