ویجت انتخاب‌گر گزینه‌ها (فرم)

ویجت «انتخاب‌گر گزینه‌ها» یک یا چند گروه از انتخاب‌ها را از یک متغیر JSON دریافت می‌کند. هر گروه می‌تواند به‌شکل چیپ متنی، رادیویی، کمبوباکس، رنگ یا تصویر، کارت یا یک صفحه کاملاً طراحی‌شده نمایش داده شود.

این ویجت برای فرم‌هایی مناسب است که گزینه‌ها پویا هستند یا چند گروه انتخاب به خروجی یکپارچه نیاز دارند؛ مانند انتخاب اندازه و رنگ، نوع بسته، ویژگی‌های یک سفارش یا پاسخ چند بخش مرتبط.

روند استفاده

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

ساختار داده منبع

مقدار منبع باید آرایه‌ای از گروه‌ها باشد. هر گروه یک کلید، عنوان و آرایه گزینه‌ها دارد:

[
  {
    "key": "size",
    "name": "اندازه",
    "terms": [
      {
        "name": "کوچک",
        "value": "small",
        "available": true,
        "selected": false,
        "description": "مناسب استفاده روزمره"
      },
      {
        "name": "بزرگ",
        "value": "large",
        "available": true,
        "selected": true
      }
    ]
  },
  {
    "key": "color",
    "name": "رنگ",
    "terms": [
      { "name": "قرمز", "value": "red", "color": "f44336" },
      { "name": "آبی", "value": "blue", "color": "2196f3" }
    ]
  }
]

اگر مقدار available برابر false باشد، گزینه به‌صورت غیرفعال نمایش داده می‌شود. مقدار selected: true نیز انتخاب اولیه آن گروه را مشخص می‌کند.

تنظیمات داده

• نام فیلد: نام داخلی انتخاب‌گر در اطلاعات فرم.
• برچسب کلی: عنوانی که بالای همه گروه‌ها نمایش داده می‌شود.
• متغیر منبع گروه‌ها: متغیر JSON حاوی آرایه گروه‌ها.
• فیلتر گروه‌ها: فهرست کلید یا عنوان گروه‌های قابل نمایش، با ویرگول از هم جدا؛ مانند color, size.

نگاشت فیلدهای منبع

ساختار پیش‌فرض از نام‌های زیر استفاده می‌کند:

مفهوم	نام پیش‌فرض
کلید گروه	key
عنوان گروه	name
فهرست گزینه‌ها	terms
عنوان گزینه	name
مقدار گزینه	value
قابل انتخاب بودن	available
منتخب بودن	selected
رنگ گزینه	color
تصویر گزینه	image
توضیح گزینه	description

اگر داده شما نام‌های دیگری دارد، در بخش «نگاشت فیلدهای منبع» مسیر متناظر هر فیلد را وارد کنید. مسیرهای تودرتو را می‌توانید با نقطه بنویسید؛ مانند meta.label.

نوع نمایش گزینه‌ها

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

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

چیدمان گزینه‌ها

• Wrap ـ انتقال به خط بعد: گزینه‌ها کنار هم قرار می‌گیرند و در صورت کمبود فضا به خط بعد می‌روند.
• افقی با اسکرول: گزینه‌ها در یک ردیف افقی قابل پیمایش نمایش داده می‌شوند.
• عمودی: گزینه‌ها زیر یکدیگر قرار می‌گیرند.
• شبکه‌ای: گزینه‌ها در تعداد ستون تعیین‌شده نمایش داده می‌شوند.

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

نمایش اختصاصی هر گروه

در بخش «نمایش اختصاصی گروه‌ها» می‌توانید تنظیمات عمومی را برای یک گروه تغییر دهید. برای هر ردیف، کلید گروه را وارد و نوع نمایش، چیدمان و صفحه‌های الگوی همان گروه را انتخاب کنید.

برای نمونه می‌توانید گروه color را به‌شکل رنگ یا تصویر و گروه size را به‌شکل چیپ متنی نمایش دهید. گروه‌هایی که تنظیم اختصاصی ندارند از تنظیمات عمومی ویجت استفاده می‌کنند.

طراحی ظاهر با صفحه الگو

سه نوع صفحه الگو در دسترس است:

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

در صفحه الگوی گزینه، اطلاعات گزینه جاری از مسیر sys.inPage.option قابل خواندن است:

مقدار	متغیر
عنوان گزینه	sys.inPage.option.label
مقدار واقعی	sys.inPage.option.value
رنگ	sys.inPage.option.color
تصویر	sys.inPage.option.image
توضیح	sys.inPage.option.description
انتخاب‌شده بودن	sys.inPage.option.selected
فعال بودن	sys.inPage.option.enabled
شماره گزینه	sys.inPage.option.index
کلید گروه والد	sys.inPage.option.group.key
عنوان گروه والد	sys.inPage.option.group.label

در صفحه الگوی عنوان گروه نیز این مقادیر در دسترس هستند:

مقدار	متغیر
کلید گروه	sys.inPage.optionGroup.key
عنوان گروه	sys.inPage.optionGroup.label
تعداد گزینه‌ها	sys.inPage.optionGroup.count
نوع نمایش نهایی	sys.inPage.optionGroup.presentation
چیدمان نهایی	sys.inPage.optionGroup.layout

نکته

از sys.inPage.option.selected و sys.inPage.option.enabled در شرط نمایش ویجت‌های صفحه الگو استفاده کنید تا ظاهر انتخاب‌شده و غیرفعال را متفاوت طراحی کنید.

اتصال انتخاب‌ها به متغیر

مقدار خروجی ویجت یک آبجکت JSON است که کلید هر گروه را به مقدار انتخاب‌شده متصل می‌کند:

{
  "size": "large",
  "color": "blue"
}

سه جهت اتصال در دسترس است:

• فیلد به متغیر: انتخاب‌های کاربر در متغیر نوشته می‌شوند.
• متغیر به فیلد: ویجت انتخاب‌ها را از متغیر می‌خواند و تغییر کاربر روی متغیر نوشته نمی‌شود.
• همگام‌سازی دوطرفه: تغییر ویجت و متغیر در هر دو جهت همگام می‌شود.

رویداد تغییر گزینه

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

مقدار	متغیر
نام انتخاب‌گر	sys.inPage.optionSelector.name
کلید گروه تغییریافته	sys.inPage.optionSelector.changedKey
مقدار انتخاب‌شده	sys.inPage.optionSelector.changedValue
همه انتخاب‌های فعلی	sys.inPage.optionSelector.selection

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

اعتبارسنجی

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

خطاهای رایج

• منبع داده آرایه نیست یا گروه‌ها آرایه گزینه ندارند.
• کلید گروه خالی یا در چند گروه تکراری است.
• نام فیلدها با بخش «نگاشت فیلدهای منبع» هماهنگ نیست.
• مقدار متغیر انتخاب‌ها آبجکت JSON نیست.
• صفحه الگو انتخاب شده، اما متغیرهای sys.inPage.option در آن استفاده نشده‌اند.
• گزینه رنگ یا تصویر دارد، اما مقدار رنگ یا نشانی تصویر معتبر نیست.

نکات طراحی و تست

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