از API فضای نامی به API مدولار ارتقا دهید

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

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

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

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

درباره کتابخانه‌های فضای نام ( compat ).

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

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

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

برای برنامه‌هایی که قرار گرفتن در معرض بسیار کمی با Firebase Web SDK دارند - برای مثال، برنامه‌ای که فقط یک تماس ساده با APIهای Authentication برقرار می‌کند - ممکن است بدون استفاده از کتابخانه‌های سازگار، کدهای فضای نام قدیمی‌تر را تغییر دهیم. اگر چنین برنامه‌ای را ارتقا می‌دهید، می‌توانید دستورالعمل‌های این راهنما را برای «API مدولار» بدون استفاده از کتابخانه‌های compat دنبال کنید.

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

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

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

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

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

npm i firebase@10.14.0

# OR

yarn add firebase@10.14.0

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

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

قبل: نسخه 8 یا قبل

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

بعد از : compat

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

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

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

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

مثال 1: بازسازی یک تابع Authentication

قبل از: همنشین

کد compat با کد فضای نام یکسان است، اما واردات تغییر کرده است.

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

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

بعد از: مدولار

تابع getAuth firebaseApp به عنوان اولین پارامتر خود می گیرد. تابع onAuthStateChanged مانند API فضای نامی از نمونه auth زنجیر نشده است. در عوض، این یک تابع رایگان است که auth به عنوان اولین پارامتر خود می گیرد.

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

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

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

API ماژولار یک تغییر قطعی را در getRedirectResult معرفی می کند. هنگامی که هیچ عملیات تغییر مسیری فراخوانی نمی شود، API ماژولار بر خلاف API با فضای نام، که یک UserCredential با یک کاربر null برمی گرداند null را برمی گرداند.

قبل از: همنشین

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

بعد از: مدولار

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

قبل از: همنشین

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);
    });

بعد از: مدولار

تابع getFirestore firebaseApp به عنوان اولین پارامتر خود می گیرد، که در مثال قبلی از initializeApp برگردانده شده بود. توجه داشته باشید که چگونه کد برای تشکیل یک پرس و جو در API مدولار بسیار متفاوت است. هیچ زنجیره ای وجود ندارد و روش هایی مانند 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

API ماژولار یک تغییر شکسته را معرفی می کند که در آن ویژگی firestore.DocumentSnapshot.exists به یک متد تغییر یافته است. عملکرد اساساً یکسان است (تست کردن اینکه آیا یک سند وجود دارد یا خیر) اما باید کد خود را تغییر دهید تا از روش جدیدتر همانطور که نشان داده شده است استفاده کنید:

قبل از: compat

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

بعد از: مدولار

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

مثال 3: ترکیب سبک کدهای فضای نام و مدولار

استفاده از کتابخانه‌های compat در حین ارتقا به شما امکان می‌دهد به استفاده از کدهای فضای نامی در کنار کدهای بازسازی‌شده برای API مدولار ادامه دهید. این به این معنی است که می‌توانید کدهای فضای نام موجود را برای Cloud Firestore نگه دارید، در حالی که Authentication یا دیگر کدهای Firebase SDK را به سبک مدولار تغییر می‌دهید، و همچنان با موفقیت برنامه خود را با هر دو سبک کد کامپایل کنید. همین امر برای کدهای API با فضای نام و ماژولار در محصولی مانند 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);

به خاطر داشته باشید که اگرچه برنامه شما کامپایل می شود، اما تا زمانی که دستورات سازگار و کد را به طور کامل از برنامه خود حذف نکنید، از مزایای اندازه برنامه کد ماژولار برخوردار نخواهید شد.

کد اولیه را به روز کنید

کد مقداردهی اولیه برنامه خود را برای استفاده از نحو مدولار به روز کنید. مهم است که این کد را پس از تکمیل مجدد تمام کدهای موجود در برنامه خود به روز کنید. این به این دلیل است که firebase.initializeApp() حالت جهانی را برای APIهای سازگار و مدولار مقداردهی می کند، در حالی که تابع ماژولار initializeApp() فقط حالت را برای ماژولار مقداردهی می کند.

قبل از: همنشین

import firebase from "firebase/compat/app"

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

بعد از: مدولار

import { initializeApp } from "firebase/app"

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

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

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

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

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

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

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

مزایا و محدودیت های SDK مدولار

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

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

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

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

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

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

درباره کتابخانه‌های فضای نام ( compat ).

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

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

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

