# 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»](#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](/docs/es/api/shared/#control-playback). 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](/docs/es/gsap/) para ver cómo hacerlo.

## Enlaces opcionales con valores iniciales fijos

[Sección titulada «Enlaces opcionales con valores iniciales fijos»](#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 |
| ---------------------------------------------------------------------------------------------------------- | --------------- | -------------- |
| `time` Tiempo de destino absoluto en segundos. Debe ser finito y representable como float32.               | `number`        | Obligatorio    |
| `intensity` Intensidad final finita. Se limita al intervalo de 0 a 1 antes de interpolar.                  | `number`        | Obligatorio    |
| `duration` Duración de interpolación finita y no negativa, en segundos. Se acepta cero.                    | `number`        | Obligatorio    |
| `position` Posición de inserción en GSAP. Si se omite, se añade al final de la línea de tiempo.            | `gsap.Position` | `undefined`    |
| `disposeEffect` Delega 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](/docs/es/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.
