Ir al contenido

Controla el tiempo y la intensidad del efecto con una línea de tiempo propia.

Un tween de GSAP es un objeto de animación que cambia propiedades con el tiempo. Usa estas animaciones nativas con cualquier efecto de domfx y una línea de tiempo para ordenarlas. La instancia permite modificar las propiedades numéricas time e intensity. No necesitas registrar un plugin de domfx ni importar @domfx/gsap.

Sigue la guía de instalación y añade GSAP a tu aplicación. Este ejemplo usa Fire; sustituye su importación para usar otro efecto.

Prueba la secuencia

Una línea de tiempo mueve el texto y controla cinco efectos, letra por letra.

domfx

La reproducción necesita JavaScript y WebGPU. La secuencia y el texto original siguen visibles.

time (s)
0.00
rootColor
intensity
0.000.000.000.000.00
0.00

Cambiar la posición pausa la reproducción.

La secuencia
timeline.fromTo(host, { opacity: 0 }, {
  opacity: 1,
  duration: .4,
  ease: "none",
  immediateRender: false
}, 0);
timeline.fromTo(letters, { y: 70 }, {
  y: 0,
  duration: .8,
  ease: "back.out(2.2)",
  stagger: .06,
  immediateRender: false
}, 0);
timeline.addLabel("ignite", 1);
timeline.to(fires, {
  intensity: 1,
  duration: .7,
  ease: "power3.in",
  stagger: .14
}, "ignite");
timeline.addLabel("surge", 2.4);
timeline.to(fires, {
  rootColor: "#ffffff",
  tipColor: "#ffd27a",
  duration: .7,
  ease: "power1.in"
}, "surge");
timeline.to(fires, {
  rootColor: "#99ddff",
  tipColor: "#0066ff",
  duration: .8,
  ease: "power1.out"
}, "surge+=0.7");
timeline.to(letters, {
  y: -18,
  duration: .3,
  ease: "sine.inOut",
  yoyo: true,
  repeat: 1,
  stagger: .07
}, "surge+=0.3");
timeline.addLabel("burnOut", 4.2);
timeline.to(fires, {
  intensity: .08,
  duration: 1,
  ease: "power2.out",
  stagger: {
    each: .15,
    from: "end"
  }
}, "burnOut");
timeline.to(fires, {
  time: 6,
  duration: 6,
  ease: "none"
}, 0);

Esta es la secuencia que ejecuta el reproductor, con su escalonado y sus etiquetas. El ejemplo completo de abajo empieza con algo más pequeño: un objetivo y un efecto.

El reproductor da a cada letra su propio efecto con attachFire(letter, { host, clock: 'manual', intensity: 0, flameReach: 0.7 }) y después pasa las letras y los efectos a una sola línea de tiempo, de modo que stagger se aplica a ambos. Mueve, escala y atenúa el contenedor o la posición de las letras con libertad: el efecto las sigue sin una captura nueva. La rotación y la inclinación desactivan el efecto con unsupported-placement, y los cambios de opacidad solo en el objetivo no son compatibles, así que atenúa el contenedor.

El resto de esta guía empieza con algo más pequeño: un objetivo y un efecto.

Usa el index.html de instalación, incluido el contador de clics. Sustituye todo el contenido de main.ts por el siguiente módulo. En un componente, ejecútalo después de montar los elementos.

Crea el efecto con clock: ‘manual’ para que GSAP controle su tiempo. El contenedor aparece gradualmente en medio segundo; luego el efecto pasa del tiempo 0 al 4 y de intensidad 0.8 a 0.4 durante cuatro segundos. Anima la opacidad del contenedor para que el objetivo original y el efecto la compartan. Los cambios de opacidad solo en el objetivo no son compatibles.

import { gsap } from 'gsap';
import { attachFire } from '@domfx/browser';

const host = document.querySelector('#host');
const target = document.querySelector('#target');
const clicks = document.querySelector('#clicks');
if (!(host instanceof HTMLElement) || !target || !clicks) {
  throw new Error('Falta el contenedor, el objetivo o el contador');
}

let count = 0;
const onClick = () => { clicks.textContent = String(++count); };
target.addEventListener('click', onClick);

let disposed = false;
let fire: ReturnType<typeof attachFire> | undefined;
const timeline = gsap.timeline({ paused: true });
let unsubscribe: (() => void) | undefined;

function cleanup() {
  disposed = true;
  window.removeEventListener('pagehide', cleanup);
  target?.removeEventListener('click', onClick);
  unsubscribe?.();
  timeline.revert();
  fire?.dispose();
}

// Antes de llamar a setup, registra también cleanup para que se ejecute al desmontar el componente.
window.addEventListener('pagehide', cleanup, { once: true });

