با لیست داده ها کار کنید

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

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

DatabaseReference ref = FirebaseDatabase.instance.ref();

خواندن و نوشتن لیست ها

به لیستی از داده ها اضافه کنید

از متد 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.
});

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

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

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

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

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

این یک پرس و جو را تعریف می کند که وقتی با یک شنونده کودک ترکیب می شود، مشتری را با پست های کاربر از مسیر موجود در پایگاه داده بر اساس شناسه کاربری آن ها، به ترتیب بر اساس تعداد ستاره هایی که هر پست دریافت کرده است، همگام می کند. این تکنیک استفاده از شناسه‌ها به‌عنوان کلیدهای فهرست، فن‌آوری داده‌ها نامیده می‌شود، می‌توانید اطلاعات بیشتری درباره آن در Structure Your Database بخوانید.

فراخوانی متد 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() برای تعیین حد 100 استفاده کنید، در ابتدا فقط تا 100 رویداد onChildAdded دریافت خواهید کرد. اگر کمتر از 100 مورد در پایگاه داده Firebase خود ذخیره کنید، یک رویداد onChildAdded برای هر مورد فعال می شود.

با تغییر موارد، رویدادهای onChildAdded را برای مواردی که وارد پرس و جو می‌شوند و رویدادهای onChildRemoved را برای مواردی که از آن حذف می‌شوند دریافت می‌کنید تا تعداد کل 100 باقی بماند.

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

final recentPostsRef = FirebaseDatabase.instance.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() همچنین باید در هر شنونده کودک فراخوانی شود تا پاسخ تماس را حذف کند.

مراحل بعدی