العمل مع قوائم البيانات على الويب

احصل على مرجع قاعدة البيانات

لقراءة البيانات أو كتابتها من قاعدة البيانات ، تحتاج إلى مثيل لـ firebase.database.Reference :

Web modular API

import { getDatabase } from "firebase/database";

const database = getDatabase();

Web namespaced API

var database = firebase.database();

قوائم القراءة والكتابة

إلحاق بقائمة البيانات

استخدم طريقة push() لإلحاق البيانات بقائمة في التطبيقات متعددة المستخدمين. تنشئ طريقة push() مفتاحًا فريدًا في كل مرة تتم فيها إضافة طفل جديد إلى مرجع Firebase المحدد. باستخدام هذه المفاتيح التي تم إنشاؤها تلقائيًا لكل عنصر جديد في القائمة ، يمكن للعديد من العملاء إضافة توابع إلى نفس الموقع في نفس الوقت دون تعارض في الكتابة. يعتمد المفتاح الفريد الذي تم إنشاؤه بواسطة push() على طابع زمني ، لذلك يتم ترتيب عناصر القائمة تلقائيًا ترتيبًا زمنيًا.

يمكنك استخدام الإشارة إلى البيانات الجديدة التي يتم إرجاعها بواسطة طريقة push() للحصول على قيمة مفتاح الطفل الذي تم إنشاؤه تلقائيًا أو تعيين البيانات للطفل. تحتوي خاصية .key لمرجع push() على المفتاح الذي تم إنشاؤه تلقائيًا.

يمكنك استخدام هذه المفاتيح التي تم إنشاؤها تلقائيًا لتبسيط تسوية هيكل البيانات. لمزيد من المعلومات ، راجع مثال توزيع البيانات.

على سبيل المثال ، يمكن استخدام push() لإضافة منشور جديد إلى قائمة المنشورات في تطبيق اجتماعي:

Web modular API

import { getDatabase, ref, push, set } from "firebase/database";

// Create a new post reference with an auto-generated id
const db = getDatabase();
const postListRef = ref(db, 'posts');
const newPostRef = push(postListRef);
set(newPostRef, {
    // ...
});

Web namespaced API

// Create a new post reference with an auto-generated id
var postListRef = firebase.database().ref('posts');
var newPostRef = postListRef.push();
newPostRef.set({
    // ...
});

استمع لأحداث الأطفال

يتم تشغيل الأحداث الفرعية استجابةً لعمليات معينة تحدث لأبناء عقدة من عملية مثل إضافة طفل جديد من خلال طريقة push() أو تحديث طفل من خلال طريقة update() .

حدث استخدام نموذجي
child_added استرجع قوائم العناصر أو استمع للإضافات إلى قائمة العناصر. يتم تشغيل هذا الحدث مرة واحدة لكل طفل موجود ثم مرة أخرى في كل مرة يتم فيها إضافة طفل جديد إلى المسار المحدد. يمرر المستمع لقطة تحتوي على بيانات الطفل الجديد.
child_changed استمع إلى التغييرات التي تم إجراؤها على العناصر الموجودة في القائمة. يتم تشغيل هذا الحدث في أي وقت يتم فيه تعديل عقدة فرعية. يتضمن هذا أي تعديلات على أحفاد العقدة الفرعية. تحتوي اللقطة التي تم تمريرها إلى مستمع الحدث على البيانات المحدثة للطفل.
child_removed استمع للعناصر التي يتم إزالتها من القائمة. يتم تشغيل هذا الحدث عند إزالة طفل مباشر. تحتوي اللقطة التي تم تمريرها إلى كتلة رد الاتصال على بيانات الطفل الذي تمت إزالته.
child_moved استمع إلى التغييرات في ترتيب العناصر في قائمة مرتبة. تتبع أحداث child_moved دائمًا حدث child_changed الذي تسبب في تغيير ترتيب العنصر (بناءً على طريقة الترتيب الحالية).

يمكن أن يكون كل من هؤلاء معًا مفيدًا للاستماع إلى التغييرات التي تطرأ على عقدة معينة في قاعدة البيانات. على سبيل المثال ، قد يستخدم تطبيق التدوين الاجتماعي هذه الطرق معًا لمراقبة النشاط في تعليقات المنشور ، كما هو موضح أدناه:

