API de GSAP
Anima propiedades con GSAP o usa enlaces opcionales con valores iniciales fijos.
Animaciones nativas de propiedades
Sección titulada «Animaciones nativas de propiedades»Un tween es una animación que cambia los valores de las propiedades con el tiempo. Usa gsap.to(effect, { time, intensity, duration, ease }) o añade el mismo objetivo a una línea de tiempo. Usa clock: ‘manual’ al crear el efecto. No necesitas registrar un plugin de domfx ni importar @domfx/gsap para estas propiedades numéricas.
GSAP actualiza las propiedades públicas del efecto, incluso al saltar a un punto de la línea de tiempo sin ejecutar las funciones asociadas a sus eventos (callbacks). Las llamadas encadenadas a .to() parten de los valores anteriores. .from(), .fromTo(), las curvas de aceleración (ease, que definen el ritmo del cambio), repeat/yoyo, la sobrescritura de propiedades y gsap.killTweensOf(effect) siguen el comportamiento habitual de GSAP.
Mantén los valores dentro de los rangos de control del efecto. La instancia valida las asignaciones al ejecutarse; los tipos de GSAP no imponen estos rangos. intensity se limita en cada asignación, por lo que las curvas que rebasan el rango pueden hacer que la intensidad permanezca en uno de sus límites.
Elimina tus animaciones con kill() y libera el efecto durante la limpieza. Eliminar o completar una animación no libera su objetivo. Registra la limpieza de inmediato, incluso si la configuración aún está pendiente. Consulta la guía completa de GSAP para ver cómo hacerlo.
Enlaces opcionales con valores iniciales fijos
Sección titulada «Enlaces opcionales con valores iniciales fijos»Elige un enlace si necesitas valores iniciales fijos o sus funciones de limpieza. Para secuencias habituales, usa las animaciones nativas anteriores.
Importa bindEffect desde @domfx/gsap. Acepta cualquier EffectHandle sin liberar con control externo. Proporciona la instancia, una línea de tiempo GSAP bajo tu control y estas opciones:
| Propiedad | Tipo | Predeterminado |
|---|---|---|
timeTiempo de destino absoluto en segundos. Debe ser finito y representable como float32. | number | Obligatorio |
intensityIntensidad final finita. Se limita al intervalo de 0 a 1 antes de interpolar. | number | Obligatorio |
durationDuración de interpolación finita y no negativa, en segundos. Se acepta cero. | number | Obligatorio |
positionPosición de inserción en GSAP. Si se omite, se añade al final de la línea de tiempo. | gsap.Position | undefined |
disposeEffectDelega al enlace la responsabilidad de liberar el efecto, incluso al revertir el contexto. | boolean | false |
bindEffect(effect, timeline, options) devuelve un EffectBinding. Fija los controles iniciales al llamarla e interpola linealmente. Las asignaciones posteriores no cambian esos valores iniciales. binding.dispose() elimina su animación, conserva los últimos valores y libera el efecto solo con disposeEffect: true. La línea de tiempo sigue a cargo de quien la creó.
bindEffectAsync(promise, timeline, options) acepta una promesa de cualquier instancia de efecto y requiere disposeEffect: true. Devuelve un AsyncEffectBinding con dispose() y ready: Promise<void>, y libera los resultados que llegan después de cancelar. Usa context.revert() para limpiar el contexto GSAP.
Consulta la guía de GSAP para ver una secuencia completa y su limpieza.
Estos adaptadores animan objetos privados en lugar de la instancia de efecto: gsap.killTweensOf(effect) y la sobrescritura entre enlaces no afectan a esas animaciones. Varios enlaces creados juntos capturan los mismos controles iniciales; usa llamadas nativas a .to() para secuencias encadenadas normales.
Eliminar únicamente la línea de tiempo que proporcionaste no elimina la suscripción de liberación del enlace. Libera también el enlace. El ready de un enlace asíncrono espera la configuración del enlace o la limpieza de un resultado tardío, no la configuración inicial del propio efecto.
Puedes crear un enlace antes de que termine effect.ready. Las opciones no válidas, el control automático y las instancias ya liberadas producen un error síncrono; si falla la validación, sigues a cargo de liberar el efecto. Liberar un efecto elimina sus enlaces. Usa context.revert(), no context.kill(), para ejecutar la limpieza personalizada del contexto.