‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

کار کردن با فهرست‌های داده‌ها

دریافت مرجع پایگاه داده

برای خواندن یا نوشتن داده‌ها از پایگاه داده، به نمونه‌ای از DatabaseReference نیاز دارید:

DatabaseReference ref = FirebaseDatabase.instance.ref();

توجه: به‌طور پیش‌فرض، دسترسی خواندن و نوشتن به پایگاه داده شما محدود شده است تا فقط کاربران اصالت‌سنجی‌شده بتوانند داده‌ها را بخوانند یا بنویسند. برای شروع به کار بدون راه‌اندازی «اصالت‌سنجی Firebase»، می‌توانید قوانینتان را برای دسترسی عمومی پیکربندی کنید. این کار باعث می‌شود پایگاه داده شما برای همه، حتی افرادی که از برنامه شما استفاده نمی‌کنند، باز شود، بنابراین حتماً هنگام راه‌اندازی اصالت‌سنجی، پایگاه داده خود را دوباره محدود کنید.

خواندن و نوشتن فهرست‌ها

افزودن به فهرست داده‌ها

از روش push() برای افزودن داده به فهرست در برنامه‌های چندکاربره استفاده کنید. روش push() هربار که فرزند جدیدی به مرجع Firebase مشخص‌شده اضافه می‌شود، کلید منحصربه‌فردی تولید می‌کند. بااستفاده از این کلیدهای تولیدشده به‌طور خودکار برای هر عنصر جدید در فهرست، چندین کارخواه می‌توانند به‌طور هم‌زمان و بدون تداخل نوشتن، فرزندان را به همان مکان اضافه کنند. کلید منحصربه‌فردی که push() تولید می‌کند براساس مُهر زمان است، بنابراین موارد فهرست به‌طور خودکار به‌ترتیب زمانی مرتب می‌شوند.

می‌توانید از ارجاع به داده‌های جدید برگردانده‌شده توسط روش push() برای دریافت مقدار کلید تولیدشده خودکار فرزند یا تنظیم داده‌ها برای فرزند استفاده کنید. ویژگی .key مرجع push() حاوی کلید تولیدشده خودکار است.

می‌توانید از این کلیدهای تولیدشده به‌طور خودکار برای ساده کردن مسطح‌سازی ساختار داده‌هایتان استفاده کنید. برای اطلاعات بیشتر، مثال توزیع داده را ببینید.

برای مثال، می‌توان از push() برای افزودن پست جدید به فهرست پست‌ها در نرم‌افزار اجتماعی استفاده کرد:

DatabaseReference postListRef = FirebaseDatabase.instance.ref("posts");
DatabaseReference newPostRef = postListRef.push();
newPostRef.set({
  // ...
});

گوش دادن به رویدادهای فرزند

رویدادهای فرزند در پاسخ به عملیات خاصی که برای فرزندان یک گره اتفاق می‌افتد، راه‌اندازی می‌شوند، مانند اضافه شدن یک فرزند جدید ازطریق روش push() یا به‌روزرسانی یک فرزند ازطریق روش update().

رویداد	استفاده معمول
`onChildAdded`	فهرست موارد را بازیابی کند یا به موارد اضافه‌شده به فهرست موارد گوش دهد. این رویداد یک‌بار برای هر فرزند موجود راه‌اندازی می‌شود و سپس دوباره هر بار که فرزند جدیدی به مسیر مشخص‌شده اضافه می‌شود. شنونده یک عکس آنی حاوی داده‌های فرزند جدید را دریافت می‌کند.
`onChildChanged`	گوش دادن به تغییرات موارد موجود در فهرست. این رویداد هرزمان که گره فرعی اصلاح شود راه‌اندازی می‌شود. این شامل هرگونه تغییر در فرزندان گره فرزند می‌شود. عکس آنی ارسال‌شده به شنونده رویداد حاوی داده‌های به‌روزشده برای فرزند است.
`onChildRemoved`	به مواردی که از فهرست برداشته می‌شوند گوش دهید. این رویداد زمانی راه‌اندازی می‌شود که فرزند مستقیم برداشته شود.عکس آنی ارسال‌شده به بلوک فراخوانی برگشتی حاوی داده‌های فرزند برداشته‌شده است.
`onChildMoved`	به تغییرات ترتیب موارد در فهرست مرتب‌شده گوش دهید. رویدادهای onChildMoved همیشه پس‌از رویداد onChildChanged که باعث تغییر ترتیب مورد شده است (براساس روش به‌ترتیب کردن فعلی شما) رخ می‌دهند.

هرکدام از این‌ها باهم می‌توانند برای گوش دادن به تغییرات در گره خاصی در پایگاه داده مفید باشند. برای مثال، یک برنامه وبلاگ‌نویسی اجتماعی ممکن است از این روش‌ها با هم برای نظارت بر فعالیت در نظرات یک پست استفاده کند، همان‌طور که در زیر نشان داده شده است:

