Ir al contenido

Opciones y controles compartidos

Opciones de creación y controles modificables disponibles en todos los efectos.

Todos los efectos aceptan estas opciones de creación y devuelven el mismo EffectHandle. Las opciones específicas de cada efecto se explican en sus referencias individuales.

Usa el tipo exportado AttachmentOptions. Solo host es obligatorio. Los efectos salvo Burned paper amplían este tipo con ColorAttachmentOptions.

PropiedadTipoPredeterminado
host

Contenedor del efecto: un elemento HTML ya presente en la página, con una posición CSS distinta de static. Debe contener el elemento objetivo en el mismo documento; no puede ser el propio objetivo.

HTMLElementObligatorio
clock

Usa manual para controlar el tiempo con tu código o GSAP; auto lo avanza automáticamente.

'manual' | 'auto''manual'
motion

respect suprime la salida con movimiento reducido. static siempre dibuja un efecto inmóvil en el tiempo cero, con cualquier preferencia.

'respect' | 'static''respect'
seed

Semilla aleatoria fija. Permite repetir el patrón con el mismo tiempo, ajustes y objetivo capturado. No determina la cantidad de aleatoriedad ni garantiza píxeles idénticos entre dispositivos.

number0
time

Tiempo inicial del efecto en segundos. Acepta valores negativos.

number0
intensity

Intensidad inicial del efecto. Los valores aceptados se limitan al intervalo de 0 a 1; la respuesta visual depende del efecto.

number1
color

Color decorativo principal opcional para todos los efectos excepto Burned paper. Acepta #RGB, #RRGGBB, rgb(...) y rgba(..., 1). Omitirlo conserva los colores originales del efecto; asignar undefined los restaura.

string | undefinedOmitido (colores originales)

Todos los valores numéricos deben ser finitos. time, seed, intensity y los controles solo de creación deben ser representables como float32. Los controles artísticos modificables, incluso al crearlos, aceptan cualquier número finito y se limitan a 0–1; los demás valores no válidos generan un error antes de aplicar el límite. Para cambiar una opción de creación distinta de time o intensity, libera la instancia y crea otra.

Solo un efecto puede usar un objetivo a la vez. Las relaciones de contenedor no válidas y los objetivos superpuestos generan un error síncrono. Libera el efecto existente antes de aplicar otro al mismo objetivo, a uno de sus ancestros o a uno de sus descendientes. Esta restricción se refiere al árbol del DOM, no a cualquier superposición visual.

Lee y modifica estas propiedades de la instancia de efecto. Los cambios pueden leerse de inmediato. Cuando la salida está disponible, se dibujan en el siguiente fotograma sin volver a capturar el elemento.

PropiedadTipo
time

Tiempo del efecto en segundos. Permite avanzar y retroceder, incluso a tiempos negativos.

number
intensity

Intensidad del efecto, limitada al intervalo de 0 a 1 después de validar el valor. No es un ajuste universal de altura ni de opacidad.

number
color

Color decorativo principal opcional. Todos los efectos excepto Burned paper lo admiten; asigna undefined para recuperar los colores originales.

string | undefined

Todos los valores numéricos deben ser finitos. time e intensity deben ser representables como float32. intensity y los controles específicos se limitan a 0–1; estos últimos aceptan cualquier número finito. Una asignación no válida genera un error y conserva el valor anterior. Usa un solo controlador por propiedad: asignaciones directas, una línea de tiempo u otro controlador de animación.

Usa clock: ‘auto’ para la animación automática. domfx avanza el tiempo mientras puede dibujar el efecto, sin contar el tiempo en pausa, oculto o fuera de pantalla.

Usa clock: ‘manual’ para el control externo mediante tu código o GSAP. domfx nunca avanza el tiempo en este modo, ni siquiera después de resume(). Sigue observando el objetivo y programa el renderizado para el siguiente fotograma.

time elige un punto de la animación en segundos. No es un progreso de 0 a 1 ni el tiempo real transcurrido. Puedes retroceder o usar valores negativos. Deja cada propiedad a cargo de un solo controlador de animación.

El valor predeterminado motion: ‘respect’ suprime la salida cuando la persona solicita movimiento reducido. Cuando la preferencia vuelva a cambiar, llama explícitamente a retry(). No sustituye automáticamente la animación por un fotograma inmóvil.

motion: ‘static’ siempre dibuja un efecto inmóvil en el tiempo cero, con cualquier preferencia. Puedes seguir leyendo el valor asignado a time, pero no cambia el fotograma dibujado. La intensidad y las actualizaciones de captura siguen funcionando. resume() no lo anima.

Consulta estado y métodos del efecto para preparación, pausa, reanudación, actualización de captura, reintento y limpieza.