Text Input

کامپوننت x-text-input یک ورودی تک‌خطی پیشرفته برای فرم‌ها است که امکانات متنوعی مانند کنترل طول، پیشنهادها (suggestion)، پیشوند و پسوند، ماسک ورودی، کنترل راست‌چین/چپ‌چین بودن، trim خودکار، پیام راهنما، پیام خطا، کنترل اتوکامپلیت، و ... را ارائه می‌دهد.

---

ویژگی‌ها

• پشتیبانی از لیبل و فضای رزرو لیبل
• تعیین مقدار اولیه (value)
• تعیین placeholder
• کنترل اتوکامپلیت (autoComplete)
• پشتیبانی از پیشوند (prefix) و پسوند (suffix)
• کنترل حداقل و حداکثر طول (minLength, maxLength)
• محدودیت تعداد کاراکتر (charLength)
• کنترل جهت نوشتار (direction: rtl یا ltr)
• کنترل تراز متن (textAlign: right یا left)
• اعتبارسنجی با قوانین (rules) یا regex
• پیشنهادهای ورودی (suggestions)
• ماسک ورودی (maskExpression)
• trim خودکار مقدار (trim)
• فوکوس خودکار (autoFocus)
• نمایش پیام راهنما هنگام غیرفعال بودن (disabledTooltip)
• نمایش پیام خطا و پیام‌های سفارشی با استایل‌های مختلف
• امکان شخصی‌سازی کلاس‌های CSS برای خود و کانتینر
• پشتیبانی از پیام راهنما (hint)
• پشتیبانی از slot برای suffix لیبل (label-suffix-slot)
• غیرفعال یا فقط‌خواندنی بودن ورودی

---

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

نام پراپ	نوع داده	مقدار پیش‌فرض	توضیحات
name	string	—	نام فیلد (اجباری)
id	string	null	شناسه یکتا برای ورودی
label	string	null	لیبل اصلی
labelSpaceReserved	bool	false	آیا فضای لیبل حتی بدون مقدار رزرو شود؟
value	string	null	مقدار اولیه
placeholder	string	null	placeholder برای ورودی
autoComplete	string	"off"	مقدار autocomplete (مانند "off", "on", "email", ...)
prefix	string	null	پیشوند
suffix	string	null	پسوند
minLength	string/int	null	حداقل طول مجاز
maxLength	string/int	null	حداکثر طول مجاز
charLength	string/int	null	محدودیت تعداد کاراکتر (نمایش شمارنده)
direction	string	'rtl'	جهت نوشتار ورودی (rtl یا ltr)
textAlign	string	null	تراز متن ورودی (right یا left)
required	bool	false	اجباری بودن فیلد
rules	string	null	قوانین اعتبارسنجی (Laravel validation rules)
regexExpression	string	null	regex برای اعتبارسنجی
suggestions	array	[]	آرایه‌ای از پیشنهادهای ورودی
maskExpression	string	null	ماسک ورودی (مثلاً برای شماره تلفن)
defaultMessage	string	null	پیام پیش‌فرض برای نمایش
messageStyle	string/enum	"message"	استایل نمایش پیام (message, tooltip, ...)
defaultMessageType	string/enum	"info"	نوع پیام پیش‌فرض (info, error, success, ...)
suppressLogicMessages	bool	false	عدم نمایش پیام‌های منطقی
trim	bool	false	حذف فاصله‌های ابتدا و انتهای مقدار
autoFocus	bool	false	فوکوس خودکار روی ورودی
containerClass	string	null	کلاس CSS سفارشی برای کانتینر
class	string	null	کلاس CSS سفارشی برای خود ورودی
hint	string	null	پیام راهنما یا توضیح کوتاه
disabled	bool	false	غیرفعال بودن ورودی
disabledTooltip	string	null	پیام راهنما هنگام غیرفعال بودن ورودی
clearable	bool	false	نمایش دکمه پاک کردن مقدار ورودی

---

گزینه‌های ماسک (maskExpression)

کامپوننت x-text-input از ماسک‌های از پیش تعریف شده برای فرمت‌دهی ورودی‌های رایج پشتیبانی می‌کند. می‌توانید نام ماسک را به عنوان مقدار maskExpression استفاده کنید:

نام ماسک	مقدار ماسک	فرمت خروجی	توضیحات
nationalCode	9999999999	5354286727	کد ملی (۱۰ رقم)
postalCode	9999999999	1234567890	کد پستی (۱۰ رقم)
phone	999-99999999	021-12345678	شماره تلفن ثابت
mobile	99999999999	09123456789	شماره موبایل (۱۱ رقم)
bankCard	9999-9999-9999-9999	1234-5678-9012-3456	شماره کارت بانکی (۱۶ رقم با خط تیره)
ibanNumber	IR999999999999999999999999	IR123456789012345678901234	شماره شبا (۲۶ رقم با پیشوند IR)
ip	999.999.999.999	192.168.101.100	آدرس IP نسخه ۴

نکته

می‌توانید به جای استفاده از نام ماسک، الگوی ماسک سفارشی خود را نیز به صورت مستقیم وارد کنید. برای مثال می‌توانید از maskExpression="9999-9999" استفاده کنید.

---

مثال‌ها

نمونه پایه

<x-text-input
    label="آی پی"
    name="ip"
    prefix="ip"
    defaultMessage="IPV4"
    direction="rtl"
    textAlign="right"
    rules="num"
    regexExpression="^[A-Y]+"
    maskExpression="ip"
/>

<x-text-input
    label="نام"
    name="fname"
    value="DFGDG"
    placeholder="لطفا نام خود را وارد کنید"
    prefix="$"
    suffix="SUD"
    :suggestions="['Naghi', 'Taghi', 'Karim']"
    defaultMessage="لطفا نام خود را وارد نمایید."
    minLength="3"
    maxLength="6"
    charLength="6"
    direction="rtl"
    textAlign="right"
    rules="num"
    messageStyle="toast"
    regexExpression="^[A-Y]+"
>
    <x-slot:label-suffix-slot>
        <a href="/">استعلام مجدد</a>
    </x-slot:label-suffix-slot>
</x-text-input>