Web modular API

import { getDatabase, ref, onChildAdded, onChildChanged, onChildRemoved } from "firebase/database";

const db = getDatabase();
const commentsRef = ref(db, 'post-comments/' + postId);
onChildAdded(commentsRef, (data) => {
  addCommentElement(postElement, data.key, data.val().text, data.val().author);
});

onChildChanged(commentsRef, (data) => {
  setCommentValues(postElement, data.key, data.val().text, data.val().author);
});

onChildRemoved(commentsRef, (data) => {
  deleteComment(postElement, data.key);
});

Web namespaced API

var commentsRef = firebase.database().ref('post-comments/' + postId);
commentsRef.on('child_added', (data) => {
  addCommentElement(postElement, data.key, data.val().text, data.val().author);
});

commentsRef.on('child_changed', (data) => {
  setCommentValues(postElement, data.key, data.val().text, data.val().author);
});

commentsRef.on('child_removed', (data) => {
  deleteComment(postElement, data.key);
});

استمع إلى الأحداث القيمة

في حين أن الاستماع إلى الأحداث التابعة هو الطريقة الموصى بها لقراءة قوائم البيانات ، فهناك مواقف تستفيد من الاستماع إلى الأحداث ذات القيمة في مرجع قائمة.

سيؤدي إرفاق مراقب value بقائمة البيانات إلى إرجاع القائمة الكاملة للبيانات كلقطة واحدة يمكنك بعد ذلك تكرارها للوصول إلى الأطفال الفرديين.

حتى عندما يكون هناك تطابق واحد فقط للاستعلام ، فإن اللقطة تظل قائمة ؛ يحتوي فقط على عنصر واحد. للوصول إلى العنصر ، تحتاج إلى تكرار النتيجة:

Web modular API

import { getDatabase, ref, onValue } from "firebase/database";

const db = getDatabase();
const dbRef = ref(db, '/a/b/c');

onValue(dbRef, (snapshot) => {
  snapshot.forEach((childSnapshot) => {
    const childKey = childSnapshot.key;
    const childData = childSnapshot.val();
    // ...
  });
}, {
  onlyOnce: true
});

Web namespaced API

ref.once('value', (snapshot) => {
  snapshot.forEach((childSnapshot) => {
    var childKey = childSnapshot.key;
    var childData = childSnapshot.val();
    // ...
  });
});

يمكن أن يكون هذا النمط مفيدًا عندما تريد جلب جميع العناصر الفرعية للقائمة في عملية واحدة ، بدلاً من الاستماع إلى أحداث إضافية مضافة للأطفال.

فرز البيانات وتصفيتها

يمكنك استخدام فئة Realtime Database Query لاسترداد البيانات التي تم فرزها حسب المفتاح أو القيمة أو حسب قيمة الطفل. يمكنك أيضًا تصفية النتيجة التي تم فرزها إلى عدد محدد من النتائج أو نطاق من المفاتيح أو القيم.

فرز البيانات

لاسترداد البيانات التي تم فرزها ، ابدأ بتحديد إحدى طرق الترتيب لتحديد كيفية ترتيب النتائج:

طريقة إستعمال
orderByChild() ترتيب النتائج حسب قيمة مفتاح فرعي محدد أو مسار فرعي متداخل.
orderByKey() ترتيب النتائج عن طريق المفاتيح الفرعية.
orderByValue() ترتيب النتائج حسب القيم الفرعية.

يمكنك استخدام طريقة طلب واحدة فقط في كل مرة. يؤدي استدعاء طريقة ترتيب حسب عدة مرات في نفس الاستعلام إلى حدوث خطأ.

يوضح المثال التالي كيف يمكنك استرداد قائمة بأهم مشاركات المستخدم مرتبة حسب عدد النجوم:

Web modular API

import { getDatabase, ref, query, orderByChild } from "firebase/database";
import { getAuth } from "firebase/auth";

const db = getDatabase();
const auth = getAuth();

const myUserId = auth.currentUser.uid;
const topUserPostsRef = query(ref(db, 'user-posts/' + myUserId), orderByChild('starCount'));

Web namespaced API

var myUserId = firebase.auth().currentUser.uid;
var topUserPostsRef = firebase.database().ref('user-posts/' + myUserId).orderByChild('starCount');

