Repeater Inputs

کامپوننت x-repeater-inputs برای ساخت فرم‌های تکرارشونده (repeater) با قابلیت افزودن، حذف و مدیریت داینامیک ردیف‌ها در فرم‌ها استفاده می‌شود. این کامپوننت امکان تعریف ستون‌های مختلف با انواع ورودی (متن، عدد، سلکت و ...) را فراهم می‌کند و کنترل کاملی روی تعداد ردیف‌ها، حذف ردیف‌ها، پیام‌ها و ظاهر دارد.

---

ویژگی‌ها

• افزودن و حذف داینامیک ردیف‌ها در فرم
• تعیین حداقل و حداکثر تعداد ردیف‌ها (minRows, maxRows)
• تعیین تعداد اولیه ردیف‌ها (initialRows)
• امکان غیرفعال‌سازی حذف ردیف‌ها یا نمایش دکمه حذف همه
• پشتیبانی از پیام راهنما (hint) و پیام‌های سفارشی
• کنترل ظاهر پیام‌ها با پراپ‌های messageStyle و defaultMessageType
• امکان نمایش Tooltip برای کل کامپوننت یا دکمه حذف
• شخصی‌سازی کلاس کانتینر با containerClass
• پشتیبانی از مقدار اولیه (values)
• پشتیبانی از ردیف‌های ثابت با پراپ staticRows (تعریف ردیف‌هایی که همیشه در ابتدای جدول نمایش داده می‌شوند)
• امکان شرطی‌سازی حذف ردیف‌ها با پراپ deleteCondition
• تعریف ستون‌های دلخواه با کامپوننت x-repeater-input-column
• پشتیبانی از انواع ورودی: text number select multiselect switch hidden
• امکان تعیین یکتا بودن مقدار هر ستون (columnIsUnique)
• پشتیبانی از لیبل و Tooltip برای هر ستون

---

ورودی‌های کامپوننت

x-repeater-inputs

نام پراپ	نوع داده	مقدار پیش‌فرض	توضیحات
name	string	—	نام فیلد (اجباری)
id	string	null	شناسه یکتا برای کامپوننت
values	array	null	آرایه مقادیر اولیه برای ردیف‌ها
containerClass	string	null	کلاس CSS سفارشی برای کانتینر
initialRows	int/string	1	تعداد اولیه ردیف‌ها
maxRows	int	null	حداکثر تعداد ردیف‌ها
minRows	int	null	حداقل تعداد ردیف‌ها
allowDelete	bool	true	اجازه حذف ردیف‌ها
showDelete	bool	true	نمایش دکمه حذف هر ردیف
showDeleteAll	bool	false	نمایش دکمه حذف همه ردیف‌ها
defaultMessage	string	null	پیام پیش‌فرض برای نمایش
messageStyle	string/enum	"message"	استایل نمایش پیام (message, tooltip, ...)
defaultMessageType	string/enum	"info"	نوع پیام پیش‌فرض (info, error, warning, ...)
hint	string	null	پیام راهنما یا توضیح کوتاه
addRowText	string	افزودن ردیف	متن دکمه افزودن سطر جدید
tooltip	string	null	پیام راهنما هنگام هاور روی کل کامپوننت
deleteCondition	string	null	شرط حذف ردیف (مثلاً فقط اگر مقدار خاصی داشته باشد)
staticRows	array	null	تعریف ردیف‌های ثابت به صورت آرایه‌ای از آبجکت‌ها؛ هر آبجکت شامل کلیدهای name و label برای هر ردیف ثابت است (برای نمایش عناوین خاص در ابتدای هر سطر).
minColumnWidth	string	null	حداقل اندازه ستون‌ها

نکته

درون هر سطر کامپوننت x-repeater-inputs، شما می‌توانید از همه ویژگی‌ها و پراپ‌های مخصوص هر کامپوننت اینپوت (مانند x-number-input x-select و غیره) بهره ببرید. توجه داشته باشید هنگام مقداردهی پراپ‌ها باید آن‌ها را با فرمت camelCase بنویسید (مثلاً showSeparator یا showAmountInWords).

هشدار

در صورت مقداردهی به پراپ staticRows استایل متفاوتی مشابه نمای جدولی اعمال می‌شود و امکان درج سطر جدید را نخواهد داشت. مقدار وارد شده در label هر آیتم در ابتدای سطر نمایش داده می‌شود و مقدار name به عنوان اندیس در اینپوت‌های آن سطر قرار می‌گیرد

---

🕹️ متدهای ارتباط با کامپوننت

برای راحتی کار با کامپوننت x-repeater-inputs، متدهای jQuery زیر در دسترس هستند:

متدهای قابل استفاده:

• $("#repeater-id").getRows() دریافت آرایه‌ای از همه ردیف‌های فعلی (همه مقادیر سطر و ستون‌ها).

• $("#repeater-id").getRow(index) دریافت مقادیر یک ردیف خاص بر اساس شماره اندیس مورد نظر.

• $("#repeater-id").resetRepeaterInputs() بازنشانی کل مقادیر تکرارشونده به حالت اولیه.

