Image Picker

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

---

ویژگی‌ها

• فقط انتخاب تصاویر (فرمت‌های رایج مانند jpg, png, webp, svg, ... پشتیبانی می‌شود)
• محدودیت پسوندهای مجاز (allowedExtensions) و غیرمجاز (disallowedExtensions) فقط برای تصاویر
• محدودیت حجم فایل (حداقل و حداکثر) (minSize, maxSize)
• محدودیت ابعاد تصویر (minWidth, maxWidth, minHeight, maxHeight)
• محدودیت نسبت تصویر (minAspectRatio, maxAspectRatio, aspectRatio)
• قابلیت کراپ تصویر قبل از آپلود (cropper, forceCropping, allowRecropping)
• کنترل کیفیت تصویر (quality)
• امکان تغییر نام فایل هنگام آپلود (allowRename)
• قابلیت فقط‌خواندنی (readonly)
• قابلیت پاک‌کردن تصویر انتخاب‌شده (clearable)
• شخصی‌سازی کلاس کانتینر پیش‌نمایش (previewContainerClass)
• تعیین ارتفاع ناحیه آپلود (uploadZoneHeight)
• کنترل نحوه نمایش تصویر (fit: cover/contain)
• تعیین حداکثر طول نام فایل (fileNameMaxLength)
• نمایش پیام راهنما هنگام غیرفعال بودن (disabledTooltip)
• پشتیبانی از پیام راهنما (hint)
• پشتیبانی از لیبل و فضای رزرو لیبل (label, labelSpaceReserved)
• کنترل نمایش پیام‌های منطقی (suppressLogicMessages)
• استایل و نوع پیام پیش‌فرض (messageStyle, defaultMessageType)

---

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

نام پراپ	نوع داده	مقدار پیش‌فرض	توضیحات
name	string	—	نام فیلد (اجباری)
label	string	null	لیبل اصلی
labelSpaceReserved	bool	false	آیا فضای لیبل حتی بدون مقدار رزرو شود؟
id	string	null	شناسه یکتا برای ورودی
class	string	null	کلاس CSS سفارشی برای خود ورودی
containerClass	string	null	کلاس CSS سفارشی برای کانتینر
allowedExtensions	string	همه فرمت‌های تصویر	پسوندهای مجاز (مثال: "jpg,png,webp")
disallowedExtensions	string	null	پسوندهای غیرمجاز (مثال: "svg")
minSize	int	null	حداقل حجم فایل (کیلوبایت)
maxSize	int	null	حداکثر حجم فایل (کیلوبایت)
defaultMessage	string	پیام پیش‌فرض	پیام پیش‌فرض برای نمایش
messageStyle	string/enum	"message"	استایل نمایش پیام (message, tooltip, ...)
defaultMessageType	string/enum	"info"	نوع پیام پیش‌فرض (info, error, success, ...)
hint	string	null	پیام راهنما یا توضیح کوتاه
suppressLogicMessages	bool	false	عدم نمایش پیام‌های منطقی
required	bool	false	اجباری بودن فیلد
previewContainerClass	string	null	کلاس سفارشی برای کانتینر پیش‌نمایش تصویر
src	int, string, object, null	null	مقدار اولیه (آیدی یا مدل فایل)
clearable	bool	true	امکان پاک‌کردن تصویر انتخاب‌شده
readonly	bool	false	فقط‌خواندنی بودن ورودی
allowRename	bool	false	امکان تغییر نام فایل هنگام آپلود
cropper	bool	false	فعال‌سازی کراپ تصویر
forceCropping	bool	false	اجبار به کراپ قبل از آپلود
allowRecropping	bool	false	اجازه کراپ مجدد
quality	float	0.75	کیفیت تصویر (۰ تا ۱)
maxWidth	int	null	حداکثر عرض تصویر (پیکسل)
maxHeight	int	null	حداکثر ارتفاع تصویر (پیکسل)
minWidth	int	null	حداقل عرض تصویر (پیکسل)
minHeight	int	null	حداقل ارتفاع تصویر (پیکسل)
minAspectRatio	float	null	حداقل نسبت تصویر (مثال: 1.5)
maxAspectRatio	float	null	حداکثر نسبت تصویر (مثال: 2)
aspectRatio	float	null	نسبت تصویر ثابت (مثال: 1 برای مربع)
uploadZoneHeight	string	null	ارتفاع ناحیه آپلود (مثال: "120px")
fit	string	"cover"	نحوه نمایش تصویر (cover, contain)
fileNameMaxLength	int	null	حداکثر طول نام فایل
disabled	bool	false	غیرفعال بودن ورودی
disabledTooltip	string	null	پیام راهنما هنگام غیرفعال بودن ورودی
header	string	null	متن دلخواه بالای ورودی
compactMode	boolean	false	تغییر استایل آپلودر به حالت کوچکتر مشابه file-picker

---

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

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

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

---

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

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

imagePickerInstance.setValue({
    key: "image-key" // FILE ID,
    name: "image.jpg",
    src: "https://example.com/image.jpg",
    size: 50000,
    extension: "jpg",
});

هشدار

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

توجه

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

const imagePickerElement = $('#slectorId');

const pickerInstance = imagePickerElement.getInstance();

pickerInstance?.resetValue();

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

initializeImagePicker("#slectorId");

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

---

مثال‌ها

نمونه پایه

<x-image-picker
    label="انتخاب تصویر"
    name="images3"
    container-class="col-md-6"
    hint="بدون cropper و با recropping"
    :force-cropping="true"
    accept=".png"
    :cropper="false"
    :allow-recropping="true"
/>