يحدد هذا الاستعلام أنه عند دمجه مع مستمع فرعي يقوم بمزامنة العميل مع مشاركات المستخدم من المسار في قاعدة البيانات بناءً على معرف المستخدم الخاص به ، مرتبة حسب عدد النجوم التي تلقتها كل مشاركة. تسمى تقنية استخدام المعرفات كمفاتيح فهرسة توزيع البيانات ، ويمكنك قراءة المزيد عنها في هيكل قاعدة البيانات الخاصة بك .

يحدّد استدعاء الأسلوب orderByChild() المفتاح الفرعي لترتيب النتائج حسب. في هذه الحالة ، يتم فرز المشاركات حسب قيمة العنصر الفرعي "starCount" الخاص بها. يمكن أيضًا ترتيب الاستعلامات بواسطة العناصر الأبناء المتداخلة ، في حال كان لديك بيانات تبدو كالتالي:

"posts": {
  "ts-functions": {
    "metrics": {
      "views" : 1200000,
      "likes" : 251000,
      "shares": 1200,
    },
    "title" : "Why you should use TypeScript for writing Cloud Functions",
    "author": "Doug",
  },
  "android-arch-3": {
    "metrics": {
      "views" : 900000,
      "likes" : 117000,
      "shares": 144,
    },
    "title" : "Using Android Architecture Components with Firebase Realtime Database (Part 3)",
    "author": "Doug",
  }
},

في هذه الحالة ، يمكننا ترتيب عناصر قائمتنا حسب القيم المتداخلة تحت مفتاح metrics عن طريق تحديد المسار النسبي للطفل المتداخل في استدعاء orderByChild() الخاص بنا.

Web modular API

import { getDatabase, ref, query, orderByChild } from "firebase/database";

const db = getDatabase();
const mostViewedPosts = query(ref(db, 'posts'), orderByChild('metrics/views'));

Web namespaced API

var mostViewedPosts = firebase.database().ref('posts').orderByChild('metrics/views');

لمزيد من المعلومات حول كيفية ترتيب أنواع البيانات الأخرى ، راجع كيفية ترتيب بيانات الاستعلام .

تصفية البيانات

لتصفية البيانات ، يمكنك دمج أي من أساليب الحد أو النطاق مع طريقة الترتيب حسب عند إنشاء استعلام.

طريقة إستعمال
limitToFirst() يضبط الحد الأقصى لعدد العناصر المراد إرجاعها من بداية قائمة النتائج المرتبة.
limitToLast() يضبط الحد الأقصى لعدد العناصر المراد إرجاعها من نهاية قائمة النتائج المرتبة.
startAt() إرجاع العناصر الأكبر من أو تساوي المفتاح أو القيمة المحددة ، اعتمادًا على طريقة الترتيب حسب المختار.
startAfter() إرجاع العناصر الأكبر من المفتاح أو القيمة المحددة بناءً على طريقة الترتيب التي تم اختيارها.
endAt() إرجاع العناصر التي تقل عن أو تساوي المفتاح أو القيمة المحددة ، بناءً على طريقة الترتيب التي تم اختيارها.
endBefore() إرجاع العناصر الأقل من المفتاح أو القيمة المحددة بناءً على طريقة الترتيب المختارة.
equalTo() إرجاع العناصر التي تساوي المفتاح أو القيمة المحددة ، اعتمادًا على طريقة الترتيب التي تم اختيارها.

على عكس طرق الترتيب حسب ، يمكنك الجمع بين عدة وظائف حد أو نطاق. على سبيل المثال ، يمكنك دمج أساليب startAt() و endAt() لقصر النتائج على نطاق محدد من القيم.

حدد عدد النتائج

يمكنك استخدام أساليب limitToFirst() و limitToLast() لتعيين الحد الأقصى لعدد الأطفال المراد مزامنتهم لحدث معين. على سبيل المثال ، إذا كنت تستخدم limitToFirst() لتعيين حد 100 ، فإنك تتلقى في البداية ما يصل إلى 100 حدث child_added فقط. إذا كان لديك أقل من 100 عنصر مخزّن في قاعدة بيانات Firebase ، فسيتم تفعيل حدث child_added لكل عنصر.