برای برنامه‌هایی که قرار گرفتن در معرض بسیار کمی با Firebase Web SDK دارند - برای مثال، برنامه‌ای که فقط یک تماس ساده با APIهای Authentication برقرار می‌کند - ممکن است بدون استفاده از کتابخانه‌های سازگار، کدهای فضای نام قدیمی‌تر را تغییر دهیم. اگر چنین برنامه‌ای را ارتقا می‌دهید، می‌توانید دستورالعمل‌های این راهنما را برای «API مدولار» بدون استفاده از کتابخانه‌های compat دنبال کنید.

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

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

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

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

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

npm i firebase@10.14.0

# OR

yarn add firebase@10.14.0

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

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

قبل: نسخه 8 یا قبل

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

بعد از : compat

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

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

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

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

مثال 1: بازسازی یک تابع Authentication

قبل از: همنشین

کد compat با کد فضای نام یکسان است، اما واردات تغییر کرده است.

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

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

بعد از: مدولار

تابع getAuth firebaseApp به عنوان اولین پارامتر خود می گیرد. تابع onAuthStateChanged مانند API فضای نامی از نمونه auth زنجیر نشده است. در عوض، این یک تابع رایگان است که auth به عنوان اولین پارامتر خود می گیرد.

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

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

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

API ماژولار یک تغییر قطعی را در getRedirectResult معرفی می کند. هنگامی که هیچ عملیات تغییر مسیری فراخوانی نمی شود، API ماژولار بر خلاف API با فضای نام، که یک UserCredential با یک کاربر null برمی گرداند null را برمی گرداند.

قبل از: همنشین

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

بعد از: مدولار

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

قبل از: همنشین

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);
    });

بعد از: مدولار

تابع getFirestore firebaseApp به عنوان اولین پارامتر خود می گیرد، که در مثال قبلی از initializeApp برگردانده شده بود. توجه داشته باشید که چگونه کد برای تشکیل یک پرس و جو در API مدولار بسیار متفاوت است. هیچ زنجیره ای وجود ندارد و روش هایی مانند 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

API ماژولار یک تغییر شکسته را معرفی می کند که در آن ویژگی firestore.DocumentSnapshot.exists به یک متد تغییر یافته است. عملکرد اساساً یکسان است (تست کردن اینکه آیا یک سند وجود دارد یا خیر) اما باید کد خود را تغییر دهید تا از روش جدیدتر همانطور که نشان داده شده است استفاده کنید:

قبل از: compat

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

بعد از: مدولار

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

مثال 3: ترکیب سبک کدهای فضای نام و مدولار

استفاده از کتابخانه‌های compat در حین ارتقا به شما امکان می‌دهد به استفاده از کدهای فضای نامی در کنار کدهای بازسازی‌شده برای API مدولار ادامه دهید. این به این معنی است که می‌توانید کدهای فضای نام موجود را برای Cloud Firestore نگه دارید، در حالی که Authentication یا دیگر کدهای Firebase SDK را به سبک مدولار تغییر می‌دهید، و همچنان با موفقیت برنامه خود را با هر دو سبک کد کامپایل کنید. همین امر برای کدهای API با فضای نام و ماژولار در محصولی مانند 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);

به خاطر داشته باشید که اگرچه برنامه شما کامپایل می شود، اما تا زمانی که دستورات سازگار و کد را به طور کامل از برنامه خود حذف نکنید، از مزایای اندازه برنامه کد ماژولار برخوردار نخواهید شد.

کد اولیه را به روز کنید

کد مقداردهی اولیه برنامه خود را برای استفاده از نحو مدولار به روز کنید. مهم است که این کد را پس از تکمیل مجدد تمام کدهای موجود در برنامه خود به روز کنید. این به این دلیل است که firebase.initializeApp() حالت جهانی را برای APIهای سازگار و مدولار مقداردهی می کند، در حالی که تابع ماژولار initializeApp() فقط حالت را برای ماژولار مقداردهی می کند.

قبل از: همنشین

import firebase from "firebase/compat/app"

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

بعد از: مدولار

import { initializeApp } from "firebase/app"

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

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

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

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

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

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

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

مزایا و محدودیت های SDK مدولار

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

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

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

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

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

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

درباره کتابخانه‌های فضای نام ( compat ).

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

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

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