final commentsRef = FirebaseDatabase.instance.ref("post-comments/$postId");
commentsRef.onChildAdded.listen((event) {
  // A new comment has been added, so add it to the displayed list.
});
commentsRef.onChildChanged.listen((event) {
  // A comment has changed; use the key to determine if we are displaying this
  // comment and if so displayed the changed comment.
});
commentsRef.onChildRemoved.listen((event) {
  // A comment has been removed; use the key to determine if we are displaying
  // this comment and if so remove it.
});

گوش دادن به رویدادهای مقدار

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

Attaching a value listener to a list of data will return the entire list of data as a single snapshot which you can then loop over to access individual children.

حتی وقتی فقط یک مورد منطبق برای پُرسمان وجود دارد، عکس آنی همچنان به‌صورت فهرست است؛ فقط یک مورد دارد. برای دسترسی به مورد، باید روی نتیجه حلقه بزنید:

myTopPostsQuery.onValue.listen((event) {
  for (final child in event.snapshot.children) {
    // Handle the post.
  }
}, onError: (error) {
  // Error.
});

این الگو زمانی می‌تواند مفید باشد که می‌خواهید همه فرزندان یک فهرست را در یک عملیات واکشی کنید، به‌جای اینکه برای رویدادهای اضافه شدن فرزندان اضافی گوش دهید.

مرتب‌سازی و فیلتر کردن داده‌ها

می‌توانید از کلاس Query برای بازیابی داده‌های مرتب‌شده براساس کلید، مقدار، یا مقدار فرزند استفاده کنید. همچنین می‌توانید نتیجه مرتب‌شده را به تعداد خاصی از نتایج یا محدوده‌ای از کلیدها یا مقادیر فیلتر کنید.

مرتب کردن داده‌ها

برای بازیابی داده‌های مرتب‌شده، ابتدا یکی از روش‌های به‌ترتیب کردن را برای تعیین نحوه مرتب‌سازی نتایج مشخص کنید:

روش	کاربرد
`orderByChild()`	نتایج را براساس مقدار کلید فرزند مشخص‌شده یا مسیر فرزند تودرتو مرتب کنید.
`orderByKey()`	نتایج را براساس کلیدهای فرزند مرتب کنید.
`orderByValue()`	نتایج را براساس مقادیر فرزند مرتب کنید.

در هر زمان فقط می‌توانید از یک روش به‌ترتیب کردن استفاده کنید. فراخوانی روش به‌ترتیب کردن به‌دفعات در یک پُرسمان باعث ایجاد خطا می‌شود.

مثال زیر نشان می‌دهد که چگونه می‌توانید فهرستی از پست‌های برتر کاربر را که براساس تعداد ستاره‌هایشان مرتب شده‌اند بازیابی کنید:

final myUserId = FirebaseAuth.instance.currentUser?.uid;
final topUserPostsRef = FirebaseDatabase.instance
    .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() مرتب کنیم.

final mostViewedPosts =
    FirebaseDatabase.instance.ref('posts').orderByChild('metrics/views');

برای اطلاعات بیشتر درباره نحوه مرتب‌سازی انواع دیگر داده‌ها، نحوه مرتب‌سازی داده‌های پُرسمان را ببینید.

فیلتر کردن داده‌ها

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

روش	کاربرد
`limitToFirst()`	حداکثر تعداد مواردی را که باید از ابتدای فهرست مرتب‌شده نتایج برگردانده شود تنظیم می‌کند.
`limitToLast()`	حداکثر تعداد مواردی را که باید از انتهای فهرست مرتب‌شده نتایج برگردانده شود تنظیم می‌کند.
`startAt()`	موارد بزرگ‌تر یا مساوی با کلید یا مقدار مشخص‌شده را برمی‌گرداند، بسته به روش به‌ترتیب کردن انتخاب‌شده.
`startAfter()`	موارد بزرگ‌تر از کلید یا مقدار مشخص‌شده را بسته به روش به‌ترتیب کردن انتخاب‌شده برمی‌گرداند.
`endAt()`	موارد کوچک‌تر یا مساوی کلید یا مقدار مشخص‌شده را برمی‌گرداند، بسته به روش به‌ترتیب کردن انتخاب‌شده.
`endBefore()`	موارد کمتر از کلید یا مقدار مشخص‌شده را بسته به روش به‌ترتیب کردن انتخاب‌شده برمی‌گرداند.
`equalTo()`	موارد برابر با کلید یا مقدار مشخص‌شده را بسته به روش به‌ترتیب کردن انتخاب‌شده برمی‌گرداند.

برخلاف روش‌های به‌ترتیب کردن، می‌توانید چندین تابع محدوده یا حد را ترکیب کنید. برای مثال، می‌توانید روش‌های startAt() و endAt() را ترکیب کنید تا نتایج را به گستره مشخصی از مقادیر محدود کنید.

محدود کردن تعداد نتایج

