نمایش خریدهای کاربر با لیست پویا

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

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

در پایان این آموزش، هر کارت می‌تواند اطلاعات زیر را نشان دهد:

• نام و توضیحات محصول
• دائمی یا زمان‌دار بودن دسترسی
• تاریخ خرید به شمسی
• تاریخ انقضا به شمسی
• تعداد روز باقی‌مانده
• منبع خرید، مانند سرور، بازار یا مایکت

مهم

sys.user.buys فقط خریدها و دسترسی‌های فعال را نگه می‌دارد. خرید یا اشتراک منقضی‌شده در این فهرست نمایش داده نمی‌شود.

پیش‌نیازها

پیش از شروع، موارد زیر را آماده کنید:

1. حداقل یک آیتم خریدنی در اپ تعریف شده باشد.
2. تنظیمات سیستم پرداخت اپ کامل شده باشد.
3. برای دسترسی زمان‌دار، همگام‌سازی پرداخت با سرور فعال باشد.
4. با مفهوم متغیرهای سیستمی و صفحه الگوی لیست پویا آشنایی اولیه داشته باشید.

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

ساختار صفحاتی که می‌سازیم

برای این نمونه سه صفحه در نظر می‌گیریم:

خریدهای من
├── لیست پویا با منبع sys.user.buys
│   └── الگوی کارت خرید
└── الگوی اختیاری لیست خالی

صفحه «الگوی کارت خرید» به‌ازای هر عضو sys.user.buys یک بار ساخته می‌شود. داخل این صفحه، اطلاعات خرید جاری از sys.inPage.data قابل دسترسی است.

گام ۱: ساخت صفحه الگوی کارت خرید

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

ساختار پیشنهادی کارت:

گروه کارت خرید
├── نام محصول
├── توضیحات محصول
├── تاریخ خرید
├── برچسب «خرید دائمی»
└── گروه اطلاعات دسترسی زمان‌دار
    ├── تاریخ انقضا
    └── روزهای باقی‌مانده

گام ۲: نمایش نام و توضیحات محصول

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

برای نمایش نام محصول:

1. یک ویجت «نمایشگر متغیر» اضافه کنید.
2. در «نام متغیر» مقدار زیر را قرار دهید:

sys.inPage.data.name

برای نمایش توضیحات، یک نمایشگر متغیر دیگر با مسیر زیر اضافه کنید:

sys.inPage.data.description

مسیرهای پرکاربرد در الگوی کارت:

اطلاعات	مسیر متغیر
نام محصول	sys.inPage.data.name
توضیحات	sys.inPage.data.description
کد محصول	sys.inPage.data.code
شناسه محصول	sys.inPage.data.itemId
منبع دسترسی	sys.inPage.data.source
شماره ردیف، از صفر	sys.inPage.data._index

هشدار

داخل صفحه الگوی کارت از مسیرهایی مانند sys.user.buys[0].name استفاده نکنید. این مسیر همیشه اولین خرید را می‌خواند. مسیر صحیح برای آیتم جاری sys.inPage.data.name است.

گام ۳: نمایش تاریخ خرید

برای نمایش تاریخ شمسی خرید:

1. یک ویجت متن ثابت با عنوان «تاریخ خرید» قرار دهید.
2. کنار یا زیر آن یک نمایشگر متغیر اضافه کنید.
3. نام متغیر را روی مقدار زیر بگذارید:

sys.inPage.data.purchasedAtJalali

نمونه خروجی:

1405/05/05 13:50

اگر به تاریخ استاندارد ISO-8601 نیاز دارید، از مسیر زیر استفاده کنید:

sys.inPage.data.purchasedAt

تاریخ خرید ممکن است تا پیش از دریافت اطلاعات معتبر از سرور یا مارکت null باشد. اگر نمایش تاریخ برای طراحی شما ضروری نیست، می‌توانید این ردیف را حذف کنید.

گام ۴: ساخت برچسب خرید دائمی

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

برای اینکه این گروه فقط برای خریدهای دائمی دیده شود:

1. تنظیمات شرط نمایش گروه را باز کنید.
2. شرط «مقدار متغیر» را انتخاب کنید.
3. نام متغیر را روی مقدار زیر قرار دهید:

