ویجت لیست پویا

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

تنظیمات ویجت لیست پویا در پنل اپ‌ادیتور.

آموزش عملی

برای یادگیری این ویجت در یک سناریوی واقعی، راهنمای گام‌به‌گام نمایش خریدهای کاربر با لیست پویا را ببینید. در این آموزش، اتصال sys.user.buys به لیست، ساخت الگوی کارت، نمایش تاریخ انقضا و تفکیک خرید دائمی از دسترسی زمان‌دار توضیح داده شده است.

روند کلی ساخت لیست

1. یک صفحه برای قالب آیتم بسازید؛ مثلاً کارت محصول شامل تصویر، عنوان و قیمت.
2. در صفحه اصلی، ویجت «لیست پویا» را اضافه کنید.
3. منبع داده را مشخص کنید.
4. صفحه ساخته‌شده را در گزینه «الگوی صفحه برای آیتم‌ها» انتخاب کنید.
5. در ویجت‌های «الگوی صفحه برای آیتم‌ها»، فیلدهای آیتم را با متغیرهای sys.inPage.data نمایش دهید.
6. چیدمان، بارگذاری تدریجی و حالت‌های خالی یا خطا را تنظیم کنید.

ساختار داده

مقدار ورودی لیست باید یک آرایه باشد. معمولاً هر عضو آرایه یک آبجکت است:

[
  {
    "id": 101,
    "title": "محصول اول",
    "price": 120000,
    "image": "https://example.com/images/101.jpg",
    "category": { "title": "کتاب" }
  },
  {
    "id": 102,
    "title": "محصول دوم",
    "price": 89000,
    "image": "https://example.com/images/102.jpg",
    "category": { "title": "آموزش" }
  }
]

اگر مقدار ورودی آرایه نباشد، لیست آن را داده خالی در نظر می‌گیرد.

دسترسی به داده در الگوی صفحه آیتم‌ها

داده آیتم جاری در الگوی صفحه آیتم‌ها از مسیر sys.inPage.data قابل دسترسی است:

مقدار موردنیاز	متغیر
کل آیتم	sys.inPage.data
عنوان	sys.inPage.data.title
قیمت	sys.inPage.data.price
عنوان دسته‌بندی تودرتو	sys.inPage.data.category.title
اولین عضو یک آرایه	sys.inPage.data.images.0.url یا sys.inPage.data.images[0].url
شماره آیتم، با شروع از صفر	sys.inPage.data._index

این متغیرها را می‌توانید در متن، تصویر، شرط‌ها و عملکردهای الگوی صفحه آیتم‌ها استفاده کنید.

نکته

اگر با لمس آیتم یک صفحه مقصد باز شود، داده همان آیتم به صفحه مقصد نیز ارسال می‌شود و در آن صفحه هم از طریق sys.inPage.data... قابل خواندن است.

منبع داده

آرایه ثابت (JSON)

برای داده‌ای که مستقیماً در تنظیمات ویجت نوشته می‌شود. مقدار «داده JSON» باید یک آرایه معتبر باشد. این روش برای منوهای کوچک، نمونه‌سازی و داده‌های کم‌تغییر مناسب است.

متغیر

در «نام متغیر»، متغیری را انتخاب کنید که مقدار آن آرایه‌ای از آبجکت‌ها است. هر آبجکت به یک آیتم لیست تبدیل می‌شود. لیست تغییرات همان متغیر را دنبال می‌کند؛ با مقداردهی دوباره متغیر، داده‌های لیست نیز بدون بازکردن مجدد صفحه بارگذاری می‌شوند.

آدرس URL

این حالت داده را از API دریافت می‌کند و تنظیمات زیر را دارد:

• آدرس URL: نشانی کامل API.
• متد درخواست: GET یا POST.
• کلید آرایه در JSON: مسیر آرایه در پاسخ، مانند data.items.
• نوع محتوای POST: یکی از Form URL Encoded یا JSON.
• Query Params: آبجکت JSON پارامترهای Query.
• بدنه درخواست: آبجکت JSON داده‌های بدنه درخواست.
• هدرها: آبجکت JSON هدرهایی مانند Authorization.
• مهلت درخواست: حداکثر زمان انتظار بر حسب ثانیه؛ مقدار پیش‌فرض ۳۰ است.
• تعداد تلاش مجدد: تعداد تکرار درخواست ناموفق؛ مقدار پیش‌فرض صفر است.

نمونه تنظیم Query و Header:

// Query Params
{
  "category": 12,
  "status": "publish"
}

