File Picker

کامپوننت x-file-picker یک ورودی پیشرفته برای انتخاب و آپلود فایل در فرم‌ها است که امکانات متنوعی مانند انتخاب چندگانه، محدودیت نوع و حجم فایل، پیش‌نمایش تصویر/ویدیو، قابلیت حذف و جایگزینی فایل، کنترل فقط‌خواندنی، شخصی‌سازی ظاهر و ... را ارائه می‌دهد.

---

ویژگی‌ها

• پشتیبانی از انتخاب یک یا چند فایل (multiple)
• تعیین پسوندهای مجاز و غیرمجاز (allowedExtensions, disallowedExtensions)
• محدودیت حجم فایل (حداقل و حداکثر) (minSize, maxSize)
• محدودیت تعداد فایل انتخابی (minSelection, maxSelection)
• پیش‌نمایش تصویر و ویدیو و نمایش آیکن برای سایر فرمت‌ها
• قابلیت حذف و جایگزینی فایل (دکمه‌های حذف و جایگزین)
• قابلیت فقط‌خواندنی (readonly)
• امکان تغییر نام فایل هنگام آپلود (allowRename)
• شخصی‌سازی تعداد ستون پیش‌نمایش (cols) و کلاس کانتینر پیش‌نمایش (previewContainerClass)
• کنترل نمایش دکمه پاک‌کردن (clearable)
• کنترل نمایش پاپ‌آپ پیش‌نمایش و تصویر بندانگشتی (showPreviewPopup, showPreviewThumbnail)
• تعیین حداکثر طول نام فایل (fileNameMaxLength)
• شخصی‌سازی کلاس‌های CSS برای خود و کانتینر
• نمایش پیام راهنما هنگام غیرفعال بودن (disabledTooltip)
• پشتیبانی از پیام راهنما (hint)
• پشتیبانی از لیبل و فضای رزرو لیبل (label, labelSpaceReserved)
• کنترل نمایش پیام‌های منطقی (suppressLogicMessages)
• استایل و نوع پیام پیش‌فرض (messageStyle, defaultMessageType)
• تعیین ارتفاع و جهت ناحیه آپلود (uploadZoneHeight, uploadZoneOrientation)

---

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

نام پراپ	نوع داده	مقدار پیش‌فرض	توضیحات
name	string	—	نام فیلد (اجباری)
label	string	null	لیبل اصلی
labelSpaceReserved	bool	false	آیا فضای لیبل حتی بدون مقدار رزرو شود؟
id	string	null	شناسه یکتا برای ورودی
class	string	null	کلاس CSS سفارشی برای خود ورودی
containerClass	string	null	کلاس CSS سفارشی برای کانتینر
multiple	bool	false	امکان انتخاب چند فایل
allowedExtensions	string	null	پسوندهای مجاز (مثال: "jpg,png,mp4")
disallowedExtensions	string	null	پسوندهای غیرمجاز (مثال: "exe,php")
minSize	int	null	حداقل حجم فایل (کیلوبایت)
maxSize	int	null	حداکثر حجم فایل (کیلوبایت)
minSelection	int	null	حداقل تعداد فایل انتخابی
maxSelection	int	null	حداکثر تعداد فایل انتخابی
defaultMessage	string	null	پیام پیش‌فرض برای نمایش
messageStyle	string/enum	"message"	استایل نمایش پیام (message, tooltip, ...)
defaultMessageType	string/enum	"info"	نوع پیام پیش‌فرض (info, error, success, ...)
hint	string	null	پیام راهنما یا توضیح کوتاه
suppressLogicMessages	bool	false	عدم نمایش پیام‌های منطقی
cols	int	null	تعداد ستون پیش‌نمایش فایل‌ها
required	bool	false	اجباری بودن فیلد
previewContainerClass	string	null	کلاس سفارشی برای کانتینر پیش‌نمایش فایل‌ها
value	array,object,int,string,null	null	مقدار اولیه (آیدی یا آرایه آیدی فایل‌ها)
clearable	bool	true	امکان پاک‌کردن فایل انتخاب‌شده
readonly	bool	false	فقط‌خواندنی بودن ورودی
allowRename	bool	false	امکان تغییر نام فایل هنگام آپلود
fileNameMaxLength	int	255	حداکثر طول نام فایل
disabled	bool	false	غیرفعال بودن ورودی
disabledTooltip	string	null	پیام راهنما هنگام غیرفعال بودن ورودی
showPreviewPopup	bool	false	نمایش پاپ‌آپ پیش‌نمایش فایل
previewMode	enum	fancybox	نوع پیش نمایش پاپ‌آپ (fancybox یا modal)
showPreviewThumbnail	bool	false	نمایش تصویر بندانگشتی فایل
uploadZoneHeight	string	null	ارتفاع ناحیه آپلود (مثال: "120px")
uploadZoneOrientation	string	"horizontal"	جهت ناحیه آپلود (horizontal یا vertical)
deleteTooltipText	string	null	متن راهنمای حذف فایل
replaceTooltipText	string	null	متن راهنمای جایگزینی فایل
disableReplace	bool	false	غیر فعال کردن امکان جایگزینی فایل
disableDelete	bool	false	غیر فعال کردن امکان حذف فایل