sys.inPage.data.isPermanent

4. مقدار مورد انتظار را true قرار دهید.

می‌توانید متن گروه را به‌شکل زیر طراحی کنید:

دسترسی دائمی

برای خرید دائمی، فیلدهای expiresAtJalali و remainingDays برابر null هستند؛ بنابراین بهتر است آن‌ها را در این گروه نمایش ندهید.

گام ۵: نمایش اطلاعات دسترسی زمان‌دار

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

شرط نمایش گروه را به‌صورت زیر تنظیم کنید:

نام متغیر: sys.inPage.data.isSubscription
مقدار مورد انتظار: true

داخل این گروه دو نمایشگر متغیر اضافه کنید.

تاریخ انقضای شمسی:

sys.inPage.data.expiresAtJalali

تعداد روز باقی‌مانده:

sys.inPage.data.remainingDays

چیدمان پیشنهادی:

تاریخ انقضا: 1405/05/09 10:20
روزهای باقی‌مانده: 4

remainingDays رو به بالا گرد می‌شود؛ بنابراین اگر کمتر از یک روز باقی مانده باشد، مقدار آن 1 است. مقدار زمان باقی‌مانده هنگام اجرای اپ به‌روزرسانی می‌شود و پس از انقضا، کارت از لیست حذف خواهد شد.

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

sys.inPage.data.remainingSeconds

گام ۶: ساخت صفحه اصلی «خریدهای من»

1. یک صفحه جدید با نام «خریدهای من» بسازید.
2. یک عنوان مانند «خریدها و اشتراک‌های فعال من» در بالای صفحه قرار دهید.
3. ویجت «لیست پویا» را به صفحه اضافه کنید.
4. در تنظیمات لیست، نوع منبع داده را روی متغیر بگذارید.
5. در فیلد «نام متغیر» مقدار زیر را وارد کنید:

sys.user.buys

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

تنظیمات اصلی این مرحله:

تنظیم	مقدار
نوع منبع	متغیر
نام متغیر	sys.user.buys
الگوی صفحه برای آیتم‌ها	کارت خرید فعال
کلید یکتای آیتم	itemId
چیدمان پیشنهادی	عمودی

یادداشت

برای sys.user.buys نیازی به فعال‌کردن صفحه‌بندی سرور نیست. تعداد دسترسی‌های فعال معمولاً کم است و کل آرایه در حافظه اپ قرار دارد.

گام ۷: نمایش تعداد خریدهای فعال

برای نمایش تعداد خریدها، بالای لیست یک نمایشگر متغیر اضافه کنید و نام متغیر را روی مقدار زیر قرار دهید:

sys.user.buys._length

برای مثال می‌توانید کنار آن متن ثابت «تعداد دسترسی‌های فعال» قرار دهید.

گام ۸: طراحی حالت خالی

زمانی که خرید فعالی وجود ندارد، sys.user.buys برابر [] است. برای اینکه کاربر با صفحه خالی روبه‌رو نشود:

1. یک صفحه جدید با نام «خرید فعالی وجود ندارد» بسازید.
2. داخل آن یک آیکون، متن راهنما و در صورت نیاز دکمه رفتن به صفحه محصولات قرار دهید.
3. متن پیشنهادی:

در حال حاضر خرید یا اشتراک فعالی ندارید.

4. در تنظیمات لیست پویا، این صفحه را در گزینه «الگوی صفحه برای لیست خالی» انتخاب کنید.

اگر صفحه جداگانه نمی‌خواهید، مقدار «متن خالی بودن» را تنظیم کنید.

گام ۹: ساخت دو لیست جداگانه

اگر می‌خواهید خریدهای دائمی و دسترسی‌های زمان‌دار در دو بخش جدا نمایش داده شوند، دو ویجت لیست پویا بسازید. منبع هر دو ویجت همچنان sys.user.buys است.

لیست خریدهای دائمی:

تنظیم	مقدار
مسیر فیلتر	isPermanent
مقدار فیلتر	true

لیست دسترسی‌های زمان‌دار:

تنظیم	مقدار
مسیر فیلتر	isSubscription
مقدار فیلتر	true

