در GSAP، توابع کمکی مانند getProperty()، getUnit()، selector() و toArray() ابزارهایی برای دسترسی و مدیریت المان‌ها و ویژگی‌های CSS یا DOM هستند. این توابع مخصوصاً وقتی با Tweenها، Modifiers و dynamic animations کار می‌کنید بسیار کاربردی‌اند.

🟢 1️⃣ ()getProperty

• کاربرد: خواندن مقدار یک ویژگی (CSS یا Attribute) از یک المان.

• ساختار:

gsap.getProperty(target, property)

مثال:

let box = document.querySelector(".box");
let x = gsap.getProperty(box, "x");  // مقدار فعلی transform: translateX
console.log(x);

• می‌تواند CSS، transform یا attribute باشد.

• مفید برای Tweenهای وابسته به وضعیت فعلی المان.

🟡 2️⃣ ()getUnit

• کاربرد: استخراج واحد یک مقدار CSS یا مقدار Tween.

• ساختار:

gsap.getUnit(value)

مثال:

console.log(gsap.getUnit("50px")); // "px"
console.log(gsap.getUnit("2em"));  // "em"

• مفید برای Modifers یا Tweenهای dynamic که نیاز به حفظ واحد دارند.

🟠 3️⃣ ()selector

• کاربرد: ایجاد تابع انتخابگر (shorthand) برای المان‌ها، مشابه $() در jQuery.

• ساختار:

const q = gsap.utils.selector(scope);
let items = q(".box"); // تمام .boxها داخل scope

مثال:

let container = document.querySelector("#container");
let q = gsap.utils.selector(container);
q(".box").forEach(box => {
  gsap.to(box, { x: 100, duration: 1 });
});

• با این روش می‌توانید انتخابگرها را محدود به یک parent خاص کنید.

• بسیار کاربردی در React/Vue/SPA برای جلوگیری از اثر روی کل صفحه.

🟣 4️⃣ ()toArray

• کاربرد: تبدیل NodeList یا انتخابگر CSS به آرایه واقعی.

• ساختار:

gsap.utils.toArray(selectorOrNodeList)

مثال:

let boxes = gsap.utils.toArray(".box");
boxes.forEach((box, i) => {
  gsap.to(box, { y: i * 50, duration: 1 });
});

• NodeList معمولی قابلیت استفاده از برخی متدهای Array را ندارد، ()toArray آن را تبدیل به آرایه می‌کند.

• می‌توان مستقیماً Node یا selector string بدهید:

gsap.utils.toArray("#container .item");

🟤 ترکیب با Tween و Modifier

const boxes = gsap.utils.toArray(".box");
gsap.to(boxes, {
  x: (i, target) => gsap.getProperty(target, "x") + 100,
  duration: 1
});

• استفاده از ()getProperty برای خواندن مقدار فعلی و محاسبه مقدار جدید.

• ()selector برای محدود کردن انتخابگرها به parent.

✅ جمع‌بندی

این توابع، کنترل و دسترسی دقیق به DOM و ویژگی‌های المان‌ها را در GSAP راحت و سریع می‌کنند و برای انیمیشن‌های پویا، گروهی و responsive ضروری هستند.