برای برنامه‌هایی که قرار گرفتن در معرض بسیار کمی با Firebase Web SDK دارند - برای مثال، برنامه‌ای که فقط یک تماس ساده با APIهای Authentication برقرار می‌کند - ممکن است بدون استفاده از کتابخانه‌های سازگار، کدهای فضای نام قدیمی‌تر را تغییر دهیم. اگر چنین برنامه‌ای را ارتقا می‌دهید، می‌توانید دستورالعمل‌های این راهنما را برای «API مدولار» بدون استفاده از کتابخانه‌های compat دنبال کنید.

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

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

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

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

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

npm i firebase@10.14.0

# OR

yarn add firebase@10.14.0

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

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

قبل: نسخه 8 یا قبل

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

بعد از : compat

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

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

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

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

مثال 1: بازسازی یک تابع Authentication

قبل از: همنشین

کد compat با کد فضای نام یکسان است، اما واردات تغییر کرده است.

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

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

بعد از: مدولار

تابع getAuth firebaseApp به عنوان اولین پارامتر خود می گیرد. تابع onAuthStateChanged مانند API فضای نامی از نمونه auth زنجیر نشده است. در عوض، این یک تابع رایگان است که auth به عنوان اولین پارامتر خود می گیرد.

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

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

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

API ماژولار یک تغییر قطعی را در getRedirectResult معرفی می کند. هنگامی که هیچ عملیات تغییر مسیری فراخوانی نمی شود، API ماژولار بر خلاف API با فضای نام، که یک UserCredential با یک کاربر null برمی گرداند null را برمی گرداند.

قبل از: همنشین

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

بعد از: مدولار

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

قبل از: همنشین

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);
    });

بعد از: مدولار

تابع getFirestore firebaseApp به عنوان اولین پارامتر خود می گیرد، که در مثال قبلی از initializeApp برگردانده شده بود. توجه داشته باشید که چگونه کد برای تشکیل یک پرس و جو در API مدولار بسیار متفاوت است. هیچ زنجیره ای وجود ندارد و روش هایی مانند 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

API ماژولار یک تغییر شکسته را معرفی می کند که در آن ویژگی firestore.DocumentSnapshot.exists به یک متد تغییر یافته است. عملکرد اساساً یکسان است (تست کردن اینکه آیا یک سند وجود دارد یا خیر) اما باید کد خود را تغییر دهید تا از روش جدیدتر همانطور که نشان داده شده است استفاده کنید:

قبل از: compat

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

بعد از: مدولار

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

مثال 3: ترکیب سبک کدهای فضای نام و مدولار

استفاده از کتابخانه‌های compat در حین ارتقا به شما امکان می‌دهد به استفاده از کدهای فضای نامی در کنار کدهای بازسازی‌شده برای API مدولار ادامه دهید. این به این معنی است که می‌توانید کدهای فضای نام موجود را برای Cloud Firestore نگه دارید، در حالی که Authentication یا دیگر کدهای Firebase SDK را به سبک مدولار تغییر می‌دهید، و همچنان با موفقیت برنامه خود را با هر دو سبک کد کامپایل کنید. همین امر برای کدهای API با فضای نام و ماژولار در محصولی مانند 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);

به خاطر داشته باشید که اگرچه برنامه شما کامپایل می شود، اما تا زمانی که دستورات سازگار و کد را به طور کامل از برنامه خود حذف نکنید، از مزایای اندازه برنامه کد ماژولار برخوردار نخواهید شد.

کد اولیه را به روز کنید

کد مقداردهی اولیه برنامه خود را برای استفاده از نحو مدولار به روز کنید. مهم است که این کد را پس از تکمیل مجدد تمام کدهای موجود در برنامه خود به روز کنید. این به این دلیل است که firebase.initializeApp() حالت جهانی را برای APIهای سازگار و مدولار مقداردهی می کند، در حالی که تابع ماژولار initializeApp() فقط حالت را برای ماژولار مقداردهی می کند.

قبل از: همنشین

import firebase from "firebase/compat/app"

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

بعد از: مدولار

import { initializeApp } from "firebase/app"

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

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

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

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

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

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

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

مزایا و محدودیت های SDK مدولار

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

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

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

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

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

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

درباره کتابخانه‌های فضای نام ( compat ).

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

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

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

برای برنامه‌هایی که قرار گرفتن در معرض بسیار کمی با Firebase Web SDK دارند - برای مثال، برنامه‌ای که فقط یک تماس ساده با APIهای Authentication برقرار می‌کند - ممکن است بدون استفاده از کتابخانه‌های سازگار، کدهای فضای نام قدیمی‌تر را تغییر دهیم. اگر چنین برنامه‌ای را ارتقا می‌دهید، می‌توانید دستورالعمل‌های این راهنما را برای «API مدولار» بدون استفاده از کتابخانه‌های compat دنبال کنید.

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

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

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

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

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