برای هر لیست می‌توانید عنوان و الگوی خالی متفاوتی انتخاب کنید؛ مثلاً «خریدهای دائمی» و «اشتراک‌های فعال».

گام ۱۰: آزمایش با داده نمونه

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

[
  {
    "itemId": 12,
    "code": "remove_ads",
    "name": "حذف تبلیغات",
    "description": "حذف دائمی تبلیغات برنامه",
    "source": "bazaar",
    "isActive": true,
    "isSubscription": false,
    "isPermanent": true,
    "purchasedAtJalali": "1405/05/05 13:50",
    "expiresAtJalali": null,
    "remainingDays": null
  },
  {
    "itemId": 18,
    "code": "gold_30_days",
    "name": "دسترسی طلایی ۳۰ روزه",
    "description": "دسترسی به تمام محتوای طلایی",
    "source": "server",
    "isActive": true,
    "isSubscription": true,
    "isPermanent": false,
    "purchasedAtJalali": "1405/04/10 10:20",
    "expiresAtJalali": "1405/05/09 10:20",
    "remainingDays": 4
  }
]

پس از اطمینان از طراحی، نوع منبع را دوباره روی «متغیر» و نام آن را روی sys.user.buys قرار دهید.

گام ۱۱: آزمایش در اپ واقعی

برای اطمینان از عملکرد درست، حالت‌های زیر را بررسی کنید:

سناریو	نتیجه مورد انتظار
کاربر خرید فعالی ندارد	الگوی لیست خالی نمایش داده شود
خرید مستقیم مارکت بدون همگام‌سازی	کارت دائمی بدون تاریخ انقضا نمایش داده شود
خرید دائمی ثبت‌شده در سرور	کارت دائمی نمایش داده شود
دسترسی زمان‌دار فعال	تاریخ انقضا و روزهای باقی‌مانده نمایش داده شوند
دسترسی منقضی شود	آیتم از لیست حذف شود
کاربر از حساب سروری خارج شود	خریدهای وابسته به آن حساب از لیست حذف شوند
کاربر دوباره وارد شود	خریدهای فعال حساب دوباره دریافت و نمایش داده شوند

پرداخت مارکتی را روی همان مارکتی آزمایش کنید که خروجی برای آن ساخته شده است. موجودی خرید بازار و مایکت معمولاً در پیش‌نمایش یا خروجی غیرمارکتی قابل بررسی نیست.

خطاهای رایج

لیست همیشه خالی است

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

همه کارت‌ها اطلاعات اولین خرید را نشان می‌دهند

در صفحه الگوی آیتم از sys.user.buys[0] استفاده کرده‌اید. مسیرهای الگو باید با sys.inPage.data شروع شوند:

sys.inPage.data.name
sys.inPage.data.remainingDays

برای خرید دائمی تاریخ انقضا خالی است

این رفتار صحیح است. برای خرید دائمی، این مقادیر null هستند:

sys.inPage.data.expiresAt
sys.inPage.data.expiresAtJalali
sys.inPage.data.remainingSeconds
sys.inPage.data.remainingDays

اطلاعات انقضا را داخل گروهی قرار دهید که فقط با شرط isSubscription == true نمایش داده می‌شود.

اشتراک منقضی‌شده نمایش داده نمی‌شود

این متغیر فقط دسترسی‌های فعال را نمایش می‌دهد و برای تاریخچه خرید طراحی نشده است. حذف اشتراک منقضی‌شده از لیست رفتار مورد انتظار است.

اشتراک زمان‌دار در حالت مارکت مستقیم ساخته نمی‌شود

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

نتیجه نهایی

اکنون صفحه‌ای دارید که بدون درخواست API دستی، خریدها و اشتراک‌های فعال را نمایش می‌دهد. منبع لیست sys.user.buys است و هر کارت داده آیتم جاری را از sys.inPage.data دریافت می‌کند.

برای جزئیات کامل همه فیلدها، صفحه متغیرهای سیستمی را ببینید. برای تنظیمات پیشرفته چیدمان، فیلتر، حالت خالی و تعامل با آیتم‌ها نیز به راهنمای ویجت لیست پویا مراجعه کنید.