1. قبل البدء
في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية دمج Firebase مع تطبيق ويب Next.js يُسمى Friendly Eats، وهو موقع إلكتروني لمراجعات المطاعم.

يقدّم تطبيق الويب المكتمل ميزات مفيدة توضّح كيف يمكن أن تساعدك Firebase في إنشاء تطبيقات Next.js. وتشمل هذه الميزات ما يلي:
- الإنشاء والنشر التلقائيان: يستخدم هذا الدرس التطبيقي حول الترميز Firebase App Hosting لإنشاء رمز Next.js ونشره تلقائيًا في كل مرة يتم فيها إرسال الرمز إلى فرع تم ضبطه.
- تسجيل الدخول والخروج: يتيح لك تطبيق الويب المكتمل تسجيل الدخول باستخدام حساب Google وتسجيل الخروج. تتم إدارة تسجيل دخول المستخدمين واستمرارهم بالكامل من خلال مصادقة Firebase.
- الصور: يتيح تطبيق الويب المكتمل للمستخدمين الذين سجّلوا الدخول تحميل صور المطاعم. يتم تخزين مواد عرض الصور في مساحة تخزين سحابية لـ Firebase. توفّر حزمة Firebase JavaScript SDK عنوان URL متاحًا للجميع للصور التي تم تحميلها. يتم بعد ذلك تخزين عنوان URL العلني هذا في مستند المطعم ذي الصلة في Cloud Firestore.
- المراجعات: يتيح تطبيق الويب المكتمل للمستخدمين الذين سجّلوا الدخول نشر مراجعات للمطاعم تتألف من تقييم بالنجوم ورسالة نصية. يتم تخزين معلومات المراجعات في Cloud Firestore.
- الفلاتر: يتيح تطبيق الويب المكتمل للمستخدمين الذين سجّلوا الدخول فلترة قائمة المطاعم حسب الفئة والموقع الجغرافي والسعر. يمكنك أيضًا تخصيص طريقة الترتيب المستخدَمة. يتم الوصول إلى البيانات من Cloud Firestore، ويتم تطبيق طلبات بحث Firestore استنادًا إلى الفلاتر المستخدَمة.
المتطلبات الأساسية
- حساب GitHub
- معرفة بـ Next.js وJavaScript
أهداف الدورة التعليمية
- كيفية استخدام Firebase مع App Router في Next.js والعرض على جهة الخادم
- كيفية الاحتفاظ بالصور في مساحة تخزين سحابية لـ Firebase
- كيفية قراءة البيانات وكتابتها في قاعدة بيانات Cloud Firestore
- كيفية استخدام ميزة تسجيل الدخول باستخدام حساب Google مع حزمة Firebase JavaScript SDK
المتطلبات
- Git
- إصدار ثابت حديث من Node.js
- متصفّح من اختيارك، مثل Google Chrome
- بيئة تطوير تتضمّن أداة تعديل الرموز وTerminal
- حساب Google لإنشاء مشروع Firebase وإدارته
- إمكانية ترقية مشروع Firebase إلى خطة Blaze المَرِنة
2. إعداد بيئة التطوير ومستودع GitHub
يوفّر هذا الدرس التطبيقي حول الترميز قاعدة الرموز البرمجية الأولية للتطبيق ويعتمد على Firebase CLI.
إنشاء مستودع GitHub
يمكن العثور على مصدر الدرس التطبيقي حول الترميز على الرابط https://github.com/firebase/friendlyeats-web. يحتوي المستودع على نماذج مشاريع لمنصات متعددة. ومع ذلك، يستخدم هذا الدرس التطبيقي حول الترميز الدليل nextjs-start فقط. يُرجى تدوين الأدلة التالية:
* `nextjs-start`: contains the starter code upon which you build.
* `nextjs-end`: contains the solution code for the finished web app.
انسخ المجلد nextjs-start إلى مستودعك الخاص:
- باستخدام وحدة طرفية، أنشئ مجلدًا جديدًا على جهاز الكمبيوتر وانتقِل إلى الدليل الجديد:
mkdir codelab-friendlyeats-web cd codelab-friendlyeats-web - استخدِم حزمة npm giget لجلب المجلد
nextjs-startفقط:npx giget@latest "gh:firebase/friendlyeats-web/nextjs-start#master" . --install - تتبُّع التغييرات محليًا باستخدام git:
git init git add . git commit -m "Codelab starting point" git branch -M main - أنشئ مستودع GitHub جديدًا: https://github.com/new. يمكنك تسميته بأي اسم تريده.
- استنادًا إلى طريقة المصادقة على GitHub (HTTPS أو SSH)، انسخ عنوان URL الجديد الذي ينشئه GitHub لك:
https://github.com/<USER_NAME>/<REPOSITORY_NAME>.gitأوgit@github.com:<USER_NAME>/<REPOSITORY_NAME>.git
- انشر التغييرات المحلية في مستودع GitHub الجديد من خلال تنفيذ الأمر التالي. استبدِل العنصر النائب
<REPOSITORY_URL>بعنوان URL الفعلي للمستودع.git remote add origin <REPOSITORY_URL> git push -u origin main - من المفترض أن يظهر لك الآن الرمز الأوّلي في مستودع GitHub.
تثبيت Firebase CLI أو تحديثه
شغِّل الأمر التالي للتأكّد من تثبيت Firebase CLI وأنّه الإصدار 14.1.0 أو إصدار أحدث:
firebase --version
إذا ظهر لك إصدار أقدم أو لم يكن لديك Firebase CLI مثبّتًا، شغِّل أمر التثبيت:
npm install -g firebase-tools@latest
إذا لم تتمكّن من تثبيت Firebase CLI بسبب أخطاء في الأذونات، يمكنك الاطّلاع على مستندات npm أو استخدام خيار تثبيت آخر.
تسجيل الدخول إلى Firebase
- نفِّذ الأمر التالي لتسجيل الدخول إلى Firebase CLI:
firebase login
- بناءً على ما إذا كنت تريد أن تجمع Firebase البيانات، أدخِل
YأوN. - في المتصفّح، اختَر حسابك على Google، ثم انقر على السماح.
3- إعداد مشروع Firebase
في هذا القسم، عليك إعداد مشروع Firebase وربط تطبيق ويب على Firebase به. ستقوم أيضًا بإعداد خدمات Firebase التي يستخدمها نموذج تطبيق الويب.
إنشاء مشروع Firebase
- سجِّل الدخول إلى وحدة تحكّم Firebase باستخدام حساب Google نفسه الذي استخدمته في الخطوة السابقة.
- انقر على الزر لإنشاء مشروع جديد، ثم أدخِل اسم المشروع (على سبيل المثال،
FriendlyEats Codelab).
- انقر على متابعة.
- راجِع بنود Firebase واقبلها إذا طُلب منك ذلك، ثمّ انقر على متابعة.
- (اختياري) فعِّل ميزة "المساعدة بالذكاء الاصطناعي" في وحدة تحكّم Firebase (المعروفة باسم "Gemini في Firebase").
- في هذا الدرس التطبيقي حول الترميز، لا تحتاج إلى "إحصاءات Google"، لذا أوقِف خيار "إحصاءات Google".
- انقر على إنشاء مشروع، وانتظِر حتى يتم توفير مشروعك، ثم انقر على متابعة.
ترقية خطة أسعار Firebase
لاستخدام Firebase App Hosting و"مساحة تخزين سحابية لـ Firebase"، يجب أن يكون مشروع Firebase الخاص بك على خطة أسعار الدفع حسب الاستخدام (Blaze)، ما يعني أنّه مرتبط بحساب فوترة على Cloud.
- يتطلّب حساب Cloud Billing طريقة دفع، مثل بطاقة ائتمان.
- إذا كنت مستخدمًا جديدًا لـ Firebase وGoogle Cloud، تحقَّق من أهليتك للحصول على رصيد بقيمة 300 دولار أمريكي وحساب فوترة تجريبي مجاني على Cloud.
- إذا كنت تشارك في هذا الدرس التطبيقي حول الترميز كجزء من فعالية، اسأل المنظّم عمّا إذا كانت هناك أي أرصدة Cloud متاحة.
لترقية مشروعك إلى خطة Blaze، اتّبِع الخطوات التالية:
- في وحدة تحكُّم Firebase، اختَر ترقية خطتك.
- اختَر خطة Blaze. اتّبِع التعليمات الظاهرة على الشاشة لربط حساب "فوترة على Cloud" بمشروعك.
إذا كنت بحاجة إلى إنشاء حساب "فوترة على Cloud" كجزء من هذه الترقية، قد تحتاج إلى الرجوع إلى عملية الترقية في وحدة تحكّم Firebase لإكمال الترقية.
إضافة تطبيق ويب إلى مشروع Firebase
- انتقِل إلى نظرة عامة على المشروع في مشروع Firebase، وانقر على إضافة تطبيق، ثم انقر على الويب.
- في مربّع النص لقب التطبيق، أدخِل لقبًا يسهل تذكّره للتطبيق، مثل
My Next.js app. - أبقِ مربّع الاختيار إعداد ميزة "استضافة Firebase" لهذا التطبيق أيضًا غير محدّد.
- انقر على تسجيل التطبيق > المتابعة إلى وحدة التحكّم.
إعداد خدمات Firebase في وحدة تحكُّم Firebase
إعداد المصادقة
- في اللوحة اليمنى من وحدة تحكُّم Firebase، وسِّع إنشاء، ثمّ اختَر المصادقة.
- انقر على البدء.
- في عمود مقدّمو خدمات تسجيل الدخول (Sign-in providers)، انقر على Google > تفعيل (Enable).
- في مربّع النص الاسم العلني للمشروع، أدخِل اسمًا يسهل تذكّره، مثل
My Next.js app. - من القائمة المنسدلة البريد الإلكتروني المخصّص للدعم في المشروع، اختَر عنوان بريدك الإلكتروني.
- انقر على حفظ.
إعداد Cloud Firestore
- في اللوحة اليمنى من وحدة تحكُّم Firebase، وسِّع إنشاء، ثم اختَر قاعدة بيانات Firestore.
- انقر على إنشاء قاعدة بيانات.
- اختَر الإصدار العادي وانقر على التالي.
- لا تغيِّر معرّف قاعدة البيانات (Database ID)، واتركه مضبوطًا على
(default). - اختَر موقعًا جغرافيًا لقاعدة بياناتك، ثم انقر على التالي.
بالنسبة إلى التطبيقات الحقيقية، من الأفضل اختيار موقع جغرافي قريب من المستخدمين. - انقر على البدء في وضع الاختبار. اقرأ بيان إخلاء المسؤولية حول قواعد الأمان.
في وقت لاحق من هذا الدرس التطبيقي حول الترميز، ستضيف قواعد الأمان لتأمين بياناتك. لا توزِّع تطبيقًا أو تعرضه للجميع بدون إضافة قواعد أمان لقاعدة بياناتك. - انقر على إنشاء.
إعداد Cloud Storage for Firebase
- في اللوحة اليمنى من وحدة تحكّم Firebase، وسِّع إنشاء، ثم اختَر مساحة التخزين.
- انقر على البدء.
- اختَر موقعًا جغرافيًا لحزمة التخزين التلقائية.
يمكن للحزم فيUS-WEST1وUS-CENTRAL1وUS-EAST1الاستفادة من فئة "المجانية دائمًا" في Google Cloud Storage. أما الحِزم في جميع المواقع الجغرافية الأخرى، فتخضع لأسعار Google Cloud Storage واستخدامها. - انقر على البدء في وضع الاختبار. يُرجى قراءة بيان إخلاء المسؤولية حول قواعد الأمان.
في مرحلة لاحقة من هذا الدرس التطبيقي حول الترميز، ستضيف قواعد أمان لتأمين بياناتك. لا توزِّع تطبيقًا أو تعرضه للجميع بدون إضافة قواعد أمان إلى حزمة Storage. - انقر على إنشاء.
نشر قواعد الأمان
يحتوي الرمز البرمجي على مجموعات من قواعد الأمان لكل من Firestore و"مساحة تخزين سحابية لـ Firebase". بعد نشر "قواعد الأمان"، تتم حماية البيانات في قاعدة البيانات والحزمة بشكل أفضل من إساءة الاستخدام.
- في الوحدة الطرفية، اضبط واجهة سطر الأوامر لاستخدام مشروع Firebase الذي أنشأته سابقًا:
عندما يُطلب منك إدخال اسم مستعار، أدخِلfirebase use --add
friendlyeats-codelab. - لنشر "قواعد الأمان" هذه (بالإضافة إلى الفهارس التي ستحتاج إليها لاحقًا)، نفِّذ الأمر التالي في الوحدة الطرفية:
firebase deploy --only firestore,storage
- إذا طُلب منك:
"Cloud Storage for Firebase needs an IAM Role to use cross-service rules. Grant the new role?"، اضغط علىEnterلاختيار نعم.
4. مراجعة قاعدة الرموز البرمجية الأولية
في هذا القسم، ستراجع بعض أجزاء قاعدة الرموز البرمجية الأولية للتطبيق التي ستضيف إليها وظائف في هذا الدرس التطبيقي حول الترميز.
بنية المجلدات والملفات
يحتوي الجدول التالي على نظرة عامة على بنية المجلدات والملفات في التطبيق:
الملفات والمجلدات | الوصف |
| مكوّنات React للفلاتر والعناوين وتفاصيل المطاعم والمراجعات |
| الدوال الخدمية التي لا ترتبط بالضرورة بـ React أو Next.js |
| الرمز البرمجي الخاص بـ Firebase وإعدادات Firebase |
| مواد العرض الثابتة في تطبيق الويب، مثل الرموز |
| التوجيه باستخدام Next.js App Router |
| التبعيات في المشروع باستخدام npm |
| إعدادات خاصة بـ Next.js (يتم تفعيل إجراءات الخادم) |
| إعدادات خدمة لغة JavaScript |
مكوّنات الخادم والعميل
التطبيق هو تطبيق ويب Next.js يستخدم App Router. يتم استخدام العرض على جهة الخادم في جميع أنحاء التطبيق. على سبيل المثال، ملف src/app/page.js هو مكوّن خادم مسؤول عن الصفحة الرئيسية. ملف src/components/RestaurantListings.jsx هو مكوّن عميل يُشار إليه بالتوجيه "use client" في بداية الملف.
استيراد كشوفات الحسابات
قد تلاحظ عبارات استيراد مثل ما يلي:
import RatingPicker from "@/src/components/RatingPicker.jsx";
يستخدم التطبيق الرمز @ لتجنُّب مسارات الاستيراد النسبية غير المريحة، ويتم ذلك من خلال الأسماء البديلة للمسارات.
واجهات برمجة التطبيقات الخاصة بـ Firebase
يتم تضمين كل رموز واجهة برمجة التطبيقات في Firebase في الدليل src/lib/firebase. بعد ذلك، تستورد مكوّنات React الفردية الدوال المغلَّفة من دليل src/lib/firebase، بدلاً من استيراد دوال Firebase مباشرةً.
بيانات وهمية
يحتوي الملف src/lib/randomData.js على بيانات وهمية لمطاعم ومراجعات. يتم تجميع البيانات من هذا الملف في الرمز البرمجي في ملف src/lib/fakeRestaurants.js.
5- إنشاء خلفية في App Hosting
في هذا القسم، ستُعدّ واجهة خلفية في App Hosting لمراقبة فرع في مستودع git.
في نهاية هذا القسم، سيكون لديك خلفية في App Hosting مرتبطة بمستودعك في GitHub، والتي ستعيد إنشاء إصدار جديد من تطبيقك وطرحه تلقائيًا كلما أرسلت عملية تنفيذ جديدة إلى فرع main.
إنشاء خلفية
- انتقِل إلى صفحة App Hosting في وحدة تحكّم Firebase.
- انقر على البدء لبدء عملية إنشاء الخلفية.
- اختر منطقة. بالنسبة إلى تطبيق حقيقي، عليك اختيار المنطقة الأقرب إلى المستخدمين.
- اتّبِع التعليمات الواردة في خطوة استيراد مستودع GitHub لإعداد مصادقة GitHub.
- من المستودع، اختَر منح إذن الوصول إلى مستودع جديد في GitHub واتّبِع التعليمات لتفعيل الوصول إلى مستودع GitHub الذي أنشأته سابقًا.
- انقر على إعادة تحميل القائمة لإعادة تحميل القائمة، ثم اختَر المستودع وانقر على التالي.
- اضبط إعدادات النشر:
- اضبط الفرع المباشر على
main. - احتفِظ بالدليل الجذري على أنّه
/. - تفعيل عمليات الطرح التلقائية
- اضبط الفرع المباشر على
- أدخِل الاسم
friendlyeats-codelabللخلفية وانقر على التالي. - من ربط تطبيق ويب على Firebase، انقر على اختيار تطبيق ويب حالي على Firebase واختَر التطبيق الذي أضفته من القائمة
- انقر على إنهاء ونشر. ستتم إعادة توجيهك إلى صفحة جديدة حيث يمكنك الاطّلاع على حالة الخلفية الجديدة في App Hosting.
- انقر على عرض للاطّلاع على مزيد من المعلومات حول عملية نشر App Hosting، بما في ذلك حالة الطرح والسجلّات وتفاصيل الاستخدام.
- بعد اكتمال عملية الطرح، انقر لفتح عنوان URL لموقعك الإلكتروني ضمن النطاقات. قد يستغرق بدء العمل بضع دقائق بسبب انتشار نظام أسماء النطاقات.
- عفوًا عند تحميل الصفحة، ستظهر رسالة الخطأ "خطأ في التطبيق: حدث استثناء من جهة الخادم (يُرجى الاطّلاع على سجلّات الخادم لمزيد من المعلومات)".
- في وحدة تحكُّم Firebase، اطّلِع على علامة التبويب السجلّات في الخلفية في App Hosting. سيظهر لك سجلّ "خطأ: لم يتم التنفيذ". سنصلح ذلك في الخطوة التالية عندما نضيف المصادقة.
لقد نشرت تطبيق الويب الأوّلي. في كل مرة تنشر فيها عملية تثبيت جديدة في الفرع main من مستودع GitHub، سيظهر لك إصدار جديد ويبدأ طرحه في وحدة تحكّم Firebase، وسيتم تعديل موقعك الإلكتروني تلقائيًا بعد اكتمال عملية الطرح.
6. إضافة المصادقة إلى تطبيق الويب
في هذا القسم، يمكنك إضافة مصادقة إلى تطبيق الويب لتتمكّن من تسجيل الدخول إليه.
إضافة نطاق معتمَد
لن تقبل مصادقة Firebase طلبات تسجيل الدخول إلا من النطاقات التي تسمح بها. في هذه الخطوة، سنضيف نطاق الخلفية في App Hosting إلى قائمة النطاقات الموافَق عليها في مشروعك.
- افتح صفحة App Hosting وانقر على عرض أسفل موقعك الإلكتروني المنشور للوصول إلى صفحة نظرة عامة. انسخ اسم نطاق الخلفية في App Hosting.
- انتقِل إلى علامة التبويب "إعدادات المصادقة" (Auth Settings) واختَر المشروع الذي تريد إضافة نطاق معتمَد إليه. بعد ذلك، ابحث عن قسم النطاقات المعتمَدة وانقر عليه.
- انقر على الزر إضافة نطاق.
- أدخِل نطاق الخلفية في App Hosting.
- انقر على إضافة.
تنفيذ وظيفتَي تسجيل الدخول وتسجيل الخروج
في ملف src/lib/firebase/auth.js، استبدِل الدوال onAuthStateChanged وonIdTokenChanged وsignInWithGoogle وsignOut بالرمز التالي:
export function onAuthStateChanged(cb) {
return _onAuthStateChanged(auth, cb);
}
export function onIdTokenChanged(cb) {
return _onIdTokenChanged(auth, cb);
}
export async function signInWithGoogle() {
const provider = new GoogleAuthProvider();
try {
await signInWithPopup(auth, provider);
} catch (error) {
console.error("Error signing in with Google", error);
}
}
export async function signOut() {
try {
return auth.signOut();
} catch (error) {
console.error("Error signing out with Google", error);
}
}
يستخدم هذا الرمز واجهات برمجة التطبيقات التالية في Firebase:
Firebase API | الوصف |
تضيف هذه الطريقة مراقبًا للتغييرات في حالة تسجيل دخول المستخدم. | |
تضيف هذه الطريقة مراقبًا للتغييرات التي تطرأ على رمز المعرّف المميّز للمستخدم. | |
تنشئ هذه الطريقة مثيلاً لموفّر مصادقة Google. | |
لبدء مسار مصادقة مستند إلى مربّع حوار | |
يتم تسجيل خروج المستخدم. |
في ملف src/components/Header.jsx، يستدعي الرمز البرمجي الدالتَين signInWithGoogle وsignOut.
إرسال حالة المصادقة إلى الخادم
لنقل حالة المصادقة إلى الخادم، سنستخدم ملفات تعريف الارتباط. عندما تتغيّر حالة المصادقة في العميل، سنعدّل ملف تعريف الارتباط __session.
في src/components/Header.jsx، استبدِل الدالة useUserSession بالرمز التالي:
function useUserSession(initialUser) {
useEffect(() => {
return onIdTokenChanged(async (user) => {
if (user) {
const idToken = await user.getIdToken();
await setCookie("__session", idToken);
} else {
await deleteCookie("__session");
}
if (initialUser?.uid === user?.uid) {
return;
}
window.location.reload();
});
}, [initialUser]);
return initialUser;
}
قراءة حالة المصادقة على الخادم
سنستخدم FirebaseServerApp لنسخ حالة مصادقة العميل على الخادم.
افتح src/lib/firebase/serverApp.js واستبدِل دالة getAuthenticatedAppForUser:
export async function getAuthenticatedAppForUser() {
const authIdToken = (await cookies()).get("__session")?.value;
// Firebase Server App is a new feature in the JS SDK that allows you to
// instantiate the SDK with credentials retrieved from the client & has
// other affordances for use in server environments.
const firebaseServerApp = initializeServerApp(
// https://github.com/firebase/firebase-js-sdk/issues/8863#issuecomment-2751401913
initializeApp(),
{
authIdToken,
}
);
const auth = getAuth(firebaseServerApp);
await auth.authStateReady();
return { firebaseServerApp, currentUser: auth.currentUser };
}
التحقّق من التغييرات
يعرض التنسيق الجذر في ملف src/app/layout.js العنوان ويمرّر المستخدم، إذا كان متاحًا، كسمة.
<Header initialUser={currentUser?.toJSON()} />
هذا يعني أنّ مكوّن <Header> يعرض بيانات المستخدم، إذا كانت متاحة، أثناء وقت تشغيل الخادم. إذا كانت هناك أي تعديلات على المصادقة أثناء مراحل نشاط الصفحة بعد تحميل الصفحة الأولي، سيتولّى معالج onAuthStateChanged معالجتها.
حان الوقت الآن لطرح إصدار جديد والتحقّق من صحة ما أنشأته.
- أنشئ عملية تثبيت مع رسالة التثبيت "إضافة مصادقة" وأرسلها إلى مستودع GitHub الخاص بك.
git add . git commit -m "Add authentication" git push - افتح صفحة App Hosting، وعند اكتمال عملية الطرح الجديدة، انقر على عنوان URL للموقع الإلكتروني لفتحه.
- اختبار المصادقة:
- سجِّل الدخول باستخدام حساب Google وتأكَّد من ظهور اسمك المعروض في العنوان بعد تسجيل الدخول.
- سجِّل الخروج ثم أعِد تسجيل الدخول. يمكنك تكرار هذه الخطوة مع مستخدمين مختلفين.
- اختياري: انقر بزر الماوس الأيمن على تطبيق الويب، واختَر عرض مصدر الصفحة، وابحث عن الاسم المعروض. ويظهر في مصدر HTML الأولي الذي يعرضه الخادم.
7. عرض معلومات المطعم
يتضمّن تطبيق الويب بيانات وهمية للمطاعم والمراجعات.
إضافة مطعم واحد أو أكثر
لإدراج بيانات مطعم وهمية في قاعدة بيانات Cloud Firestore المحلية، اتّبِع الخطوات التالية:
- سجِّل الدخول إلى تطبيق الويب إذا لم يسبق لك ذلك. بعد ذلك، انقر على
> إضافة مطاعم نموذجية. يُرجى العِلم أنّه لا تظهر أي مطاعم في تطبيق الويب Friendly Eats لأنّنا لم نُعِدّ رمز جلب البيانات بعد. سنحلّ هذه المشكلة في الخطوة التالية. - في وحدة تحكُّم Firebase، ضمن صفحة قاعدة بيانات Firestore، انقر على مطاعم. ستظهر لك المستندات ذات المستوى الأعلى في مجموعة المطاعم، ويمثّل كل منها مطعمًا.
- انقر على بعض المستندات لاستكشاف خصائص مستند مطعم.
عرض قائمة المطاعم
تحتوي قاعدة بيانات Cloud Firestore الآن على مطاعم يمكن لتطبيق الويب Next.js عرضها.
لتحديد رمز جلب البيانات، اتّبِع الخطوات التالية:
- في ملف
src/app/page.js، ابحث عن مكوّن خادم<Home />، وراجِع طلب دالةgetRestaurantsالتي تسترد قائمة بالمطاعم في وقت تشغيل الخادم. يمكنك تنفيذ الدالةgetRestaurantsمن خلال الخطوات التالية. - في ملف
src/lib/firebase/firestore.js، استبدِل الدالتَينapplyQueryFiltersوgetRestaurantsبالرمز التالي:
function applyQueryFilters(q, { category, city, price, sort }) {
if (category) {
q = query(q, where("category", "==", category));
}
if (city) {
q = query(q, where("city", "==", city));
}
if (price) {
q = query(q, where("price", "==", price.length));
}
if (sort === "Rating" || !sort) {
q = query(q, orderBy("avgRating", "desc"));
} else if (sort === "Review") {
q = query(q, orderBy("numRatings", "desc"));
}
return q;
}
export async function getRestaurants(db = db, filters = {}) {
let q = query(collection(db, "restaurants"));
q = applyQueryFilters(q, filters);
const results = await getDocs(q);
return results.docs.map((doc) => {
return {
id: doc.id,
...doc.data(),
// Only plain objects can be passed to Client Components from Server Components
timestamp: doc.data().timestamp.toDate(),
};
});
}
- أنشئ عملية تثبيت مع رسالة التثبيت "قراءة قائمة المطاعم من Firestore" وأرسِلها إلى مستودع GitHub.
git add . git commit -m "Read the list of restaurants from Firestore" git push - افتح صفحة App Hosting في وحدة تحكّم Firebase وانتظِر حتى تكتمل عملية الطرح الجديدة.
- في تطبيق الويب، أعِد تحميل الصفحة. تظهر صور المطاعم على شكل مربّعات في الصفحة.
التحقّق من تحميل بيانات المطاعم في وقت تشغيل الخادم
عند استخدام إطار عمل Next.js، قد لا يكون واضحًا متى يتم تحميل البيانات في وقت تشغيل الخادم أو وقت تشغيل جهة العميل.
للتحقق من تحميل قوائم المطاعم في وقت تشغيل الخادم، اتبع الخطوات التالية:
- في تطبيق الويب، افتح "أدوات مطوّري البرامج" وأوقِف JavaScript.

