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

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

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

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

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

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

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

• معياري - سطح API جديد مصمم لتسهيل اهتزاز الشجرة (إزالة الكود غير المستخدم) لجعل تطبيق الويب الخاص بك صغيرًا وسريعًا قدر الإمكان.
• Compat - سطح واجهة برمجة تطبيقات مألوف متوافق تمامًا مع الإصدار 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.17.1

# OR

yarn add firebase@9.17.1

قم بتحديث الواردات إلى الإصدار 9 المتوافق

من أجل الحفاظ على عمل التعليمات البرمجية الخاصة بك بعد تحديث التبعية من 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
});

تحديث معالجة أسلوب المصادقة getRedirectResult

يقدم الإصدار 9 تغييرًا فاصلًا في getRedirectResult . عندما لا يتم استدعاء أي عملية إعادة توجيه ، فإن الإصدار 9 يُرجع null على عكس الإصدار 8 ، الذي أعاد UserCredential مع مستخدم null .

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

const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
  return null;
}
return result;

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

const result = await getRedirectResult(auth);
// Provider of the access token could be Facebook, Github, etc.
if (result === null || provider.credentialFromResult(result) === null) {
  return null;
}
return result;

مثال 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.17.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.17.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.17.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 في وقت ما في المستقبل.