---

رویداد سفارشی change

با توجه به ساختار پیاده‌سازی شده برای کامپوننت x-file-picker، رویداد جداگانه‌ای برای اطلاع از تغییرات فایل‌ها در کامپوننت فراهم شده است که می‌توانید به صورت زیر از آن استفاده کنید.

$("#file-picker").on("file-picker:change", function (e, data) {
    console.log(data); // شامل فایل‌های انتخاب شده
});

---

مقداردهی با جاوااسکریپت

برای مقداردهی یا تغییر مقدار کامپوننت x-file-picker به صورت داینامیک با جاوااسکریپت، می‌توانید از متد زیر استفاده کنید:

// مقداردهی با یک فایل
filePickerInstance.setValue({
    key: "file-key",
    name: "filename.pdf",
    src: "https://example.com/file.pdf",
    size: 120000,
    extension: "pdf",
});

// مقداردهی با چند فایل
filePickerInstance.setValue([
    {
        key: "file-key-1",
        name: "image1.jpg",
        src: "https://example.com/image1.jpg",
        size: 50000,
        extension: "jpg",
    },
    {
        key: "file-key-2",
        name: "video1.mp4",
        src: "https://example.com/video1.mp4",
        size: 2000000,
        extension: "mp4",
    },
]);

• مقدار ورودی می‌تواند یک شیء فایل یا آرایه‌ای از فایل‌ها باشد.
• هر فایل باید شامل کلیدهای key, name, و src باشد و می‌تواند size و extension نیز داشته باشد.

هشدار

در صورتی که مقداردهی پراپ src به وسیله یک آدرس اینترنتی (url) انجام شود، برخی امکانات نظیر حذف یا ویرایش تصویر به درستی عمل نخواهند کرد. توصیه می‌شود برای عملکرد کاملِ کامپوننت، مقدار src را به صورت آیدی یا مدل فایل تنظیم کنید.

توجه

برای initialize کردن کامپوننت با مقادیر جدید میتوان به شکل زیر عمل کرد.

const filePickerElement = $('#slectorId');

const pickerInstance = filePickerElement.getInstance();

pickerInstance?.resetValue();

filePickerElement.data({
'allowed-extensions': allowed_extensions,
'max-size': max_size
})

initializeFilePicker("#slectorId");

pickerInstance?.updateHelper({max_size, allowed_extensions});

---

مثال‌ها

نمونه پایه

<x-file-picker
    name="documents_multiple"
    label="انتخاب فایل (چندتایی)"
    showPreviewPopup
    showPreviewThumbnail
    :multiple="true"
    :value="[4, 2, 114, 113]"
    :clearable="true"
/>

<x-file-picker
    name="documents"
    label="انتخاب فایل"
    showPreviewPopup
    showPreviewThumbnail
    allowed-extensions="zip,exe,pdf"
    disallowed-extensions="exe"
    :allowRename="true"
    :file-name-max-length="50"
>
    <x-slot:label-suffix-slot>
        <a href="#">استعلام</a>
    </x-slot:label-suffix-slot>
</x-file-picker>