می‌توانید از روش‌های limitToFirst() و limitToLast() برای تنظیم حداکثر تعداد فرزندان برای همگام‌سازی برای یک رویداد خاص استفاده کنید. برای مثال، اگر از limitToFirst() برای تنظیم حد ۱۰۰ استفاده کنید، در ابتدا فقط تا ۱۰۰ رویداد onChildAdded دریافت می‌کنید. اگر کمتر از ۱۰۰ مورد در پایگاه داده Firebase شما ذخیره شده باشد، یک رویداد onChildAdded برای هر مورد اجرا می‌شود.

با تغییر موارد، onChildAdded رویداد برای مواردی که وارد پُرسمان می‌شوند و onChildRemoved رویداد برای مواردی که از آن خارج می‌شوند دریافت می‌کنید تا تعداد کل روی ۱۰۰ باقی بماند.

مثال زیر نشان می‌دهد که چگونه برنامه وبلاگ‌نویسی نمونه، پُرسمانی را برای بازیابی فهرستی از ۱۰۰ پست اخیر همه کاربران تعریف می‌کند:

final recentPostsRef = FirebaseDatabase.instance.ref('posts').limitToLast(100);

این مثال فقط یک پُرسمان را تعریف می‌کند، برای همگام‌سازی واقعی داده‌ها باید شنونده پیوست‌شده داشته باشد.

فیلتر کردن براساس کلید یا مقدار

می‌توانید از startAt()،‏ startAfter()،‏ endAt()،‏ endBefore()، و equalTo() برای انتخاب نقاط شروع، پایان، و برابری دلخواه برای پرس‌وجوها استفاده کنید. این کار می‌تواند برای صفحه‌بندی داده‌ها یا پیدا کردن موارد دارای فرزند با مقدار خاص مفید باشد.

نحوه مرتب‌سازی داده‌های پُرسمان

این بخش توضیح می‌دهد که داده‌ها چگونه براساس هریک از روش‌های به‌ترتیب کردن در کلاس Query مرتب می‌شوند.

`orderByChild`

هنگام استفاده از orderByChild()، داده‌هایی که حاوی کلید فرزند مشخص‌شده هستند به‌صورت زیر مرتب می‌شوند:

فرزندان با مقدار null برای کلید فرزند مشخص‌شده اول می‌آیند.
فرزندان با مقدار false برای کلید فرزند مشخص‌شده در ردیف بعدی قرار می‌گیرند. اگر چند فرزند مقدار false داشته باشند، براساس کلید به‌ترتیب الفبایی مرتب می‌شوند.
فرزندان با مقدار true برای کلید فرزند مشخص‌شده در ردیف بعدی قرار می‌گیرند. اگر چند فرزند مقدار true داشته باشند، به‌ترتیب الفبایی براساس کلید مرتب می‌شوند.
فرزندان با مقدار عددی در ردیف بعدی قرار می‌گیرند و به‌ترتیب صعودی مرتب می‌شوند. اگر چندین فرزند مقدار عددی یکسانی برای گره فرزند مشخص‌شده داشته باشند، براساس کلید مرتب می‌شوند.
رشته‌ها بعداز اعداد می‌آیند و به‌ترتیب صعودی واژه‌نگاری مرتب می‌شوند. اگر چند فرزند مقدار یکسانی برای گره فرزند مشخص‌شده داشته باشند، آن‌ها به‌صورت واژه‌نامه‌ای براساس کلید مرتب می‌شوند.
اشیاء در آخر می‌آیند و به‌ترتیب صعودی براساس کلید مرتب می‌شوند.

`orderByKey`

هنگام استفاده از orderByKey() برای مرتب‌سازی داده‌ها، داده‌ها به‌ترتیب صعودی براساس کلید برگردانده می‌شوند.

فرزندان با کلیدی که می‌تواند به‌عنوان عدد صحیح ۳۲ بیتی تجزیه شود، ابتدا می‌آیند و به‌ترتیب صعودی مرتب می‌شوند.
فرزندان با مقدار رشته‌ای به‌عنوان کلیدشان در ردیف بعدی قرار می‌گیرند و به‌ترتیب صعودی واژه‌نامه‌ای مرتب می‌شوند.

`orderByValue`

هنگام استفاده از orderByValue()، فرزندان براساس مقدارشان مرتب می‌شوند. معیارهای ترتیب‌بندی همانند orderByChild() است، با این تفاوت که به‌جای مقدار کلید فرزند مشخص‌شده، از مقدار گره استفاده می‌شود.

جدا کردن شنونده‌ها

با فراخوانی روش off() در مرجع پایگاه داده Firebase، فراخوانی‌های برگشتی برداشته می‌شوند.

می‌توانید یک شنونده را با ارسال آن به‌عنوان پارامتر به off() حذف کنید. فراخوانی off() در مکان بدون آرگومان، همه شنوندگان را در آن مکان برمی‌دارد.

فراخوانی off() در شنونده والد به‌طور خودکار شنونده‌های ثبت‌شده در گره‌های فرزند آن را حذف نمی‌کند؛ off() باید در هر شنونده فرزند نیز فراخوانی شود تا فراخوان برگشتی حذف شود.