• $("#repeater-id").toggleRequiredLabel(id, state) تغییر وضعیت کلاس الزامی (required) برای برچسب ستون موردنظر. اگر پارامتر state مقداردهی نشود، وضعیت فعلی برعکس می‌شود؛ اگر true باشد کلاس افزوده می‌گردد و اگر false باشد حذف خواهد شد.

مثال

// دریافت همه سطرها
var allRows = $("#my-repeater").getRows();

// دریافت سطر دوم (اندیس 1)
var secondRow = $("#my-repeater").getRow(1);

// ریست کردن همه سطرها به وضعیت اولیه
$("#my-repeater").resetRepeaterInputs();

// افزودن/حذف یا تغییر وضعیت کلاس 'required' روی برچسب ستون
$("#my-repeater").toggleRequiredLabel("my-input-id", true); // اضافه کردن کلاس required

تمامی متدها فقط زمانی کار می‌کنند که کامپوننت x-repeater-inputs به شکل کامل رندر و مقداردهی اولیه شده باشد.

---

x-repeater-input-column

نام پراپ	نوع داده	مقدار پیش‌فرض	توضیحات
columnName	string	—	نام ستون (اجباری)
columnId	string	null	شناسه برای هر ستون
columnLabel	string	null	لیبل ستون
columnType	string	'text'	نوع ورودی: text number select multiselect switch hidden
columnLabelTooltip	string	null	پیام راهنما برای لیبل ستون
columnIsUnique	bool	false	یکتا بودن مقدار ستون
columnSuffix	string	null	پسوند برای ورودی ستون
columnWidth	string	null	عرض دلخواه ستون (مقدار به پیکسل: 200px)

---

هشدار

پراپ columnWidth به طور ویژه برای نوع ورودی switch اضافه شده است. توصیه می‌شود برای سایر آیتم‌ها فقط در صورت نیاز خاص از آن استفاده کنید، چرا که استفاده بی‌رویه ممکن است باعث به‌هم‌ریختگی نمایش ستون‌ها شود. به طور پیش‌فرض، کامپوننت به صورت خودکار عرض ستون‌ها را به بهترین شکل مدیریت می‌کند.

مثال‌ها

نمونه پایه

$values = [
    [
        'id' => 1,
        'province' => ['1'],
        'code' => '123',
        'name' => 'پروژه اول',
    ],
    [
        'id' => 2,
        'province' => ['4'],
    ],
    [
        'province' => ['2'],
        'code' => '456',
        'name' => 'پروژه دوم',
    ],
    [
        'id' => 4,
    ],
    [
        'province' => ['3'],
    ],
];

$selectItems = [
    ['id' => 1, 'name' => '1402', 'value' => '1', 'selected' => false, 'is_active' => true],
    ['id' => 2, 'name' => '1403', 'value' => '2', 'selected' => false, 'is_active' => true],
    ['id' => 3, 'name' => '1404', 'value' => '3', 'selected' => false, 'is_active' => true],
];

$multiSelectItems = [
    ['id' => 1, 'name' => 'تهران', 'value' => '1', 'selected' => false, 'is_active' => true],
    ['id' => 2, 'name' => 'مازندران', 'value' => '2', 'selected' => false, 'is_active' => true],
    ['id' => 3, 'name' => 'گلستان', 'value' => '3', 'selected' => false, 'is_active' => true],
];

$staticRows = [
    [
        'name' => 'x',
        'label' => 'وضع موجود',
    ],
    [
        'name' => 'y',
        'label' => 'افق طرح',
    ],
];

<x-repeater-inputs
    name="repeater-inputs-sample"
    maxRows="10"
    minRows="1"
    initialRows="3"
    :show-delete-all="true"
    :allowDelete="true"
    :showDelete="true"
    :static-rows="$staticRows"
    hint="در این کامپوننت شما می‌توانید داده‌های متعدد وارد کنید"
    delete-condition="$row[year] != '1' || $row[code] != '123'"
    :values="$values"
>
    <x-slot:header> custom slot for html </x-slot:header>

    <x-repeater-input.column column-name="id" column-type="hidden" />

    <x-repeater-input.column
        column-name="code"
        column-label="کد پروژه"
        column-type="number"
        showAmountInWords
        amountInWordsSuffix="تومان"
        amountInWordsFactor="0.1"
        column-label-tooltip="کد پروژه را به صورت عددی وارد کنید"
        :column-is-unique="false"
        :showSeparator="true"
    />

    <x-repeater-input.column column-name="name" column-label="نام پروژه" column-type="text" :column-is-unique="true" />

    <x-repeater-input.column
        column-name="year"
        column-label="سال فعالیت"
        column-suffix="(میلادی)"
        column-type="select"
        :column-is-unique="true"
        :items="$selectItems"
    />

    <x-repeater-input.column
        column-name="province"
        column-label="استان"
        column-type="multiselect"
        :items="$multiSelectItems"
        :column-is-unique="true"
    />
</x-repeater-inputs>