// Headers
{
  "Authorization": "Bearer YOUR_TOKEN",
  "Accept": "application/json"
}

پاسخ می‌تواند مستقیماً آرایه باشد:

[
  { "id": 1, "title": "آیتم اول" },
  { "id": 2, "title": "آیتم دوم" }
]

یا آرایه داخل یک آبجکت قرار بگیرد:

{
  "success": true,
  "data": {
    "items": [
      { "id": 1, "title": "آیتم اول" },
      { "id": 2, "title": "آیتم دوم" }
    ]
  }
}

برای پاسخ بالا، «کلید آرایه در JSON» را data.items قرار دهید. اگر این فیلد خالی باشد، لیست به‌صورت خودکار کلیدهای مستقیم data، items، results و list را بررسی می‌کند.

هشدار

مقادیر Query Params، بدنه و هدرها باید آبجکت JSON باشند؛ آرایه یا JSON نامعتبر در پنل با خطا مشخص می‌شود.

خودکار

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

مسیرهای تودرتو مانند data.children نیز قابل استفاده‌اند. اگر «مسیر فیلد» را خالی بگذارید، داده‌ای که از صفحه والد دریافت می‌شود باید خودش آرایه باشد.

پردازش داده

پردازش‌های زیر پیش از نمایش روی داده اعمال می‌شوند:

• مسیر فیلتر: مسیر فیلدی مانند status یا category.id.
• مقدار فیلتر: فقط آیتم‌هایی باقی می‌مانند که مقدار فیلدشان با این مقدار برابر باشد. اگر مقدار فیلتر خالی باشد، آیتم‌هایی نگه داشته می‌شوند که آن فیلد را دارند.
• کلید حذف تکراری: آیتم‌های تکراری بر اساس مسیری مانند id حذف می‌شوند.
• مسیر مرتب‌سازی: مسیر فیلد مرتب‌سازی، مانند created_at یا price.
• مرتب‌سازی نزولی: ترتیب مرتب‌سازی را معکوس می‌کند.
• حداکثر تعداد: خروجی نهایی را به تعداد تعیین‌شده محدود می‌کند.

ترتیب اجرای پردازش‌ها «فیلتر، حذف تکراری، مرتب‌سازی و سپس محدودکردن تعداد» است.

قالب‌ها و وضعیت نمایش

الگوی صفحه برای آیتم‌ها

این الگوی صفحه برای هر عضو آرایه یک بار ساخته می‌شود. اگر انتخاب نشود، مقدار خام هر آیتم به‌صورت متن نمایش داده خواهد شد. در اجزای الگو، فیلدها را با مسیرهایی مانند sys.inPage.data.title بخوانید. برای لیست‌های طولانی، الگوی آیتم را سبک نگه دارید و از تصاویر بسیار بزرگ یا ویجت‌های سنگین غیرضروری پرهیز کنید.

الگوی صفحه برای جداکننده

بین هر دو آیتم متوالی نمایش داده می‌شود. در الگوی جداکننده این داده‌ها در دسترس‌اند:

• sys.inPage.data.previousItem: آیتم قبلی
• sys.inPage.data.nextItem: آیتم بعدی
• sys.inPage.data.index: شماره جداکننده
• sys.inPage.data.isFirst: آیا اولین جداکننده است
• sys.inPage.data.isLast: آیا آخرین جداکننده است

اگر الگویی انتخاب نشود، می‌توانید از «متن جداکننده» استفاده کنید. جداکننده فقط در چیدمان عمودی، افقی و چینش آزاد نمایش داده می‌شود.

حالت خالی و خطا

• الگوی صفحه برای لیست خالی: هنگام نبود داده، به‌جای متن پیش‌فرض نمایش داده می‌شود.
• متن خالی بودن: وقتی الگویی برای لیست خالی تعیین نشده باشد استفاده می‌شود.
• الگوی صفحه برای خطا: در خطای اتصال، timeout، پاسخ HTTP یا JSON نامعتبر نمایش داده می‌شود.
• متن خطا: متن جایگزین در صورت انتخاب‌نکردن الگوی خطا.
• عنوان تلاش مجدد: متن دکمه‌ای که درخواست را دوباره اجرا می‌کند.

اگر هنگام «بارگذاری بیشتر» خطا رخ دهد، آیتم‌های قبلی حفظ می‌شوند و خطا در ادامه لیست نمایش داده می‌شود.

سربرگ و پاورقی

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

