از نسخه 8 به Web SDK مدولار ارتقا دهید

برنامه‌هایی که در حال حاضر از Firebase Web SDK نسخه 8 یا قبل‌تر استفاده می‌کنند، باید با استفاده از دستورالعمل‌های این راهنما، به نسخه 9 مهاجرت کنند.

این راهنما فرض می کند که شما با نسخه 8 آشنایی دارید و از یک بسته ماژول مانند webpack یا Rollup برای ارتقاء و توسعه نسخه 9 در حال انجام استفاده خواهید کرد.

استفاده از باندلر ماژول در محیط توسعه خود به شدت توصیه می شود. اگر از یکی استفاده نمی کنید، نمی توانید از مزایای اصلی نسخه 9 در کاهش حجم برنامه استفاده کنید. برای نصب SDK به npm یا نخ نیاز دارید.

مراحل ارتقا در این راهنما حول یک برنامه وب خیالی است که از احراز هویت و Cloud Firestore SDK استفاده می کند. با کار کردن بر روی مثال‌ها، می‌توانید بر مفاهیم و مراحل عملی مورد نیاز برای ارتقاء همه SDK‌های Web Firebase پشتیبانی شده تسلط پیدا کنید.

درباره کتابخانه های سازگار

دو نوع کتابخانه برای Firebase Web SDK نسخه 9 موجود است:

• مدولار - یک سطح API جدید که برای تسهیل تکان دادن درخت (حذف کدهای استفاده نشده) طراحی شده است تا برنامه وب شما تا حد امکان کوچک و سریع باشد.
• Compat - یک سطح API آشنا که کاملاً با نسخه 8 SDK سازگار است و به شما امکان می دهد بدون تغییر همه کدهای Firebase به یکباره به نسخه 9 ارتقا دهید. کتابخانه های Compat نسبت به نسخه 8 همتای خود دارای مزیت های اندک یا بدون اندازه یا عملکرد هستند.

این راهنما فرض می کند که شما از کتابخانه های سازگار نسخه 9 برای تسهیل ارتقای خود استفاده خواهید کرد. این کتابخانه‌ها به شما امکان می‌دهند تا به استفاده از کد نسخه 8 در کنار کدهای بازسازی‌شده برای نسخه 9 ادامه دهید. این بدان معناست که می‌توانید برنامه خود را آسان‌تر در حین کار در فرآیند ارتقا، کامپایل و اشکال‌زدایی کنید.

برای برنامه‌هایی که قرار گرفتن در معرض بسیار کمی با Firebase Web SDK دارند - برای مثال، برنامه‌ای که فقط یک تماس ساده با APIهای احراز هویت برقرار می‌کند - ممکن است اصلاح کد نسخه 8 بدون استفاده از کتابخانه‌های سازگار نسخه 9 عملی باشد. اگر چنین برنامه‌ای را ارتقا می‌دهید، می‌توانید دستورالعمل‌های این راهنما را برای "نسخه 9 ماژولار" بدون استفاده از کتابخانه‌های compat دنبال کنید.

درباره روند ارتقا

هر مرحله از فرآیند ارتقا به گونه ای است که می توانید ویرایش منبع برنامه خود را به پایان برسانید و سپس آن را بدون شکستگی کامپایل و اجرا کنید. به طور خلاصه، در اینجا کاری که برای ارتقاء یک برنامه انجام خواهید داد:

1. کتابخانه های نسخه 9 و کتابخانه های سازگار را به برنامه خود اضافه کنید.
2. عبارات واردات را در کد خود به v9 compat به روز کنید.
3. کد Refactor برای یک محصول واحد (به عنوان مثال، احراز هویت) به سبک مدولار.
4. اختیاری: در این مرحله، کتابخانه Compat Authentication و کد سازگار برای Authentication را حذف کنید تا قبل از ادامه، از مزیت اندازه برنامه برای Authentication استفاده کنید.
5. توابع Refactor برای هر محصول (به عنوان مثال، Cloud Firestore، FCM، و غیره) به سبک مدولار، کامپایل و آزمایش تا زمانی که همه مناطق کامل شوند.
6. کد اولیه را به سبک مدولار به روز کنید.
7. تمام عبارات سازگار نسخه 9 باقی مانده و کد سازگار را از برنامه خود حذف کنید.

نسخه 9 SDK را دریافت کنید

برای شروع، کتابخانه های نسخه 9 و کتابخانه های سازگار را با استفاده از npm دریافت کنید:

npm i firebase@9.22.1

# OR

yarn add firebase@9.22.1

به روز رسانی واردات به v9 compat

برای اینکه کد خود را پس از به‌روزرسانی وابستگی از نسخه 8 به نسخه بتای 9 فعال نگه دارید، گزاره‌های واردات خود را برای استفاده از نسخه «Compat» هر واردات تغییر دهید. مثلا:

قبل: نسخه 8

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

بعد از: نسخه 9 compat

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

Refactor به سبک مدولار

