در GSAP، ()gsap.matchMediaیک ابزار قدرتمند برای ساخت انیمیشن‌های واکنش‌گرا (Responsive) و دسترس‌پذیر (Accessible) است.
با این قابلیت می‌توان انیمیشن‌ها را بر اساس Media Query یا شرایط دلخواه فعال یا غیرفعال کرد.

🟢 1️⃣ ایجاد matchMedia

const mm = gsap.matchMedia();

• mm یک شیء مدیریت‌کننده Media Query است.

• اجازه می‌دهد Tweenها و Timelineها فقط وقتی شرایط مشخص برقرار است اجرا شوند.

🟡 2️⃣ استفاده با Media Query

mm.add("(min-width: 768px)", () => {
  gsap.to(".box", { x: 200, duration: 1 });
  return () => {
    // Cleanup: وقتی Media Query تغییر کند
    gsap.set(".box", { x: 0 });
  };
});

• آرگومان اول: Media Query مشابه CSS

• آرگومان دوم: تابعی که انیمیشن‌ها را تعریف می‌کند و می‌تواند یک تابع cleanup بازگرداند.

مثال واکنش‌گرایی:

mm.add({
  "(min-width: 1024px)": () => gsap.to(".box", { x: 300 }),
  "(max-width: 1023px)": () => gsap.to(".box", { x: 100 })
});

• برای هر Breakpoint انیمیشن متفاوت اجرا می‌شود.

🟠 3️⃣ استفاده با شرایط غیر Media Query

می‌توانید شرایط دلخواه هم بدهید:

mm.add("(prefers-reduced-motion: reduce)", () => {
  // برای دسترس‌پذیری: انیمیشن‌ها کم یا حذف شوند
  gsap.set(".box", { opacity: 1 });
});

• مناسب برای کاربرانی که Reduce Motion فعال کرده‌اند.

🟣 4️⃣ Cleanup خودکار

• وقتی Media Query تغییر کند یا انیمیشن غیرفعال شود، GSAP انیمیشن‌ها را پاک و CSS را revert می‌کند.

• این باعث می‌شود که پروژه SPA یا صفحات واکنش‌گرا بدون مشکل اجرا شوند.

const mm = gsap.matchMedia();

mm.add("(min-width: 768px)", () => {
  const tl = gsap.timeline();
  tl.to(".box", { x: 200 });
  
  // تابع بازگشت برای Cleanup
  return () => tl.kill();
});

🟤 5️⃣ ترکیب با Context و Timeline

const mm = gsap.matchMedia();

mm.add("(min-width: 1024px)", () => {
  const ctx = gsap.context(() => {
    gsap.to(".card", { x: 300, stagger: 0.2 });
  });
  return () => ctx.revert();
});

• ترکیب Context + matchMedia بهترین روش برای مدیریت انیمیشن‌های پیچیده واکنش‌گرا است.

⚡ نکات حرفه‌ای

1. Responsive Animations: تغییر انیمیشن با تغییر اندازه صفحه.

2. Accessibility: تشخیص prefers-reduced-motion و کاهش یا حذف انیمیشن‌ها.

3. Cleanup خودکار: وقتی شرایط Media Query دیگر برقرار نیست، انیمیشن‌ها پاک می‌شوند.

4. Stagger و Timeline: تمام ویژگی‌های GSAP قابل استفاده داخل matchMedia هستند.

✅ جمع‌بندی

با matchMedia می‌توانید انیمیشن‌ها را واکنش‌گرا، قابل کنترل و دسترس‌پذیر طراحی کنید، بدون نیاز به کدنویسی پیچیده CSS یا JS برای شرایط مختلف.