- أعِد تحميل تطبيق الويب، وستظهر قوائم المطاعم. يتم عرض معلومات المطعم في استجابة الخادم. عند تفعيل JavaScript، يتم تعبئة معلومات المطعم من خلال رمز JavaScript من جهة العميل.
- في "أدوات مطوري البرامج"، أعِد تفعيل JavaScript.
الاستماع إلى آخر أخبار المطاعم باستخدام أدوات الاستماع إلى لقطات Cloud Firestore
في القسم السابق، رأيت كيف تم تحميل المجموعة الأولية من المطاعم من ملف src/app/page.js. ملف src/app/page.js هو مكوّن خادم ويتم عرضه على الخادم، بما في ذلك رمز جلب بيانات Firebase.
ملف src/components/RestaurantListings.jsx هو مكوّن من جهة العميل ويمكن ضبطه لدمج الترميز المعروض من جهة الخادم.
لضبط ملف src/components/RestaurantListings.jsx لملء الترميز المعروض من الخادم، اتّبِع الخطوات التالية:
- في ملف
src/components/RestaurantListings.jsx، راجِع الرمز التالي الذي سبق أن كتبناه لك:
useEffect(() => {
return getRestaurantsSnapshot((data) => {
setRestaurants(data);
}, filters);
}, [filters]);
يستدعي هذا الرمز الدالة getRestaurantsSnapshot()، وهي مشابهة للدالة getRestaurants() التي نفّذتها في خطوة سابقة. ومع ذلك، توفر دالة اللقطة هذه آلية رد اتصال بحيث يتم استدعاء رد الاتصال في كل مرة يتم فيها إجراء تغيير على مجموعة المطعم.
- في ملف
src/lib/firebase/firestore.js، استبدِل الدالةgetRestaurantsSnapshot()بالرمز التالي:
export function getRestaurantsSnapshot(cb, filters = {}) {
if (typeof cb !== "function") {
console.log("Error: The callback parameter is not a function");
return;
}
let q = query(collection(db, "restaurants"));
q = applyQueryFilters(q, filters);
return onSnapshot(q, (querySnapshot) => {
const results = querySnapshot.docs.map((doc) => {
return {
id: doc.id,
...doc.data(),
// Only plain objects can be passed to Client Components from Server Components
timestamp: doc.data().timestamp.toDate(),
};
});
cb(results);
});
}
- في ملف
src/lib/firebase/firestore.js، استبدِل الدالةgetRestaurantSnapshotById()بالرمز التالي:
export function getRestaurantSnapshotById(restaurantId, cb) {
if (!restaurantId) {
console.log("Error: Invalid ID received: ", restaurantId);
return;
}
if (typeof cb !== "function") {
console.log("Error: The callback parameter is not a function");
return;
}
const docRef = doc(db, "restaurants", restaurantId);
return onSnapshot(docRef, (docSnap) => {
cb({
...docSnap.data(),
timestamp: docSnap.data().timestamp.toDate(),
});
});
}
التغييرات التي يتم إجراؤها من خلال صفحة قاعدة بيانات Firestore تظهر الآن في تطبيق الويب في الوقت الفعلي.
- أنشئ عملية تثبيت مع رسالة التثبيت "Listen for realtime restaurant updates" (الاستماع إلى تحديثات المطاعم في الوقت الفعلي) وأرسلها إلى مستودع GitHub.
git add . git commit -m "Listen for realtime restaurant updates" git push - افتح صفحة App Hosting في وحدة تحكّم Firebase وانتظِر حتى تكتمل عملية الطرح الجديدة.
- في تطبيق الويب، انقر على
> إضافة مطاعم نموذجية. إذا تم تنفيذ دالة اللقطة بشكل صحيح، ستظهر المطاعم في الوقت الفعلي بدون إعادة تحميل الصفحة.
8. حفظ المراجعات التي يرسلها المستخدمون من تطبيق الويب
- في ملف
src/lib/firebase/firestore.js، استبدِل الدالةupdateWithRating()بالرمز التالي:
const updateWithRating = async (
transaction,
docRef,
newRatingDocument,
review
) => {
const restaurant = await transaction.get(docRef);
const data = restaurant.data();
const newNumRatings = data?.numRatings ? data.numRatings + 1 : 1;
const newSumRating = (data?.sumRating || 0) + Number(review.rating);
const newAverage = newSumRating / newNumRatings;
transaction.update(docRef, {
numRatings: newNumRatings,
sumRating: newSumRating,
avgRating: newAverage,
});
transaction.set(newRatingDocument, {
...review,
timestamp: Timestamp.fromDate(new Date()),
});
};
يُدرج هذا الرمز مستند Firestore جديدًا يمثّل المراجعة الجديدة. يعدّل الرمز أيضًا مستند Firestore الحالي الذي يمثّل المطعم بأرقام معدَّلة لعدد التقييمات ومتوسط التقييم المحسوب.
- استبدِل الدالة
addReviewToRestaurant()بالرمز التالي:
export async function addReviewToRestaurant(db, restaurantId, review) {
if (!restaurantId) {
throw new Error("No restaurant ID has been provided.");
}
if (!review) {
throw new Error("A valid review has not been provided.");
}
try {
const docRef = doc(collection(db, "restaurants"), restaurantId);
const newRatingDocument = doc(
collection(db, `restaurants/${restaurantId}/ratings`),
);
// corrected line
await runTransaction(db, (transaction) =>
updateWithRating(transaction, docRef, newRatingDocument, review),
);
} catch (error) {
console.error(
"There was an error adding the rating to the restaurant",
error,
);
throw error;
}
}
تنفيذ إجراء خادم Next.js
يوفّر إجراء Next.js Server Action واجهة برمجة تطبيقات ملائمة للوصول إلى بيانات النماذج، مثل data.get("text") للحصول على القيمة النصية من حمولة إرسال النموذج.
لاستخدام إجراء خادم Next.js لمعالجة إرسال نموذج المراجعة، اتّبِع الخطوات التالية:
- في ملف
src/components/ReviewDialog.jsx، ابحث عن السمةactionفي العنصر<form>.
<form
action={handleReviewFormSubmission}
onSubmit={() => {
handleClose();
}}
>
تشير قيمة السمة action إلى دالة تنفّذها في الخطوة التالية.
- في ملف
src/app/actions.js، استبدِل الدالةhandleReviewFormSubmission()بالرمز التالي:
export async function handleReviewFormSubmission(data) {
const { firebaseServerApp } = await getAuthenticatedAppForUser();
const db = getFirestore(firebaseServerApp);
await addReviewToRestaurant(db, data.get("restaurantId"), {
text: data.get("text"),
rating: data.get("rating"),
// This came from a hidden form field.
userId: data.get("userId"),
});
}
إضافة مراجعات لمطعم
لقد نفّذت ميزة إرسال المراجعات، لذا يمكنك الآن التحقّق من إدراج مراجعاتك في Cloud Firestore بشكل صحيح.
لإضافة مراجعة والتحقّق من إدراجها في Cloud Firestore، اتّبِع الخطوات التالية:
- أنشئ عملية تثبيت مع رسالة التثبيت "السماح للمستخدمين بإرسال مراجعات المطاعم" وأرسلها إلى مستودع GitHub الخاص بك.
git add . git commit -m "Allow users to submit restaurant reviews" git push - افتح صفحة App Hosting في وحدة تحكّم Firebase وانتظِر حتى تكتمل عملية الطرح الجديدة.
- أعِد تحميل تطبيق الويب، واختَر مطعمًا من الصفحة الرئيسية.
- في صفحة المطعم، انقر على
. - اختَر تقييمًا بالنجوم.
- اكتب مراجعة.
- انقر على إرسال. ستظهر مراجعتك في أعلى قائمة المراجعات.
- في Cloud Firestore، ابحث عن مستند المطعم الذي راجعته في لوحة إضافة مستند واختَره.
- في لوحة بدء عملية الجمع، اختَر التقييمات.
- في لوحة إضافة مستند، ابحث عن المستند الذي تريد مراجعته للتأكّد من إدراجه على النحو المتوقّع.
9. حفظ الملفات التي حمّلها المستخدمون من تطبيق الويب
في هذا القسم، ستضيف وظيفة تتيح لك استبدال الصورة المرتبطة بمطعم عندما تكون مسجّلاً الدخول. يمكنك تحميل الصورة إلى مساحة تخزين Firebase، وتعديل عنوان URL للصورة في مستند Cloud Firestore الذي يمثّل المطعم.
لحفظ الملفات التي حمّلها المستخدمون من تطبيق الويب، اتّبِع الخطوات التالية:
- في ملف
src/components/Restaurant.jsx، راجِع الرمز الذي يتم تشغيله عندما يحمّل المستخدم ملفًا:
async function handleRestaurantImage(target) {
const image = target.files ? target.files[0] : null;
if (!image) {
return;
}
const imageURL = await updateRestaurantImage(id, image);
setRestaurantDetails({ ...restaurantDetails, photo: imageURL });
}
لا يلزم إجراء أي تغييرات على هذه الدالة، ولكنك تقوم بتنفيذ سلوك الدالة updateRestaurantImage() في الخطوات التالية.
- في ملف
src/lib/firebase/storage.js، استبدِل الدالتَينupdateRestaurantImage()وuploadImage()بالرمز التالي:
export async function updateRestaurantImage(restaurantId, image) {
try {
if (!restaurantId) {
throw new Error("No restaurant ID has been provided.");
}
if (!image || !image.name) {
throw new Error("A valid image has not been provided.");
}
const publicImageUrl = await uploadImage(restaurantId, image);
await updateRestaurantImageReference(restaurantId, publicImageUrl);
return publicImageUrl;
} catch (error) {
console.error("Error processing request:", error);
}
}
async function uploadImage(restaurantId, image) {
const filePath = `images/${restaurantId}/${image.name}`;
const newImageRef = ref(storage, filePath);
await uploadBytesResumable(newImageRef, image);
return await getDownloadURL(newImageRef);
}
تم تنفيذ الدالة updateRestaurantImageReference() نيابةً عنك. تعدّل هذه الدالة مستند مطعم حالي في Cloud Firestore باستخدام عنوان URL معدَّل للصورة.
التحقّق من وظيفة تحميل الصور
للتأكّد من تحميل الصورة على النحو المتوقّع، اتّبِع الخطوات التالية:
- أنشئ عملية تثبيت مع رسالة التثبيت "السماح للمستخدمين بتغيير صورة كل مطعم" وأرسلها إلى مستودع GitHub.
git add . git commit -m "Allow users to change each restaurants' photo" git push - افتح صفحة App Hosting في وحدة تحكّم Firebase وانتظِر حتى تكتمل عملية الطرح الجديدة.
- في تطبيق الويب، تأكَّد من أنك مُسجِّل الدخول واختَر مطعمًا.
- انقر على
وحمِّل صورة من نظام الملفات. تغادر صورتك بيئتك المحلية ويتم تحميلها إلى Cloud Storage. تظهر الصورة فور تحميلها. - انتقِل إلى مساحة تخزين سحابية لـ Firebase.
- انتقِل إلى المجلد الذي يمثّل المطعم. الصورة التي حمّلتها متوفّرة في المجلد.