در حالی که APIهای نسخه 8 بر اساس یک فضای نام و الگوی خدمات زنجیره‌ای هستند، رویکرد ماژولار نسخه 9 به این معنی است که کد شما عمدتاً بر اساس توابع سازمان‌دهی می‌شود. در نسخه 9، بسته firebase/app و سایر بسته‌ها صادرات جامعی را که شامل همه روش‌های بسته باشد، برنمی‌گردانند. در عوض، بسته ها توابع فردی را صادر می کنند.

در نسخه 9، سرویس ها به عنوان اولین آرگومان ارسال می شوند و سپس تابع از جزئیات سرویس برای انجام بقیه موارد استفاده می کند. بیایید بررسی کنیم که چگونه این کار در دو مثال انجام می شود که Refactor به API های Authentication و Cloud Firestore فراخوانی می کند.

مثال 1: بازسازی یک تابع احراز هویت

قبل: نسخه 9 compat

کد سازگار نسخه 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 مانند نسخه 8 از نمونه auth زنجیر نشده است. در عوض، این یک تابع رایگان است که auth را به عنوان اولین پارامتر خود می گیرد.

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

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

مدیریت به‌روزرسانی روش Auth getRedirectResult

نسخه 9 یک تغییر اساسی را در getRedirectResult معرفی می کند. هنگامی که هیچ عملیات تغییر مسیری فراخوانی نمی شود، نسخه 9 بر خلاف نسخه 8، که یک UserCredential با یک کاربر null برمی گرداند، null را برمی گرداند.

قبل: نسخه 9 compat

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 compat

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 compat

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

بعد از: نسخه 9 ماژولار

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

مثال 3: ترکیب سبک کد نسخه 8 و نسخه 9

استفاده از کتابخانه های compat در حین ارتقا به شما امکان می دهد به استفاده از کد نسخه 8 در کنار کدهای بازسازی شده برای نسخه 9 ادامه دهید. این بدان معنی است که می توانید کد نسخه 8 موجود را برای Cloud Firestore نگه دارید در حالی که Authentication یا سایر کدهای Firebase SDK را به سبک نسخه 9 تغییر می دهید، و همچنان با موفقیت برنامه خود را با هر دو سبک کد کامپایل کنید. همین امر برای کد نسخه 8 و نسخه 9 در محصولی مانند Cloud Firestore صادق است. تا زمانی که بسته‌های compat را وارد می‌کنید، سبک‌های کد جدید و قدیمی می‌توانند با هم وجود داشته باشند:

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() حالت جهانی را برای APIهای سازگار و مدولار مقداردهی می کند، در حالی که تابع ماژولار initializeApp() InitializeApp فقط حالت را برای ماژولار مقداردهی می کند.

قبل: نسخه 9 compat

import firebase from "firebase/compat/app"

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

بعد از: نسخه 9 ماژولار

import { initializeApp } from "firebase/app"

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

کد compat را حذف کنید

برای درک مزایای اندازه نسخه 9 SDK مدولار، در نهایت باید تمام فراخوان‌ها را به سبک مدولار نشان داده شده در بالا تبدیل کنید و تمام عبارات import "firebase/compat/* را از کد خود حذف کنید. پس از اتمام کار، هیچ موردی وجود ندارد. ارجاعات بیشتر به firebase.* فضای نام جهانی یا هر کد دیگری در سبک SDK نسخه 8.

استفاده از کتابخانه compat از پنجره

نسخه 9 SDK برای کار با ماژول ها به جای شی window مرورگر بهینه شده است. نسخه‌های قبلی کتابخانه بارگیری و مدیریت Firebase را با استفاده از فضای نام window.firebase . این کار در آینده توصیه نمی شود زیرا امکان حذف کدهای استفاده نشده را نمی دهد. با این حال، نسخه سازگار JavaScript SDK برای توسعه دهندگانی که ترجیح می دهند بلافاصله مسیر ارتقاء ماژولار را شروع نکنند، با window کار می کند.

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

کتابخانه سازگاری از کد ماژولار نسخه 9 در زیر هود استفاده می کند و همان API را با نسخه 8 SDK ارائه می دهد. این بدان معنی است که می توانید برای جزئیات به مرجع نسخه 8 API و قطعه کد نسخه 8 مراجعه کنید. این روش برای استفاده طولانی مدت توصیه نمی شود، اما به عنوان شروعی برای ارتقاء به کتابخانه کاملاً ماژولار نسخه 9 توصیه می شود.

مزایا و محدودیت های نسخه 9

نسخه 9 کاملاً ماژولار شده این مزایا را نسبت به نسخه های قبلی دارد:

• نسخه 9 اندازه برنامه را به طور چشمگیری کاهش می دهد. این فرمت ماژول جاوا اسکریپت مدرن را به کار می‌گیرد و به شیوه‌های "تکان دادن درخت" اجازه می‌دهد که در آن فقط مصنوعاتی را که برنامه‌تان نیاز دارد وارد کنید. بسته به برنامه شما، تکان دادن درخت با نسخه 9 می تواند 80٪ کیلوبایت کمتری نسبت به یک برنامه مشابه ساخته شده با نسخه 8 داشته باشد.
• نسخه 9 همچنان از توسعه ویژگی های مداوم بهره مند خواهد شد، در حالی که نسخه 8 در نقطه ای در آینده مسدود خواهد شد.