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 در کاهش حجم برنامه استفاده کنید. برای نصب SDK به npm یا نخ نیاز دارید.

مراحل ارتقا در این راهنما حول یک برنامه وب خیالی است که از احراز هویت و Cloud Firestore SDK استفاده می کند. با کار کردن بر روی مثال‌ها، می‌توانید بر مفاهیم و مراحل عملی مورد نیاز برای ارتقاء تمام SDK‌های وب 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 برای یک محصول واحد (به عنوان مثال، Authentication) به سبک مدولار.
  4. اختیاری: در این مرحله، کتابخانه Compat Authentication و کد سازگار برای Authentication را حذف کنید تا قبل از ادامه، مزیت اندازه برنامه را برای Authentication متوجه شوید.
  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 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
});

مثال 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.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 در زیر هود استفاده می کند و همان API را با نسخه 8 SDK ارائه می دهد. این بدان معنی است که می توانید برای جزئیات به مرجع نسخه 8 API و قطعه کد نسخه 8 مراجعه کنید. این روش برای استفاده طولانی مدت توصیه نمی شود، اما به عنوان شروعی برای ارتقاء به کتابخانه کاملاً ماژولار نسخه 9 توصیه می شود.

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

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

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