10. تلخيص مراجعات المطاعم باستخدام الذكاء الاصطناعي التوليدي
في هذا القسم، ستضيف ميزة ملخّص المراجعات ليتمكّن المستخدم من فهم آراء الجميع في مطعم معيّن بسرعة بدون الحاجة إلى قراءة كل مراجعة.
تخزين مفتاح Gemini API في Cloud Secret Manager
- لاستخدام Gemini API، ستحتاج إلى مفتاح واجهة برمجة التطبيقات. انتقِل إلى Google AI Studio وانقر على إنشاء مفتاح واجهة برمجة التطبيقات.
- أدخِل اسمًا للمفتاح كما تريد. إذا لم يكن مشروعك مدرجًا ضمن اختيار مشروع تم استيراده، انقر على استيراد مشروع، وضَع علامة في المربّع بجانب مشروعك في القائمة، ثم انقر على استيراد. أخيرًا، اختَر المشروع ضمن اختيار مشروع تم استيراده وانقر على إنشاء مفتاح.
- تتكامل ميزة App Hosting مع Cloud Secret Manager للسماح لك بتخزين القيم الحسّاسة، مثل مفاتيح واجهة برمجة التطبيقات، بشكل آمن:
- في الوحدة الطرفية، شغِّل الأمر لإنشاء مفتاح سرّي جديد:
firebase apphosting:secrets:set GEMINI_API_KEY- عندما يُطلب منك إدخال القيمة السرية، انسخ مفتاح Gemini API من Google AI Studio والصقه.
- عندما يُطلب منك تحديد ما إذا كان الرمز السرّي الجديد مخصّصًا للإصدار العلني أو للاختبار على الجهاز، اختَر "الإصدار العلني" (Production).
- عندما يُطلب منك منح الإذن لحساب الخدمة في الخلفية للوصول إلى الرمز السري، اختَر "نعم".
- عندما يُطلب منك إضافة المفتاح السري الجديد إلى
apphosting.yaml، أدخِلYللقبول.
يتم الآن تخزين مفتاح Gemini API بأمان في Cloud Secret Manager، ويمكن الوصول إليه من خلال الخلفية في App Hosting.
تنفيذ مكوّن ملخّص المراجعات
- في
src/components/Reviews/ReviewSummary.jsx، استبدِل الدالةGeminiSummaryبالرمز التالي:export async function GeminiSummary({ restaurantId }) { const { firebaseServerApp } = await getAuthenticatedAppForUser(); const reviews = await getReviewsByRestaurantId( getFirestore(firebaseServerApp), restaurantId ); const reviewSeparator = "@"; const prompt = ` Based on the following restaurant reviews, where each review is separated by a '${reviewSeparator}' character, create a one-sentence summary of what people think of the restaurant. Here are the reviews: ${reviews.map((review) => review.text).join(reviewSeparator)} `; try { if (!process.env.GEMINI_API_KEY) { // Make sure GEMINI_API_KEY environment variable is set: // https://genkit.dev/docs/get-started/ throw new Error( 'GEMINI_API_KEY not set. Set it with "firebase apphosting:secrets:set GEMINI_API_KEY"' ); } // Configure a Genkit instance. const ai = genkit({ plugins: [googleAI()], model: gemini20Flash, // set default model }); const { text } = await ai.generate(prompt); return ( <div className="restaurant__review_summary"> <p>{text}</p> <p>✨ Summarized with Gemini</p> </div> ); } catch (e) { console.error(e); return <p>Error summarizing reviews.</p>; } } - أنشئ عملية تثبيت مع رسالة التثبيت "استخدام الذكاء الاصطناعي لتلخيص المراجعات" وأرسِلها إلى مستودع GitHub.
git add . git commit -m "Use AI to summarize reviews" git push - افتح صفحة App Hosting في وحدة تحكّم Firebase وانتظِر حتى تكتمل عملية الطرح الجديدة.
- افتح صفحة مطعم. في أعلى الصفحة، من المفترض أن يظهر ملخّص من جملة واحدة لجميع المراجعات على الصفحة.
- أضِف مراجعة جديدة وأعِد تحميل الصفحة. من المفترض أن يظهر لك التغيير في الملخّص.
11. إلغاء نشر موقعك الإلكتروني على App Hosting
بعد إكمال هذا الدرس التطبيقي حول الترميز، إذا كنت لن تواصل استخدام التطبيق، يمكنك إلغاء نشره لضمان عدم وصول أي مستخدم إلى موارد Firestore وStorage وGemini. يمكنك إعادة النشر في أي وقت.
لإلغاء نشر موقع إلكتروني على App Hosting، اتّبِع الخطوات التالية:
- افتح App Hosting في وحدة تحكّم Firebase.
- ابحث عن الخلفية الخاصة بتطبيقك وانقر على عرض.
- في قسم معلومات الخلفية، انقر على إدارة بجانب النطاقات. يؤدي ذلك إلى تحميل صفحة النطاقات.
- بجانب نطاقك، انقر على رمز المزيد (النقاط الثلاث العمودية)، واختَر إيقاف النطاق، ثم انقر على إيقاف للتأكيد.
12. الخاتمة
تهانينا! لقد تعرّفت على كيفية استخدام Firebase لإضافة ميزات ووظائف إلى تطبيق Next.js، واستخدمت على وجه التحديد ما يلي:
- Firebase App Hosting لإنشاء رمز Next.js ونشره تلقائيًا في كل مرة يتم فيها إرسال الرمز إلى فرع تم ضبطه
- مصادقة Firebase لتفعيل وظيفة تسجيل الدخول والخروج
- Cloud Firestore لبيانات المطاعم ومراجعاتها
- مساحة تخزين سحابية لـ Firebase لصور المطاعم