آموزش جامع Cropper.js

📦معرفی و نصب

Cropper.js یک کتابخانه JavaScript است که قابلیت برش تصویر (Image Cropping) را مستقیماً در مرورگر فراهم می‌کند — بدون نیاز به سرور برای پردازش اولیه. ایده‌آل برای آپلود تصویر پروفایل، تصویر محصولات، و هر جایی که کاربر باید تصویر را crop کند.

نصب

<!-- CSS را در head بگذارید -->
<link rel="stylesheet" href="cropper.min.css">

<!-- JS را قبل از استفاده بگذارید -->
<script src="cropper.min.js"></script>

ساختار HTML

<!-- تصویر باید داخل یک container باشد -->
<div style="max-width: 600px">
  <img id="my-image" src="photo.jpg" alt="عکس">
</div>

<!-- Preview (اختیاری) -->
<div class="preview" style="width:100px;height:100px;overflow:hidden"></div>

<script>
  const cropper = new Cropper(
    document.getElementById('my-image'),
    {
      aspectRatio: 1,         // نسبت 1:1
      viewMode:    1,         // cropbox داخل تصویر
      preview:     '.preview' // پیش‌نمایش زنده
    }
  );
</script>

✂️دمو زنده — برش پایه

Cropper.js را به‌صورت زنده امتحان کنید. Crop box را جابجا کنید، اندازه آن را تغییر دهید یا از دکمه‌ها استفاده کنید.

▶ دمو: تمام قابلیت‌های Cropper.js

👁 Preview زنده:

👤 نمایش دایره‌ای:

چرخش و آینه:

↺ -15° ↺ -45° ↻ +45° ↻ +90° ↔ آینه افقی ↕ آینه عمودی

زوم و حرکت:

🔍 + 🔍 - 100% ← ۲۰px → ۲۰px

Aspect Ratio:

1:1 16:9 4:3 آزاد

خروجی:

✂️ برش و نمایش ⇓ دانلود PNG ↻ ریست

📸 تصویر برش‌شده:

⚙گزینه‌ها (Options)

const cropper = new Cropper(image, {
  aspectRatio:    16 / 9,
  viewMode:       1,
  dragMode:       'move',
  preview:        '.preview',
  autoCropArea:   0.8,
  guides:         true,
  background:     false,    // پنهان کردن checkered
  minCropBoxWidth:  100,
  minCropBoxHeight: 100,
  ready() {
    console.log('Cropper آماده شد!');
  },
  crop(event) {
    // در هر تغییر cropbox صدا زده می‌شود
    console.log(event.detail);  // { x, y, width, height, rotate, scaleX, scaleY }
  }
});

📐Aspect Ratio و ViewMode

Aspect Ratio — نسبت ابعاد

ViewMode — محدودیت حرکت

// تغییر aspect ratio بعد از ایجاد
cropper.setAspectRatio(16/9);
cropper.setAspectRatio(NaN);     // آزاد

// تنظیم دقیق cropbox با کد
cropper.setCropBoxData({
  left: 50, top: 30, width: 400, height: 225
});

// دریافت اطلاعات cropbox
const box = cropper.getCropBoxData();
console.log(box); // { left, top, width, height }

// دریافت کامل داده‌های crop
const data = cropper.getData();
console.log(data);
// { x, y, width, height, rotate, scaleX, scaleY }

⚡متدهای مهم

// چرخش
cropper.rotate(90);   // +90 از حالت فعلی
cropper.rotateTo(0);  // برگشت به زاویه صفر

// آینه
let scaleX = 1;
cropper.scaleX(scaleX *= -1);  // toggle

// زوم به مرکز
cropper.zoomTo(1.5);   // 150%
cropper.zoomTo(1);     // 100% (اصلی)

// تنظیم cropbox با setData
cropper.setData({
  x: 50, y: 30,
  width: 400, height: 225,
  rotate: 0, scaleX: 1, scaleY: 1
});

🔔رویدادها (Events)

Cropper.js رویدادهای مختلفی را در مراحل مختلف تعامل کاربر می‌زند. می‌توانید با addEventListener به آن‌ها گوش دهید.

مقادیر action در cropstart/cropmove/cropend

// action می‌تواند این مقادیر باشد:
'crop'     // ساختن cropbox جدید
'move'     // حرکت دادن cropbox
'e'        // کشیدن لبه east
'w'        // کشیدن لبه west
's'        // کشیدن لبه south
'n'        // کشیدن لبه north
'se'       // کشیدن گوشه جنوب‌شرقی
'all'      // حرکت تصویر
'zoom'     // zoom

// نمونه: گوش دادن به رویدادها
const img = document.getElementById('my-image');

img.addEventListener('ready', () => {
  console.log('Cropper آماده است!');
});

img.addEventListener('crop', event => {
  const { x, y, width, height } = event.detail;
  // به‌روزرسانی UI با ابعاد
  infoEl.textContent = `${Math.round(width)} × ${Math.round(height)} px`;
});

img.addEventListener('zoom', event => {
  if (event.detail.ratio > 3) {
    event.preventDefault(); // جلوگیری از زوم بیش از 300%
  }
  console.log('زوم:', Math.round(event.detail.ratio * 100) + '%');
});

▶ دمو: لاگ رویدادها — Crop box را جابجا کنید

ابعاد Crop:

—

لاگ رویدادها:

// منتظر رویداد...

🗑 پاک

📤خروجی Canvas

با getCroppedCanvas() یک canvas HTML5 دریافت می‌کنید که می‌توانید آن را به dataURL، Blob یا فایل دانلودی تبدیل کنید.