npm i firebase@10.14.0

# OR

yarn add firebase@10.14.0

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

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

قبل: نسخه 8 یا قبل

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

بعد از : compat

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

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

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

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

مثال 1: اصلاح مجدد یک عملکرد Authentication

قبل: سازگار

کد سازنده با کد نامگذاری یکسان است ، اما واردات تغییر کرده است.

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

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

بعد از آن: مدولار

عملکرد getAuth firebaseApp به عنوان اولین پارامتر خود می گیرد. عملکرد onAuthStateChanged از نمونه auth زنجیره ای نیست ، همانطور که در API نامگذاری شده است. در عوض ، این یک عملکرد رایگان است که auth به عنوان اولین پارامتر خود می گیرد.

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

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

استفاده از روش AUTH getRedirectResult به روز کنید

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

قبل: سازگار

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

بعد از آن: مدولار

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

قبل: سازگار

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);
    });

بعد از آن: مدولار

عملکرد getFirestore firebaseApp به عنوان اولین پارامتر خود ، که در مثال قبلی از initializeApp بازگردانده شده است ، می گیرد. توجه داشته باشید که چگونه کد برای تشکیل یک پرس و جو در API مدولار بسیار متفاوت است. هیچ زنجیره ای وجود ندارد ، و روش هایی مانند 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());
});

منابع را به DocumentSnapshot.exists Firestore به روز کنید.

API مدولار یک تغییر شکستن را معرفی می کند که در آن ویژگی firestore.DocumentSnapshot.exists به یک روش تغییر یافته است. عملکرد در اصل یکسان است (آزمایش اینکه آیا یک سندی وجود دارد) اما شما باید کد خود را برای استفاده از روش جدیدتر همانطور که نشان داده شده است ، مجدداً تغییر دهید:

قبل: سازگار

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

بعد از آن: مدولار

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

مثال 3: ترکیب سبک های کد نامگذاری شده و مدولار

استفاده از کتابخانه های سازگار در هنگام به روزرسانی به شما امکان می دهد تا در کنار کد اصلاح شده برای API مدولار ، از کد نامگذاری شده استفاده کنید. این بدان معنی است که شما می توانید در حالی که Authentication Refactor یا سایر کد SDK Firebase به سبک مدولار ، کد نامگذاری شده موجود را برای Cloud Firestore نگه دارید ، نگه دارید و هنوز هم برنامه خود را با هر دو سبک کد با موفقیت کامپایل کنید. همین مورد در مورد کد API نامگذاری شده و مدولار در محصولی مانند Cloud Firestore نیز صادق است. سبک های جدید و قدیمی کد می توانند همزیستی باشند ، تا زمانی که شما بسته های سازگار را وارد می کنید:

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

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

به خاطر داشته باشید که اگرچه برنامه شما کامپایل خواهد شد ، اما تا زمانی که بیانیه ها و کد های سازگار را از برنامه خود به طور کامل حذف نکنید ، مزایای اندازه برنامه کد مدولار را دریافت نخواهید کرد.

کد اولیه سازی را به روز کنید

کد اولیه سازی برنامه خود را برای استفاده از نحو مدولار به روز کنید. به روزرسانی این کد پس از اتمام اصلاح مجدد تمام کد در برنامه خود ، مهم است. این امر به این دلیل است که firebase.initializeApp() وضعیت جهانی را برای API های سازگار و مدولار آغاز می کند ، در حالی که عملکرد initializeApp() فقط حالت را برای مدولار آغاز می کند.

قبل: سازگار

import firebase from "firebase/compat/app"

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

بعد از آن: مدولار

import { initializeApp } from "firebase/app"

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

کد سازنده را حذف کنید

برای تحقق فواید اندازه API مدولار ، در نهایت باید تمام دعوت ها را به سبک مدولار نشان داده شده در بالا تبدیل کرده و همه import "firebase/compat/* را از کد خود حذف کنید. وقتی تمام شد ، دیگر نیازی به منابع دیگر وجود ندارد به firebase.* فضای نام جهانی یا هر کد دیگری در سبک API نامگذاری شده.

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

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

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

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

مزایا و محدودیت های SDK مدولار

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

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