الگوهای وضعیت، سربرگ و پاورقی می‌توانند از اطلاعات وضعیت لیست در sys.inPage.data استفاده کنند؛ از جمله state، count، visibleCount، hasMore، serverPage، errorType، errorMessage و statusCode.

چیدمان لیست

بخش «چیدمان لیست» همان امکانات چیدمان گروه را در اختیار لیست می‌گذارد:

• عمودی: آیتم‌ها زیر هم؛ مناسب خبر و محصول.
• افقی: آیتم‌ها کنار هم؛ مناسب کارت‌های افقی.
• جدول: نمایش شبکه‌ای با تنظیمات ستون و فاصله.
• چینش آزاد: انتقال خودکار آیتم‌ها به خط بعد؛ مناسب تگ‌ها و کارت‌هایی با اندازه متفاوت.
• لایه‌ای: قرارگرفتن آیتم‌ها روی هم.
• اسلاید: نمایش آیتم‌ها به‌شکل صفحات قابل ورق‌زدن.

تراز، فاصله و اسکرول

این تنظیمات به‌دلیل وابستگی مستقیم، در یک بخش مشترک قرار دارند و گزینه‌های قابل استفاده با توجه به نوع چیدمان نمایش داده می‌شوند:

• تراز آیتم‌ها: محل قرارگیری آیتم‌ها در فضای لیست.
• توزیع فضای خالی: بدون توزیع، فقط بین آیتم‌ها، اطراف آیتم‌ها یا توزیع مساوی.
• کشیدن آیتم‌ها در عرض لیست: آیتم‌ها را در محور مخالف جهت حرکت لیست گسترش می‌دهد.
• فعال‌سازی اسکرول لیست: امکان حرکت میان آیتم‌ها را در جهت چیدمان فعال می‌کند.
• نمایش اسکرول‌بار: همراه با تنظیم رنگ و نمایش دائمی آن.
• حرکت هوشمند اسکرول: رفتار خودکار اسکرول را فعال می‌کند.
• حفظ موقعیت اسکرول: پس از بازسازی لیست، موقعیت قبلی را نگه می‌دارد.
• بارگذاری همه آیتم‌ها پیش از نمایش: برای چیدمان عمودی و افقی در دسترس است.

یادداشت

با فعال‌شدن اسکرول، فضای اضافه برای حرکت آیتم‌ها استفاده می‌شود؛ بنابراین «توزیع فضای خالی» غیرفعال خواهد شد.

یادداشت

جداکننده، دکمه «بیشتر» و متن پایان لیست در همه چیدمان‌ها نمایش داده نمی‌شوند. دکمه بیشتر و متن پایان برای عمودی، افقی، جدول و چینش آزاد پشتیبانی می‌شوند؛ جداکننده برای عمودی، افقی و چینش آزاد است.

بارگذاری و تازه‌سازی

بارگذاری تدریجی و صفحه‌بندی

با فعال‌کردن «بارگذاری تدریجی»، فقط بخشی از آیتم‌ها در شروع نمایش داده می‌شود.

• تعداد در هر بار: اندازه هر بخش؛ پیش‌فرض ۲۰.
• شیوه بارگذاری بیشتر: خودکار با اسکرول، دکمه بیشتر یا هر دو.
• فاصله تا انتهای لیست: فاصله‌ای که با رسیدن به آن، بارگذاری مرحله بعد آغاز می‌شود؛ پیش‌فرض ۵۰۰ پیکسل.
• الگوی صفحه به‌جای دکمه بیشتر: صفحه سفارشی که هنگام دریافت مرحله بعد جایگزین کنترل پیش‌فرض بارگذاری بیشتر می‌شود.
• عنوان دکمه بیشتر: متن دکمه در حالت «دکمه بیشتر» یا «اسکرول + دکمه».
• متن پایان لیست: وقتی داده دیگری باقی نمانده است نمایش داده می‌شود.

«فاصله تا انتهای لیست» در حالت «دکمه بیشتر» کاربرد ندارد و «عنوان دکمه بیشتر» نیز در حالت «خودکار با اسکرول» غیرفعال است.

برای منبع ثابت، متغیر و خودکار، همه داده ابتدا در حافظه دریافت می‌شود و بارگذاری تدریجی تعداد آیتم‌های قابل مشاهده را مرحله‌ای افزایش می‌دهد. برای URL دارای صفحه‌بندی سرور، هر مرحله درخواست جدیدی به API می‌فرستد.

بدون صفحه‌بندی سرور

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

Page / Page size