const canvas = cropper.getCroppedCanvas({
  width:  800,                    // عرض خروجی (px)
  height: 800,                    // ارتفاع خروجی
  minWidth:  100, maxWidth:  4096,
  minHeight: 100, maxHeight: 4096,
  fillColor: '#fff',              // رنگ پس‌زمینه (برای PNG شفاف)
  imageSmoothingEnabled: true,
  imageSmoothingQuality: 'high'   // 'low' | 'medium' | 'high'
});

// ۱. تبدیل به dataURL (base64)
const png  = canvas.toDataURL('image/png');
const jpeg = canvas.toDataURL('image/jpeg', 0.9);  // 90% کیفیت
const webp = canvas.toDataURL('image/webp', 0.85); // 85% کیفیت

// ۲. تبدیل به Blob (برای ارسال به سرور)
canvas.toBlob(blob => {
  const url = URL.createObjectURL(blob);
  console.log('حجم: ' + (blob.size / 1024).toFixed(1) + ' KB');
}, 'image/jpeg', 0.9);

// ۳. دانلود مستقیم
const a = document.createElement('a');
a.download = 'cropped.png';
a.href = canvas.toDataURL();
a.click();

🌐ارسال به سرور

پس از برش، تصویر را با FormData و Fetch (یا Axios) به سرور ارسال کنید.

با Fetch API

async function uploadCropped(cropper) {
  return new Promise((resolve, reject) => {
    cropper.getCroppedCanvas({
      width: 800, height: 800,
      imageSmoothingQuality: 'high'
    }).toBlob(async blob => {
      const formData = new FormData();
      formData.append('image', blob, 'cropped.jpg');
      formData.append('userId', '12345');

      try {
        const res = await fetch('/api/avatar', {
          method: 'POST',
          body: formData
          // Content-Type نباید دست‌ارسال شود — مرورگر boundary را می‌گذارد
        });
        const data = await res.json();
        resolve(data);
      } catch(err) { reject(err); }
    }, 'image/jpeg', 0.92);
  });
}

با Axios و نمایش Progress

async function uploadWithProgress(cropper, onProgress) {
  return new Promise(resolve => {
    cropper.getCroppedCanvas({ width: 800 }).toBlob(async blob => {
      const fd = new FormData();
      fd.append('file', blob, 'avatar.jpg');

      const res = await axios.post('/api/upload', fd, {
        onUploadProgress: e => {
          const pct = Math.round(e.loaded / e.total * 100);
          onProgress(pct);
        }
      });
      resolve(res.data);
    }, 'image/jpeg', 0.9);
  });
}

// استفاده
await uploadWithProgress(myCropper, pct => {
  progressBar.style.width = pct + '%';
  label.textContent = pct + '٪';
});

📁آپلود و برش تصویر کاربر

رایج‌ترین کاربرد: کاربر تصویر آپلود می‌کند، crop می‌دهد، و نتیجه دریافت می‌شود.

// بارگذاری تصویر از input
document.getElementById('file-input').addEventListener('change', e => {
  const file = e.target.files[0];
  if (!file || !file.type.startsWith('image/')) return;

  const url = URL.createObjectURL(file); // بهتر از FileReader
  const img = document.getElementById('crop-img');

  if (window.myCropper) {
    window.myCropper.replace(url);         // جایگزین تصویر قبلی
  } else {
    img.src = url;
    window.myCropper = new Cropper(img, {
      aspectRatio: 1,
      viewMode:    1,
      preview:     '.preview'
    });
  }
});

▶ دمو: آپلود و برش تصویر دلخواه

📁

کلیک کنید یا تصویر را اینجا بکشید

PNG، JPG، WebP، GIF

👁 Preview:

👤 گرد:

1:1 — پروفایل 16:9 — Banner 4:3 — استاندارد آزاد ↺ -90° ↻ +90° ↔ آینه ✂️ ذخیره برش ↻ شروع مجدد

📸 نتیجه برش:

⇓ دانلود PNG

🌟پروژه کامل: تصویر پروفایل

یک سناریوی واقعی و کامل: کاربر تصویر آپلود می‌کند، crop مربعی 1:1 می‌دهد، و تصویر در کارت پروفایل نمایش داده می‌شود.

// کد کامل پروژه آپلود تصویر پروفایل
let profileCropper = null;
let scaleXVal = 1, scaleYVal = 1;

document.getElementById('avatar-input').addEventListener('change', e => {
  const file = e.target.files[0];
  if (!file) return;

  const url = URL.createObjectURL(file);
  const img = document.getElementById('avatar-img');
  if (profileCropper) profileCropper.replace(url);
  else {
    img.src = url;
    profileCropper = new Cropper(img, {
      aspectRatio: 1,     // مربع کامل
      viewMode:    1,
      dragMode:    'move',
      autoCropArea:0.9,
      preview:     '.avatar-preview',
      ready() { document.getElementById('crop-actions').style.display = 'flex'; }
    });
  }
  document.getElementById('crop-panel').style.display = 'block';
});

function applyAvatar() {
  const canvas = profileCropper.getCroppedCanvas({ width:300, height:300 });
  document.getElementById('profile-avatar').src = canvas.toDataURL('image/jpeg', 0.9);
}

▶ دمو: آپلود تصویر پروفایل کامل

نام: نقش:

👤

انتخاب تصویر پروفایل

↺ ↻ ↔ ✓ اعمال ✕

پیش‌نمایش کارت:

مصطفی موسوی

توسعه‌دهنده Front-End

🚀زمین بازی کد (Playground)

با Cropper.js روی یک تصویر نمونه کار کن: ناحیهٔ برش را بکش، گزینه‌ها (aspectRatio، viewMode) را تغییر بده و متدها (چرخش/زوم/برش) را امتحان کن. نسخهٔ ۱.۶.۲ آفلاین بارگذاری می‌شود.