Ir al contenido

Fire

Llamas cálidas y chispas se elevan desde la forma visible.

La vista previa necesita JavaScript y WebGPU.

Categoría
Energía
Función
attachFire
Opciones
FireOptions
Paquete
@domfx/browser

Uso

attachFire(target: Element, options: FireOptions): FireEffectHandle

Devuelve una instancia de efecto de inmediato. Las importaciones son seguras durante el renderizado en servidor; llama a la función en el navegador después de montar los elementos. La guía de uso independiente incluye el HTML y CSS necesarios.

import { attachFire } from '@domfx/browser';
import type { FireOptions } from '@domfx/browser';

// Ejecuta después del montaje; host contiene target y tiene position: relative.
const options: FireOptions = {
  host, clock: 'auto', intensity: 0.8,
  flameReach: 0.2,
  emberDensity: 1,
};
const effect = attachFire(target, options);
// Llama también a effect.dispose() al desmontar el componente.
window.addEventListener('pagehide', () => effect.dispose(), { once: true });
await effect.ready;
if (effect.lifecycle !== 'active') {
  console.info(effect.reason, effect.reasonDetail);
}

Opciones del efecto

FireOptions amplía AttachmentOptions con dos opciones geométricas de creación excluyentes.

PropiedadTipoPredeterminado
flameReach

Fracción finita no negativa de la altura del border box sin transformar, incluidos los márgenes transparentes. 0.1 equivale a 10 px CSS en un objetivo de 100 px y a 40 px en uno de 400 px. Limita la distancia exterior y el recorrido ascendente; no garantiza una punta visible en cada fotograma. La intensidad cambia la fuerza, sin cambiar el alcance ni el detalle fino. Cero produce salida transparente. Solo al crear la instancia; se recalcula en cada captura tras un cambio de tamaño.

numberOmitido (apariencia predeterminada)
PropiedadTipo y rangoPredeterminado
emberDensity

Selecciona cuántas brasas aparecen sin cambiar el tamaño ni el recorrido de las restantes. Es una opción de creación: usa una instancia nueva para cambiarla. La instancia expone el valor resuelto como solo lectura.

number · 0–11

Color de la base y Color de las puntas colorean la llama desde su base hasta sus extremos. También son propiedades modificables de la instancia y sustituyen la paleta original de tres paradas por una mezcla de dos colores. No se pueden combinar con color: crear Fire con ambos, o escribir uno mientras el otro está definido, lanza invalid-fire-parameter y conserva el valor anterior. Para cambiar de modo, asigna primero undefined.

PropiedadTipoSin definir
rootColor

Color de la base de la llama. Usa el mismo formato que color: hexadecimal, rgb() o rgba() opaco. El getter devuelve rgb(...) normalizado, o undefined si no está definido.

string#fff5a3
tipColor

Color de los extremos de la llama y de las brasas. Con cualquiera de los dos colores definido, las brasas usan este color o su valor predeterminado; sin ninguno, conservan #ffc747.

string#ff1701

Puedes definir solo un color: el otro usa su valor predeterminado. Si no defines ninguno, la salida no cambia. La posición en la mezcla incluye la densidad de la llama, así que describe de la base a los extremos, no una altura exacta. Escribir estos colores conserva la captura, la geometría y los recursos de GPU.

Opciones compartidas

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.

Controles

Con flameReach, cambia la fuerza visual sin cambiar el alcance ni el detalle fino. Omitir flameReach conserva la apariencia predeterminada, donde la intensidad también cambia el alcance de la llama.

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.

Consulta la sección sobre animación automática y control externo y la guía de GSAP. La referencia de la instancia de efecto documenta el estado, las actualizaciones de captura y la liberación de recursos.

Límites

El efecto sigue la forma visible capturada, incluidos los huecos y las regiones separadas. Una imagen opaca tiene una forma rectangular. La capa decorativa conserva intacto el contenido original.

Solo las opciones enumeradas son públicas. Todos los efectos salvo Burned paper permiten configurar un color decorativo principal; los degradados, la cantidad de partículas y el procesamiento del elemento completo no se pueden configurar. Mantén utilizable el contenido original cuando la salida no esté disponible. Para los límites de WebGPU, captura y composición, consulta compatibilidad con navegadores y solución de problemas.

rootColor y tipColor son la excepción a un único color principal, con dos extremos fijos y sin más paradas. Se mezclan en sRGB con codificación gamma, igual que los degradados CSS predeterminados y las animaciones de cadenas de GSAP. Por eso, los pares complementarios pasan por gris en su punto medio: #0066ff y #ff9900 se promedian en torno a #808080.

flameReach reserva un margen simétrico independiente de la intensidad: alcance + 2 px CSS de pintura exterior + una protección de muestreo de 2 px CSS y 2 píxeles de trama, redondeado hacia arriba y con un mínimo de 8 px CSS. Solo admite cajas descendientes contenidas y pintura dentro del border box más 2 px CSS; no admite sombras, filtros, contornos ni pseudoelementos generados. Comprueba todo el alfa capturado y rechaza el margen insuficiente con missing-exterior. Los límites existentes de un millón de píxeles, memoria y dimensiones del dispositivo pueden producir capture-budget u otro estado no disponible; no se recorta el alcance ni se reduce la calidad. La conversión fraccional de trama y el DPR se aplican una vez; las traslaciones y escalas positivas admitidas solo cambian la colocación.

Compara todos los efectos en la galería, uno junto a otro.