عندما تتغير العناصر ، تتلقى أحداث child_added للعناصر التي تدخل الاستعلام والأحداث child_removed للعناصر التي تسربت منه بحيث يظل العدد الإجمالي عند 100.

يوضح المثال التالي كيف يعرّف مثال تطبيق التدوين استعلامًا لاسترداد قائمة بأحدث 100 منشور بواسطة جميع المستخدمين:

Web modular API

import { getDatabase, ref, query, limitToLast } from "firebase/database";

const db = getDatabase();
const recentPostsRef = query(ref(db, 'posts'), limitToLast(100));

Web namespaced API

var recentPostsRef = firebase.database().ref('posts').limitToLast(100);

يعرّف هذا المثال استعلامًا فقط ، لمزامنة البيانات فعليًا ، يجب أن يكون لها مستمع مرفق.

تصفية حسب المفتاح أو القيمة

يمكنك استخدام startAt() و startAfter() و endAt() و endBefore() و equalTo() لاختيار نقاط البداية والنهاية والتكافؤ التعسفية للاستعلامات. يمكن أن يكون هذا مفيدًا في ترقيم البيانات أو البحث عن عناصر لها قيمة محددة.

كيف يتم ترتيب البيانات الاستعلام

يشرح هذا القسم كيفية فرز البيانات حسب كل طريقة من طرق الترتيب في فئة Query .

orderByChild

عند استخدام orderByChild() ، يتم ترتيب البيانات التي تحتوي على المفتاح الفرعي المحدد على النحو التالي:

  1. الأطفال الذين لديهم قيمة null للمفتاح الفرعي المحدد يأتون أولاً.
  2. يأتي بعد ذلك الأطفال الذين لديهم قيمة false للمفتاح الفرعي المحدد. إذا كان هناك العديد من الأطفال الذين لديهم قيمة false ، فسيتم فرزهم حسب المعجم حسب المفتاح.
  3. يأتي بعد ذلك الأطفال الذين لديهم قيمة true للمفتاح الفرعي المحدد. إذا كان للعديد من الأطفال قيمة true ، فسيتم فرزهم حسب المعجم حسب المفتاح.
  4. يأتي الأطفال ذوو القيمة الرقمية بعد ذلك ، ويتم فرزهم بترتيب تصاعدي. إذا كان لدى العديد من الأطفال نفس القيمة العددية للعقدة الفرعية المحددة ، فسيتم فرزهم حسب المفتاح.
  5. تأتي السلاسل بعد الأرقام ويتم ترتيبها حسب المعجم بترتيب تصاعدي. إذا كان لدى العديد من الأطفال نفس القيمة للعقدة الفرعية المحددة ، فسيتم ترتيبهم حسب المعجم حسب المفتاح.
  6. تأتي الكائنات أخيرًا ويتم ترتيبها حسب المعجم حسب المفتاح بترتيب تصاعدي.

orderByKey

عند استخدام orderByKey() لفرز بياناتك ، يتم إرجاع البيانات بترتيب تصاعدي حسب المفتاح.

  1. الأطفال الذين لديهم مفتاح يمكن تحليله كعدد صحيح 32 بت يأتون أولاً ، ويتم فرزهم بترتيب تصاعدي.
  2. يأتي بعد ذلك الأطفال الذين لديهم قيمة سلسلة كمفتاح لهم ، ويتم فرزهم حسب المعجم بترتيب تصاعدي.

orderByValue

عند استخدام orderByValue() ، يتم ترتيب الأطفال حسب قيمتها. معايير الترتيب هي نفسها في orderByChild() ، باستثناء قيمة العقدة المستخدمة بدلاً من قيمة المفتاح الفرعي المحدد.

افصل المستمعين

تتم إزالة عمليات الاسترجاعات عن طريق استدعاء طريقة off() في مرجع قاعدة بيانات Firebase.

يمكنك إزالة مستمع واحد عن طريق تمريره كمعامل إلى off() . يؤدي استدعاء off() على الموقع بدون وسيطات إلى إزالة جميع المستمعين في ذلك الموقع.

لا يؤدي استدعاء off() على المستمع الأصل إلى إزالة المستمعين المسجلين في العقد الفرعية الخاصة به تلقائيًا ؛ يجب أيضًا استدعاء off() على أي مستمعين أطفال لإزالة رد النداء.

الخطوات التالية