آموزش جامع ScrollReveal

📚معرفی و شروع سریع

ScrollReveal یک کتابخانه فوق‌سبک برای اضافه کردن انیمیشن ورود به المان‌ها هنگام اسکرول است. بدون هیچ dependency‌ای کار می‌کند و فقط ~16KB است.

نصب

<script src="scrollreveal.min.js"></script>

ساده‌ترین استفاده

// یک خط — کافیه!
ScrollReveal().reveal('.my-element');

// با تنظیمات
ScrollReveal().reveal('.card', {
  origin:   'bottom',
  distance: '50px',
  duration: 800,
  delay:    200,
  opacity:  0,
  easing:   'ease-out',
  reset:    false
});

// ⚠️ وقتی scroll در یک div خاص است (نه window):
const sr = ScrollReveal({
  container: document.querySelector('.main-container')
});
sr.reveal('.element');

📍Origin و Distance

origin جهت ورود المان را تعیین می‌کند و distance فاصله‌ای که طی می‌کند.

sr.reveal('.from-bottom', { origin: 'bottom', distance: '60px' });  // پیش‌فرض
sr.reveal('.from-top',    { origin: 'top',    distance: '60px' });
sr.reveal('.from-left',   { origin: 'left',   distance: '80px' });
sr.reveal('.from-right',  { origin: 'right',  distance: '80px' });
sr.reveal('.fade-only',   { distance: '0px', opacity: 0 });     // فقط fade
sr.reveal('.far',          { origin: 'bottom', distance: '150px', duration: 1000 });

🔄Scale و Rotate

// scale — بزرگ‌نمایی هنگام ورود
sr.reveal('.scale-in', {
  scale:    0.4,       // شروع از ۴۰٪ اندازه
  distance: '0px',
  duration: 800,
  easing:   'ease-out'
});

// rotate — چرخش هنگام ورود
sr.reveal('.rotate-in', {
  rotate:   { x: 0, y: 0, z: 30 },  // چرخش ۳۰ درجه روی محور Z
  origin:   'left',
  distance: '30px',
  duration: 900
});

// ترکیب — scale + origin + opacity
sr.reveal('.combo', {
  scale:    0.6,
  origin:   'bottom',
  distance: '40px',
  opacity:  0,
  duration: 700,
  easing:   'cubic-bezier(0.34, 1.56, 0.64, 1)'  // spring
});

⏰تنظیمات زمان‌بندی

sr.reveal('.fast',   { duration: 300 });       // سریع
sr.reveal('.slow',   { duration: 1500 });      // کند
sr.reveal('.late',   { delay: 600 });           // با تأخیر
sr.reveal('.partial',{ viewFactor: 0.5 });     // فقط وقتی ۵۰٪ دیده شد
sr.reveal('.offset', { viewOffset: { bottom: 100 } }); // ۱۰۰px قبل از لبه

📈Easing — منحنی انیمیشن

// انواع easing
sr.reveal('.linear',   { easing: 'linear' });
sr.reveal('.ease-in',  { easing: 'ease-in' });
sr.reveal('.ease-out', { easing: 'ease-out' });
sr.reveal('.ease',     { easing: 'ease' });

// cubic-bezier سفارشی
sr.reveal('.spring', { easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)' });  // spring
sr.reveal('.bounce', { easing: 'cubic-bezier(0.68, -0.6, 0.32, 1.6)' }); // bounce
sr.reveal('.sharp',  { easing: 'cubic-bezier(0.4, 0, 0.6, 1)' });        // sharp

★Interval و Stagger

با interval می‌توانید المان‌های هم‌سلکتور را یکی‌پس‌از‌دیگری animate کنید — بدون نوشتن delay جداگانه برای هر کدام.

// همه .card ها با ۱۵۰ms فاصله ظاهر می‌شوند
sr.reveal('.card', {
  origin:   'bottom',
  distance: '40px',
  interval: 150   // ← کلید اصلی
});

// grid از بالا + interval
sr.reveal('.grid-item', {
  origin:   'top',
  interval: 100,
  scale:    0.85
});

🗑Reset و Cleanup

// reset: true — هر بار که المان وارد viewport می‌شود تکرار
sr.reveal('.repeating', { reset: true });

// حذف انیمیشن از یک المان
sr.clean('.my-element');

// حذف کامل ScrollReveal از صفحه
sr.destroy();

// تنظیمات پیش‌فرض سراسری
const sr = ScrollReveal({
  container: document.querySelector('.main'),
  distance:  '60px',
  duration:  800,
  easing:    'ease-out',
  opacity:   0,
  reset:     false        // پیش‌فرض سراسری
});

👁Container و Viewport

به‌صورت پیش‌فرض ScrollReveal از window به عنوان container استفاده می‌کند. اگر صفحه شما داخل یک div با overflow:auto اسکرول می‌شود، باید container را تعیین کنید.

// مشکل رایج: scroll داخل یک div (نه window)
// در این حالت ScrollReveal() پیش‌فرض کار نمی‌کند!

// ✓ راه‌حل: تعیین container
const sr = ScrollReveal({
  container: document.querySelector('.main-container')
});

// viewFactor — چقدر المان باید دیده شود (0 تا 1)
sr.reveal('.el', { viewFactor: 0.0 });  // فقط لبه‌اش دیده شود
sr.reveal('.el', { viewFactor: 0.5 });  // ۵۰٪ دیده شود
sr.reveal('.el', { viewFactor: 1.0 });  // کاملاً دیده شود

// viewOffset — فاصله trigger از لبه viewport
sr.reveal('.el', {
  viewOffset: { top: 50, bottom: 50 }
});

// opacity شروع (پیش‌فرض 0)
sr.reveal('.el', { opacity: 0.3 });  // شروع از ۳۰٪ شفافیت

📞Callback و رویدادها

sr.reveal('.el', {
  origin:   'bottom',
  duration: 600,

  // وقتی المان ظاهر شد
  afterReveal: function(el) {
    console.log('ظاهر شد:', el.id);
    el.classList.add('revealed');
  },

  // وقتی المان پنهان شد (فقط در reset:true)
  afterReset: function(el) {
    console.log('ریست شد:', el.id);
    el.classList.remove('revealed');
  },

  // وقتی المان وارد viewport شد (قبل از انیمیشن)
  beforeReveal: function(el) {
    console.log('در راه است...');
  }
});

🏆پروژه کامل — Landing Page

ترکیب تمام قابلیت‌ها برای ساخت یک Landing Page با انیمیشن‌های حرفه‌ای:

const sr = ScrollReveal({
  container: document.querySelector('.page'),
  distance:  '60px',
  duration:  800,
  easing:    'ease-out',
  opacity:   0,
  reset:     false
});

// Hero — از بالا با delay
sr.reveal('.hero-title',   { origin: 'top',    delay: 0 });
sr.reveal('.hero-sub',     { origin: 'bottom', delay: 200 });
sr.reveal('.hero-btn',     { scale: 0.8, delay: 400 });

// Feature cards — stagger از پایین
sr.reveal('.feature-card', { origin: 'bottom', interval: 150 });

// آمار — از چپ و راست
sr.reveal('.stat-item',    { origin: 'left', interval: 100 });

// Footer cols — از پایین با interval
sr.reveal('.footer-col',   { origin: 'bottom', interval: 120 });

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

المان‌ها را با ScrollReveal هنگام اسکرول نمایان کن. داخل کادر نتیجه اسکرول کن تا افکت اجرا شود. reset:true باعث تکرار می‌شود. نسخهٔ ۴.۰.۹ آفلاین بارگذاری می‌شود.