پارامتر شماره صفحه و تعداد در هر صفحه ارسال می‌شود. نام‌های پیش‌فرض page و per_page هستند و «صفحه شروع» به‌طور پیش‌فرض ۱ است.

Offset / Limit

پارامتر Offset و تعداد ارسال می‌شود. Offset بر اساس صفحه شروع و تعداد هر بار محاسبه می‌گردد. نام‌های پیش‌فرض offset و per_page هستند.

Cursor

برای APIهایی که به‌جای شماره صفحه، Cursor بعدی برمی‌گردانند. نام پارامتر پیش‌فرض cursor است و باید «مسیر Cursor بعدی» مانند meta.next_cursor را تنظیم کنید.

برای هر سه مدل می‌توانید این مسیرها را تعیین کنید:

• مسیر Has More: مقدار بولی ادامه‌داشتن داده، مانند meta.has_more.
• مسیر تعداد کل: تعداد کل نتایج، مانند meta.total.
• مسیر Cursor بعدی: مخصوص صفحه‌بندی Cursor.

اگر Has More مشخص نشده باشد، در مدل Page و Offset دریافت تعداد کامل آیتم‌های هر صفحه به معنی احتمال وجود صفحه بعد است. در مدل Cursor، وجود Cursor بعدی ملاک ادامه است.

نکته

در صفحه‌بندی سرور، «کلید یکتای آیتم» را روی فیلدی مانند id تنظیم کنید. این کار هم کلید پایدار برای رندر ایجاد می‌کند و هم از اضافه‌شدن دوباره آیتم‌های تکراری در پاسخ صفحات بعد جلوگیری می‌کند.

تازه‌سازی و نمایش بارگذاری

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

تعامل با آیتم

با فعال‌کردن «باز کردن صفحه با کلیک روی آیتم» و انتخاب «صفحه مقصد»، لمس هر ردیف صفحه مقصد را باز می‌کند. داده همان ردیف به صفحه مقصد ارسال می‌شود؛ بنابراین جزئیات را با sys.inPage.data.title و سایر مسیرها نمایش دهید.

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

نمونه کامل API صفحه‌بندی‌شده

فرض کنید پاسخ API چنین است:

{
  "data": {
    "items": [
      { "id": 21, "title": "مطلب ۲۱" },
      { "id": 22, "title": "مطلب ۲۲" }
    ]
  },
  "meta": {
    "has_more": true,
    "total": 80
  }
}

تنظیمات پیشنهادی:

تنظیم	مقدار
کلید آرایه در JSON	data.items
نوع صفحه‌بندی	Page / Page size
نام پارامتر صفحه	page
نام پارامتر تعداد	per_page
مسیر Has More	meta.has_more
مسیر تعداد کل	meta.total
بارگذاری تدریجی	فعال
کلید یکتای آیتم	id

خطاهای رایج

• واردکردن آبجکت به‌جای آرایه در داده ثابت یا متغیر.
• اشتباه‌بودن «کلید آرایه در JSON»؛ مسیرهای تودرتو را کامل بنویسید.
• نوشتن Query Params، Body یا Headers با JSON نامعتبر.
• انتخاب صفحه‌بندی سرور بدون فعال‌کردن «بارگذاری تدریجی»؛ صفحه‌بندی سرور تنها همراه بارگذاری تدریجی اجرا می‌شود.
• متفاوت‌بودن نام پارامترهای page، per_page، offset یا cursor با قرارداد API.
• انتخاب‌نکردن «الگوی صفحه برای آیتم‌ها» یا استفاده از نام فیلد اشتباه در sys.inPage.data.
• استفاده از الگوی صفحه سنگین در لیست‌های بزرگ.
• نداشتن ارتفاع یا اسکرول مناسب برای لیست طولانی.
• استفاده‌نکردن از کلید یکتا در APIهایی که بین صفحات داده تکراری برمی‌گردانند.

پیشنهادهای عملکردی

• پاسخ API را کوچک نگه دارید و تصاویر را با اندازه مناسب موبایل ارائه کنید.
• برای داده زیاد از صفحه‌بندی سرور و بارگذاری تدریجی استفاده کنید.
• برای هر حالت بارگذاری، خالی و خطا یک صفحه ساده و مشخص طراحی کنید.
• الگوی صفحه برای آیتم‌ها، صفحه مقصد و بارگذاری بیشتر را روی دستگاه واقعی آزمایش کنید.
• ابتدا با یک آرایه ثابت کوچک الگوی آیتم را تست کنید و پس از اطمینان، منبع را به متغیر یا URL تغییر دهید.