Check out what’s new from Firebase at Google I/O 2022. Learn more

قم بالترقية من الإصدار 8 إلى Web SDK المعياري

يجب أن تفكر التطبيقات التي تستخدم Firebase Web SDK الإصدار 8 أو أقدم في الترحيل إلى الإصدار 9 باستخدام الإرشادات الواردة في هذا الدليل.

يفترض هذا الدليل أنك على دراية بالإصدار 8 وأنك ستستفيد من حزمة الوحدات النمطية مثل webpack أو Rollup للترقية والتطوير المستمر للإصدار 9.

يوصى بشدة باستخدام أداة تجميع الوحدات في بيئة التطوير الخاصة بك. إذا لم تستخدم واحدًا ، فلن تتمكن من الاستفادة من المزايا الرئيسية للإصدار 9 في حجم التطبيق المنخفض. ستحتاج إلى npm أو الغزل لتثبيت SDK.

ستعتمد خطوات الترقية في هذا الدليل على تطبيق ويب وهمي يستخدم مصادقة وحزمة تطوير برامج Cloud Firestore SDK. من خلال العمل من خلال الأمثلة ، يمكنك إتقان المفاهيم والخطوات العملية المطلوبة لترقية جميع مجموعات Firebase Web SDK المدعومة.

حول المكتبات المتوافقة

يتوفر نوعان من المكتبات للإصدار 9 من Firebase Web SDK:

  • معياري - سطح API جديد مصمم لتسهيل اهتزاز الشجرة (إزالة الكود غير المستخدم) لجعل تطبيق الويب الخاص بك صغيرًا وسريعًا قدر الإمكان.
  • التوافق - سطح واجهة برمجة تطبيقات مألوف متوافق تمامًا مع الإصدار 8 SDK ، مما يسمح لك بالترقية إلى الإصدار 9 دون تغيير كل كود Firebase الخاص بك مرة واحدة. تتمتع مكتبات Compat بمزايا حجم أو أداء قليلة أو معدومة مقارنة بنظيراتها من الإصدار 8.

يفترض هذا الدليل أنك ستستفيد من مكتبات الإصدار 9 المتوافقة لتسهيل الترقية. تتيح لك هذه المكتبات الاستمرار في استخدام كود الإصدار 8 جنبًا إلى جنب مع التعليمات البرمجية المعاد تصميمها للإصدار 9. وهذا يعني أنه يمكنك تجميع وتصحيح تطبيقك بسهولة أكبر أثناء عملك خلال عملية الترقية.

بالنسبة للتطبيقات ذات التعرض الضئيل جدًا لـ Firebase Web SDK - على سبيل المثال ، تطبيق يقوم بإجراء مكالمة بسيطة فقط إلى واجهات برمجة تطبيقات المصادقة - قد يكون من العملي إعادة صياغة كود الإصدار 8 دون استخدام مكتبات الإصدار 9 المتوافقة. إذا كنت تقوم بترقية مثل هذا التطبيق ، فيمكنك اتباع التعليمات الواردة في هذا الدليل لـ "الإصدار 9 المعياري" دون استخدام المكتبات المتوافقة.

حول عملية الترقية

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

  1. أضف مكتبات الإصدار 9 والمكتبات المتوافقة إلى تطبيقك.
  2. قم بتحديث بيانات الاستيراد في التعليمات البرمجية الخاصة بك إلى الإصدار 9 المتوافق.
  3. كود Refactor لمنتج واحد (على سبيل المثال ، المصادقة) إلى النمط المعياري.
  4. اختياري: في هذه المرحلة ، قم بإزالة مكتبة توافق المصادقة ورمز التوافق للمصادقة من أجل تحقيق فائدة حجم التطبيق للمصادقة قبل المتابعة.
  5. وظائف Refactor لكل منتج (على سبيل المثال ، Cloud Firestore و FCM وما إلى ذلك) إلى النمط المعياري والتجميع والاختبار حتى تكتمل جميع المناطق.
  6. تحديث كود التهيئة إلى النمط المعياري.
  7. قم بإزالة جميع بيانات التوافق المتبقية للإصدار 9 ورمز التوافق من تطبيقك.

احصل على الإصدار 9 SDK

للبدء ، احصل على الإصدار 9 من المكتبات والمكتبات المتوافقة باستخدام npm:

