Img

مانند Image است با این تفاوت که فقط عکس را نشان میدهد اما Image گیف هم نمایش میدهد.

خواص این المان :

     ↵  Src :

              لینک تصویر میباشد و تصویر از این لینک بارگیری می شود.

   ↵  Validate :

                با نوشتن id ورودی هایی که نیاز به چک شدن دارن و جدا کردن آن ها با  “ , ” تمام تکست باکس ها و دیگر ورودی ها با regex که داخل خاصیت validation در آن المان داده شده چک میشوند و در صورتی که تمام آن ها درست بودند اکشن نهایی داخل onclick اجرا میشود. این اتفاقات پس از کلیک شدن المان رخ می دهد.

     ↵  OnClick :

              در صورت کلیک شدن المان صدا میشود و مقدار آن یک اکشن می باشد.

     ↵  Align :

              موقعیت مکانی شروع المان در صفحه را مشخص میکند

     ↵  Tint :

              رنگ عکس را تغییر میدهد.

     ↵  scaletype :

              نحوه نمایش تصویر را مشخص میکند و مقادیر center برای نمایش در مرکز  center_crop برای نمایش در مرکز با بریدن اضافاتcenter_inside برای نمایش در مرکز و داخل،  fit_center برای کوچک کردن عکس به صورتی که با طول و عرض داده شده و مرکز محور مطابق شود ، fit_end برای نمایش در انتها  fit_start برای نمایش در شروع و  fit_xy برای پیروی از طول و عرض مادر و focus_crop برای برش از قسمت متمرکز را میگیرد.

     ↵  aspectRatio :

              انداره و مدل عکس را مشخص میکند. مقادیر center و center_crop و center_inside و fit_center و fit_end و fit_start و fit_xy و focus_crop را میگیرد.

پشتیبانی از تصاویر Base64

نسخه مورد نیاز: قابلیت‌های جدید این بخش شامل بارگذاری امن و غیرهمزمان Base64، رویدادهای onload/onerror و محدودیت‌های قابل تنظیم، از appsansdk-core 0.1.78 به بعد در دسترس هستند. فرمت‌های base64:// و data: در نسخه‌های قبلی نیز پشتیبانی می‌شدند.

خاصیت src علاوه بر لینک‌های معمولی و مسیر فایل‌های محلی، دو فرمت قبلی Base64 را نیز بدون نیاز به تغییر در کد مینی‌اپ پشتیبانی می‌کند:

• base64://BASE64_DATA
• data:image/png;base64,BASE64_DATA (یا MIME type معتبر تصویر)

<img id="photo" width="match_parent" height="300" />

Appsan.setProperty('photo', 'src', 'base64://' + imageData);
// یا
Appsan.findElementById('photo').setProperty('src', dataUrl);

سازگاری با نسخه‌های قبل: امضای API و فرمت‌های base64:// و data: تغییری نکرده‌اند و کدهای فعلی بدون مهاجرت کار می‌کنند.

نحوه بارگذاری و مدیریت حافظه

بارگذاری Base64 به‌صورت غیرهمزمان انجام می‌شود تا Thread اصلی برنامه مسدود نشود. داده به‌صورت stream در فایل موقت decode می‌شود، ابعاد تصویر قبل از ساخت Bitmap بررسی می‌شود و تصویر متناسب با اندازه View و بودجه حافظه downsample می‌شود. هنگام تغییر مجدد src، درخواست قبلی لغو خواهد شد.

در زمان بارگذاری placeholder نمایش داده می‌شود. اگر داده نامعتبر یا بزرگ‌تر از محدودیت‌های مجاز باشد، آیکن خطا نمایش داده شده، خطا در لاگ Appsan ثبت می‌شود و در صورت تعریف شدن onerror اکشن مربوطه اجرا می‌شود. این رفتار جایگزین freeze یا crash شدن برنامه است.

OnLoad

اختیاری است و پس از بارگذاری موفق تصویر اجرا می‌شود. مقدار $data شامل width و height تصویر اصلی است. برای منابع غیر Base64 ممکن است این دو مقدار صفر باشند.

OnError

اختیاری است و در صورت شکست بارگذاری اجرا می‌شود. مقدار $data شامل فیلدهای code و message است.

<img
    id="photo"
    width="match_parent"
    height="300"
    onload="script/script:imageLoaded($data)"
    onerror="script/script:imageFailed($data)"
/>

<script id="script">
function imageLoaded(data) {
    console.log('Image loaded:', data.width, data.height);
}

function imageFailed(error) {
    console.error('Image error:', error.code, error.message);
}
</script>

کدهای خطای Base64

• INVALID_DATA_URL: ساختار Data URL معتبر نیست یا فرمت Base64 ندارد.
• INVALID_BASE64: داده Base64 نامعتبر یا خالی است.
• IMAGE_SOURCE_TOO_LARGE: اندازه متن Base64 یا داده decodeشده از حد مجاز بیشتر است.
• IMAGE_DIMENSIONS_TOO_LARGE: ابعاد تصویر یا حافظه Bitmap از حد مجاز بیشتر است.
• IMAGE_DECODE_FAILED: داده، تصویر پشتیبانی‌شده‌ای نیست یا خواندن آن شکست خورده است.
• IMAGE_OUT_OF_MEMORY: با وجود کنترل‌های اولیه، حافظه کافی برای decode موجود نبوده است.

محدودیت‌های پیش‌فرض

اگر تصویر از این محدودیت‌ها عبور کند، بارگذاری کنترل‌شده شکست می‌خورد و onerror فراخوانی می‌شود. کوچک بودن ظاهری المان به‌تنهایی به معنی کم بودن حافظه Bitmap نیست؛ SDK تصویر را هنگام decode متناسب با اندازه المان نمونه‌برداری می‌کند.

تنظیم محدودیت‌ها در برنامه میزبان

این تنظیم اختیاری و فقط برای توسعه‌دهنده برنامه میزبان است. مینی‌اپ‌ها نیازی به تغییر ندارند.

Appsan.getInstance().setImageSourceLimits(
    new ImageSourceLimits.Builder()
        .setMaximumEncodedBytes(24L * 1024L * 1024L)
        .setMaximumDecodedDataBytes(18L * 1024L * 1024L)
        .setMaximumDecodedBitmapBytes(32L * 1024L * 1024L)
        .setMaximumDimension(16_384)
        .build()
);