استخدام حِزم Flutter SDK التي تم إنشاؤها

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

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

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

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

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

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

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

  1. أضِف Firebase إلى تطبيق Flutter.
  2. ثبِّت أداة سطر الأوامر flutterfire dart pub global activate flutterfire_cli.
  3. نفِّذ الأمر flutterfire configure.

بعد ذلك:

  1. طوِّر مخطط تطبيقك.
  2. إعداد إنشاء حزمة تطوير البرامج (SDK):

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

  4. تنفيذ طلبات البحث والتعديلات

  5. إعداد Data Connect المحاكي واستخدامه والتكرار

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

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

firebase init dataconnect:sdk

تحديث حِزم 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

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

بعد ذلك، ثبِّت المكوّن الإضافي Data Connect:

flutter pub add firebase_data_connect

إعداد Data Connect Flutter SDK

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

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

هناك مجموعتان من عمليات الاستيراد مطلوبة لإعداد رمز العميل، وهما عمليات الاستيراد العامةData Connect وعمليات الاستيراد الخاصة بحزمة تطوير البرامج (SDK) التي تم إنشاؤها.

// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';

// generated queries and mutations from SDK
import 'generated/movies.dart';

استخدام طلبات البحث من جهة العميل

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

import 'generated/movies.dart';

await MoviesConnector.instance.listMovies().execute();

استدعاء طرق طلبات البحث في حزمة تطوير البرامج (SDK)

إليك مثال على استخدام دوال اختصارات الإجراءات هذه:

import 'generated/movies.dart';

function onBtnClick() {
  // This will call the generated Dart from the CLI and then make an HTTP request to the server.
  MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}

الحقول الاختيارية

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

على سبيل المثال، الحقل rating اختياري عند استدعاء createMovie، لذا عليك توفيره في دالة الإنشاء.

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi"}).rating(5).execute();

الاشتراك في خدمة تلقّي الإشعارات بالتغييرات

يمكنك الاشتراك في التغييرات (التي سيتم تعديلها في أي وقت تنفّذ فيه طلب بحث).

QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();

// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
  updateUIWithMovies(data.movies);
});

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`

التعامل مع التغييرات في حقول التعداد

يمكن أن يحتوي مخطط التطبيق على تعدادات، ويمكن الوصول إليها من خلال طلبات بحث GraphQL.

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

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

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

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

تفرض حزمة تطوير البرامج (SDK) التي تم إنشاؤها معالجة القيم غير المعروفة. أي أنّ رمز العميل يجب أن يفكّ غلاف العنصر EnumValue إلى Known أو Unknown.

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print("This movie is in Academy aspect");
        break;
      case AspectRatio.WIDESCREEN:
        print("This movie is in Widescreen aspect");
        break;
      case AspectRatio.ANAMORPHIC:
        print("This movie is in Anamorphic aspect");
        break;
      case AspectRatio.IMAX:
        print("This movie is in IMAX aspect");
    }
  } else {
    print("Unknown aspect ratio detected: ${aspectValue.stringValue}");
  }
}

استخدام عمليات التغيير من جهة العميل

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

await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();

إنشاء نماذج أولية لتطبيقات Flutter واختبارها

تجهيز العملاء لاستخدام محاكي محلي

يمكنك استخدام محاكي Data Connect، سواء من إضافة Data Connect في VS Code أو من واجهة سطر الأوامر.

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

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';

MoviesConnector.instance.dataConnect
          .useDataConnectEmulator('127.0.0.1', 9399);

// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();

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

أنواع البيانات في حزمة تطوير البرامج (SDK) للغة Dart

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

نوع Data Connect Dart
الطابع الزمني firebase_data_connect.Timestamp
Int (‫32 بت) int
تاريخ DateTime
معرِّف فريد عالمي (UUID) سلسلة
Int64 int
عائم مزدوج
قيمة منطقية bool
أي firebase_data_connect.AnyValue