npm i firebase@9.8.1

# OR

yarn add firebase@9.8.1

تحديث الواردات إلى v9 متوافق

من أجل الحفاظ على عمل التعليمات البرمجية الخاصة بك بعد تحديث التبعية الخاصة بك من v8 إلى v9 beta ، قم بتغيير عبارات الاستيراد الخاصة بك لاستخدام الإصدار "المتوافق" لكل عملية استيراد. فمثلا:

قبل: الإصدار 8

import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';

بعد: الإصدار 9 المتوافق

// v9 compat packages are API compatible with v8 code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';

Refactor إلى النمط المعياري

بينما تستند واجهات برمجة التطبيقات للإصدار 8 إلى مساحة اسم متسلسلة بالنقاط ونمط خدمة ، فإن النهج المعياري للإصدار 9 يعني أنه سيتم تنظيم التعليمات البرمجية بشكل أساسي حول الوظائف . في الإصدار 9 ، لا تُرجع حزمة firebase/app والحزم الأخرى تصديرًا شاملاً يحتوي على جميع الطرق من الحزمة. بدلاً من ذلك ، تقوم الحزم بتصدير الوظائف الفردية.

في الإصدار 9 ، يتم تمرير الخدمات كوسيطة أولى ، ثم تستخدم الوظيفة تفاصيل الخدمة للقيام بالباقي. دعونا نفحص كيفية عمل ذلك في مثالين يستدعيان المصادقة و Cloud Firestore APIs.

مثال 1: إعادة هيكلة دالة المصادقة

قبل: الإصدار 9 المتوافق

كود الإصدار 9 مطابق لرمز الإصدار 8 ، لكن الواردات تغيرت.

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAuthStateChanged(user => { 
  // Check for user status
});

بعد: الإصدار 9 المعياري

تأخذ وظيفة getAuth firebaseApp . وظيفة onAuthStateChanged ليست مرتبطة بسلسلة من مثيل auth كما ستكون في الإصدار 8 ؛ بدلاً من ذلك ، إنها وظيفة مجانية تأخذ auth كأول معلمة لها.

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

مثال 2: إعادة هيكلة وظيفة Cloud Firestore

قبل: الإصدار 9 المتوافق

import "firebase/compat/firestore"

const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
    .get()
    .then((querySnapshot) => {
        querySnapshot.forEach((doc) => {
            // doc.data() is never undefined for query doc snapshots
            console.log(doc.id, " => ", doc.data());
        });
    })
    .catch((error) => {
        console.log("Error getting documents: ", error);
    });

بعد: الإصدار 9 المعياري

تأخذ وظيفة getFirestore firebaseApp ، والذي تم إرجاعه من initializeApp في مثال سابق. لاحظ كيف أن الكود الخاص بتكوين استعلام مختلف تمامًا في الإصدار 9 ؛ لا يوجد تسلسل ، والطرق مثل query أو where يتم كشفها الآن كوظائف مجانية.

import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";

const db = getFirestore(firebaseApp);

const q = query(collection(db, "cities"), where("capital", "==", true));

const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
  // doc.data() is never undefined for query doc snapshots
  console.log(doc.id, " => ", doc.data());
});

قم بتحديث المراجع إلى Firestore DocumentSnapshot.exists

يقدم الإصدار 9 تغييرًا فاصلًا تم فيه تغيير خاصية firestore.DocumentSnapshot.exists إلى طريقة . الوظيفة هي نفسها بشكل أساسي (اختبار ما إذا كان المستند موجودًا) ولكن يجب إعادة تشكيل التعليمات البرمجية الخاصة بك لاستخدام طريقة v9 كما هو موضح:

قبل: الإصدار 9 المتوافق

if (snapshot.exists) {
  console.log("the document exists");
}

بعد: الإصدار 9 المعياري

if (snapshot.exists()) {
  console.log("the document exists");
}

مثال 3: دمج أنماط كود الإصدار 8 والإصدار 9