const setup = async () => {
  await document.fonts.ready;
  if (disposed) { return; }

  fire = attachFire(target, {
    host, clock: 'manual', motion: 'respect',
    time: 0, intensity: 0.8, seed: 314,
  });
  unsubscribe = fire.onDispose(() => timeline.revert());
  // El objetivo y el efecto comparten la opacidad del contenedor.
  timeline.from(host, {
    opacity: 0,
    duration: .5,
    immediateRender: false
  });
  timeline.addLabel("ignite", .5);
  timeline.to(fire, {
    time: 4,
    intensity: .4,
    duration: 4,
    ease: "none"
  }, "ignite");

  await fire.ready;
  if (disposed) { return; }
  if (fire.lifecycle !== 'active') {
    console.info(fire.reason);
    return;
  }

  timeline.play();
};

void setup();

Ejecuta pnpm dev y abre la URL indicada. El botón aparece gradualmente; después, sus llamas cambian durante cuatro segundos. Pulsarlo aumenta el contador. Para producción, ejecuta pnpm build y después pnpm preview.

Después de preparar el efecto, usa timeline.play(), pause(), seek() y reverse(). En timeline.seek(2.5), el tiempo del efecto es 2 y la intensidad 0.6. Retroceder a 1.5 da tiempo 1 e intensidad 0.7. Los saltos a un punto de la línea de tiempo también actualizan estas propiedades, aunque no ejecuten las funciones de devolución de llamada (callbacks); no hace falta copiar sus valores en onUpdate.

Encadena llamadas a .to() para animar desde los destinos anteriores. Usa .from() o .fromTo() para indicar valores iniciales explícitos, teniendo en cuenta su renderizado inmediato predeterminado. Los segmentos .fromTo() posteriores suelen necesitar immediateRender: false. ease define cómo varía la velocidad de la animación. ease, repeat, yoyo, overwrite y timeScale() siguen las convenciones normales de GSAP.

gsap.killTweensOf(fire, ‘intensity’) detiene solo esa propiedad; no libera el efecto ni detiene una animación de tiempo. Usa un controlador por propiedad y mantén los valores dentro de los rangos de control.

Todos los efectos excepto Burned paper permiten modificar color. Inicialízalo con una cadena de color opaca explícita y admitida, y después usa extremos opacos explícitos con fromTo(); la paleta original es undefined, no un valor entre el que interpolar. Esto cambia la decoración y conserva el objetivo y la opacidad del efecto.

fire.color = '#ff6600';
const colorTween = gsap.fromTo(
fire,
{ color: '#ff6600' },
{ color: '#6699ff', duration: 2, ease: 'power1.inOut' },
);

Para cambios posteriores, usa gsap.to(fire, { color: '#ff6600', duration: 2 }). Al limpiar, llama a colorTween.kill() antes de liberar el efecto. Para recuperar la paleta original, detén las animaciones de color y asigna fire.color = undefined.

rootColor y tipColor de Fire se animan igual, sin plugin: asigna primero un color explícito y después usa fromTo(). Ninguno se puede definir mientras color esté definido.

fire.rootColor = '#fff5a3';
fire.tipColor = '#ff1701';
const flameTween = gsap.fromTo(
fire,
{ rootColor: '#fff5a3', tipColor: '#ff1701' },
{ rootColor: '#99ddff', tipColor: '#0066ff', duration: 2 },
);

Registra cleanup() en el mecanismo de desmontaje de tu framework antes de llamar a setup(). Elimina los controladores de eventos, revierte y elimina la línea de tiempo propia y libera el efecto. Funciona incluso si las fuentes o ready siguen pendientes. La suscripción de liberación también restaura la opacidad si se elimina el objetivo. Al volver a montar, crea variables, efecto y línea de tiempo nuevos.

Si usas una línea de tiempo ajena, conserva referencias a tus animaciones hijas y elimina solo esas animaciones con kill(); su propietario limpia la línea de tiempo y las demás animaciones. Terminar, eliminar o sobrescribir una animación no libera los recursos del objetivo.

Crea las animaciones dentro de gsap.context() y devuelve una función de limpieza explícita. Regístrala de forma síncrona; el contexto no registra automáticamente el trabajo creado después en funciones que esperan promesas.

Si adaptas este ejemplo a un contexto, devuelve cleanup desde su función de configuración y llama a context.revert() al desmontar.

@domfx/gsap proporciona bindEffect y bindEffectAsync para enlaces que conservan los valores iniciales de los controles, con responsabilidad explícita de limpieza. La función asíncrona libera con seguridad los resultados que llegan después de cancelar.

Estas funciones capturan los controles iniciales al crearse y animan objetivos proxy privados. Difieren de las llamadas nativas encadenadas a .to(), de la eliminación de animaciones por objetivo con gsap.killTweensOf() y de la sobrescritura. Consulta la referencia de enlaces con valores iniciales fijos si necesitas ese contrato; para secuencias normales, prefiere animaciones nativas.

El ejemplo principal inicia la reproducción solo cuando el efecto está activo. Si WebGPU no está disponible o se solicita movimiento reducido, conserva el objetivo original. Corrige la condición, espera a fire.retry(), consulta su estado y reproduce la línea de tiempo existente. El reintento conserva los controles; no necesita otra animación.

Cada referencia de efecto comienza con una vista previa interactiva de los controles compartidos. Consulta la API de GSAP y solución de problemas para más detalles.