يتيح لك استخدام المكتبات المتوافقة أثناء الترقية الاستمرار في استخدام رمز الإصدار 8 جنبًا إلى جنب مع الرمز المعاد تشكيله للإصدار 9. وهذا يعني أنه يمكنك الاحتفاظ برمز الإصدار 8 الحالي لـ Cloud Firestore أثناء إعادة بناء المصادقة أو رمز Firebase SDK الآخر إلى نمط الإصدار 9 ، ولا يزال تجميع تطبيقك بنجاح باستخدام كلا نمطي الكود. وينطبق الشيء نفسه على كود الإصدار 8 والإصدار 9 داخل منتج مثل Cloud Firestore ؛ يمكن أن تتواجد أنماط التعليمات البرمجية الجديدة والقديمة ، طالما أنك تستورد الحزم المتوافقة:

import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'

const docRef = firebase.firestore().doc();
getDoc(docRef);

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

تحديث كود التهيئة

قم بتحديث رمز التهيئة للتطبيق الخاص بك لاستخدام بناء جملة الإصدار 9 المعياري الجديد. من المهم تحديث هذا الرمز بعد الانتهاء من إعادة بناء جميع الكود في تطبيقك ؛ هذا لأن firebase.initializeApp() الحالة العامة لكل من واجهات برمجة التطبيقات المتوافقة والوحدات النمطية ، في حين أن وظيفة التهيئة المعيارية initializeApp() تهيئ الحالة للوحدات النمطية فقط.

قبل: الإصدار 9 المتوافق

import firebase from "firebase/compat/app"

firebase.initializeApp({ /* config */ });

بعد: الإصدار 9 المعياري

import { initializeApp } from "firebase/app"

const firebaseApp = initializeApp({ /* config */ });

إزالة رمز التوافق

لإدراك فوائد الحجم للإصدار 9 المعياري SDK ، يجب عليك في النهاية تحويل جميع الاستدعاءات إلى النمط المعياري الموضح أعلاه وإزالة جميع عبارات import "firebase/compat/* من التعليمات البرمجية. عند الانتهاء ، يجب ألا يكون هناك المزيد من المراجع إلى firebase.* مساحة الاسم العالمية أو أي رمز آخر في نمط الإصدار 8 SDK.

استخدام المكتبة المتوافقة من النافذة

تم تحسين الإصدار 9 SDK للعمل مع الوحدات بدلاً من كائن window المتصفح. سمحت الإصدارات السابقة من المكتبة بتحميل Firebase وإدارته باستخدام مساحة الاسم window.firebase . لا يُنصح بهذا من الآن فصاعدًا لأنه لا يسمح بإزالة التعليمات البرمجية غير المستخدمة. ومع ذلك ، فإن الإصدار المتوافق من JavaScript SDK يعمل مع window للمطورين الذين يفضلون عدم بدء مسار الترقية المعياري على الفور.

<script src="https://www.gstatic.com/firebasejs/9.8.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.8.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.8.1/firebase-auth-compat.js"></script>
<script>
   const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
   const db = firebaseApp.firestore();
   const auth = firebaseApp.auth();
</script>

تستخدم مكتبة التوافق كود الإصدار 9 المعياري تحت الغطاء وتوفر لها نفس واجهة برمجة التطبيقات مثل الإصدار 8 SDK ؛ هذا يعني أنه يمكنك الرجوع إلى مرجع الإصدار 8 من واجهة برمجة التطبيقات ومقتطفات رمز الإصدار 8 للحصول على التفاصيل. لا يُنصح باستخدام هذه الطريقة على المدى الطويل ، ولكن كبداية للترقية إلى مكتبة الإصدار 9 المعياري بالكامل.

مزايا وقيود الإصدار 9

يحتوي الإصدار 9 المعياري بالكامل على هذه المزايا مقارنة بالإصدارات السابقة:

  • يتيح الإصدار 9 تقليل حجم التطبيق بشكل كبير. وهي تعتمد تنسيق وحدة JavaScript الحديثة ، مما يسمح بممارسات "اهتزاز الشجرة" التي لا تستورد فيها سوى العناصر التي يحتاجها تطبيقك. اعتمادًا على التطبيق الخاص بك ، يمكن أن يؤدي اهتزاز الشجرة مع الإصدار 9 إلى تقليل كيلوبايتات أقل بنسبة 80٪ من تطبيق مشابه تم إنشاؤه باستخدام الإصدار 8.
  • سيستمر الإصدار 9 في الاستفادة من التطوير المستمر للميزات ، بينما سيتم تجميد الإصدار 8 في وقت ما في المستقبل.