Guía
Plantillas
HTML de verdad dentro de TypeScript. La regla que decide qué es reactivo, y todo lo que se puede escribir en una plantilla.
HTML dentro de TypeScript
const tarjeta = view`
<article class="tarjeta">
<h2>${titulo}</h2>
<p>${() => resumen()}</p>
</article>`;view no existe en tiempo de ejecución: el compilador la sustituye por las
llamadas que construyen ese árbol. Lo que devuelve es el elemento raíz, un
HTMLElement corriente: se puede pasar a cualquier API del DOM.
Los atributos son los del HTML: class, for, onclick, tabindex. El
marcado de cualquier sitio se copia y se pega tal cual.
La regla única
Una closure es reactiva. Cualquier otra expresión se evalúa una vez.
| Escribes | Qué ocurre |
|---|---|
${cuenta()} |
Inserta el valor actual. No vuelve a mirarlo. |
${() => cuenta()} |
Crea un efecto: ese texto sigue al signal. |
class="fijo" |
Atributo estático. |
class=${expresion} |
Se evalúa una vez, al construir. |
class=${() => …} |
Atributo reactivo. |
onclick=${manejador} |
Listener del DOM. Se quita solo al desmontar. |
prop:value=${() => …} |
Escribe la propiedad, no el atributo. |
class:activa=${() => …} |
Pone y quita esa clase, sin tocar las demás. |
ref=${(nodo) => …} |
Entrega el elemento recién creado a una función. |
La distinción es sintáctica: mirando la plantilla se sabe qué puede cambiar, sin conocer los tipos. De ahí sale la trampa más fácil de pisar:
function Metrica(props: { valor: () => string }) {
return view`<span>${props.valor}</span>`; // ✗ pinta «() => …»
return view`<span>${() => props.valor()}</span>`; // ✓ sigue al dato
}props.valor es una función, pero ahí no hay una closure escrita, y la
regla mira lo que está escrito. Un valor reactivo se reenvía llamándolo dentro
de otra closure.
Texto
Un hueco dentro de una etiqueta es siempre texto, escapado:
view`<p>${"<b>no es negrita</b>"}</p>`; // se ve el texto tal cualnull y undefined pintan una cadena vacía; todo lo demás pasa por
String(). Para componer nodos no se usa un hueco sino un
componente.
Atributos
Un atributo reactivo con false, null o undefined desaparece, y con
true queda vacío. Así se expresan los booleanos del HTML, que existen o no
existen:
view`<button disabled=${() => enviando()}>Guardar</button>`;
// enviando() === true → <button disabled>
// enviando() === false → <button>URLs javascript:
Una URL que llega por un hueco a href, src, action, formaction o
data no se escribe si es javascript:: en un enlace se ejecutaría al hacer
clic, y casi siempre viene de datos de fuera.
view`<a href=${payment.url}>Pagar</a>`;
// payment.url === "javascript:alert(document.cookie)"
// → href="javascript:throw new Error('Ascua blocked a javascript: URL')"Queda una URL inofensiva y un aviso en la consola, como en React 19. Escrita
literal en la plantilla —href="javascript:void 0"— no se toca: esa la
decidió quien escribió el código. Lo demás (https:, mailto:, rutas
relativas) pasa igual. Para aceptar solo http(s), hay que validarlo antes.
srcdoc
srcdoc es una página entera que corre con el origen del sitio: por un hueco,
es meter HTML de fuera en la página. Solo se escribe si el <iframe> lleva
sandbox escrito en la plantilla, y no con allow-scripts y
allow-same-origin juntos, que le dejan quitarse el sandbox:
view`<iframe sandbox srcdoc=${correo.html}></iframe>`; // se escribe, sin scripts
view`<iframe srcdoc=${correo.html}></iframe>`; // srcdoc="" y aviso en la consolaUn sandbox vacío es lo que conviene para mostrar HTML ajeno (un correo, una
vista previa): sin scripts, sin formularios y en un origen aparte. Lo mismo
vale en view!, la vía Rust.
Eventos
view`<input oninput=${(e: Event) => texto.set((e.target as HTMLInputElement).value)}>`;on + el nombre del evento del DOM, en minúsculas: onclick, oninput,
onsubmit, onkeydown. El manejador recibe el evento del navegador y se
quita solo cuando el componente se libera.
Los eventos que suben por el árbol —click, input, change, keydown,
los de puntero y ratón, focusin…— se delegan, como en Solid y Svelte: el
manejador queda en el nodo y un solo listener por tipo, en el documento, lo
encuentra al subir. Crear mil filas no son dos mil addEventListener. Por
dentro se comporta como uno normal: currentTarget es el nodo del manejador y
stopPropagation corta la subida.
Una diferencia: un evento disparado a mano tiene que subir para llegar,
new Event("input", { bubbles: true }). Los del navegador ya lo hacen, y los
de ascua-testing también. Los que no suben —scroll,
focus, load— van con un addEventListener de siempre.
Formularios: prop:
El atributo value de un <input> es su valor inicial: deja de mandar en
cuanto el usuario teclea. La propiedad manda siempre. Por eso value,
checked y selected se escriben con prop::
const texto = signal("");
view`
<form onsubmit=${enviar}>
<input prop:value=${() => texto()}
oninput=${(e: Event) => texto.set((e.target as HTMLInputElement).value)}>
<button type="button" onclick=${() => texto.set("")}>Vaciar</button>
</form>`;Con value= en vez de prop:value=, el botón de vaciar dejaría de funcionar
en cuanto alguien escribiera.
bind:, en los dos sentidos
Lo de arriba es tan común que tiene atajo. bind: ata el campo a un signal:
lo que el signal diga se ve, y lo que el usuario escriba va al signal.
const nombre = signal("");
const acepta = signal(false);
const edad = signal(30);
view`
<form>
<input bind:value=${nombre}>
<input type="checkbox" bind:checked=${acepta}>
<input type="number" bind:valueAsNumber=${edad}>
<select bind:value=${pais}>…</select>
</form>`;Se le pasa el signal, no una closure. value escucha input, checked
escucha change, y valueAsNumber guarda un número (vacío es NaN). Los
tipos se comprueban: atar bind:value a un Signal<number> es un error.
Clases que van y vienen: class:
class es un atributo como otro cualquiera: hacerlo reactivo obliga a
construir la lista entera en cada cambio. Para una clase suelta está class::
view`<li class="fila" class:hecha=${() => tarea.hecha()}>…</li>`;fila se queda siempre, hecha aparece y desaparece, y el scope del CSS no se
pisa.
Quedarse con un nodo: ref
let campo: HTMLInputElement | undefined;
const formulario = view`
<form>
<input ref=${(nodo: HTMLInputElement) => (campo = nodo)}>
</form>`;
campo?.focus();El compilador llama a ref justo después de crear el elemento. Se ejecuta en
cada construcción: tras un <Show> que reconstruye, la variable apunta al nodo
nuevo.
SVG y MathML
const icono = view`
<svg viewBox="0 0 24 24" width="24" height="24">
<circle cx="12" cy="12" r=${() => radio()} class:activo=${() => activo()}/>
</svg>`;Lo que va dentro de <svg> se crea en el espacio de nombres de SVG, y lo de
<math> en el de MathML: un <circle> hecho como un elemento HTML no se
dibuja. Dentro de <foreignObject> se vuelve al HTML. Los atributos y
class: funcionan igual; las mayúsculas de viewBox o linearGradient se
respetan.
Un componente que devuelve un trozo de dibujo para el <svg> de otro —un
<g>, un <path>— no tiene un <svg> encima que lo diga. Para esos, las
etiquetas que solo existen en SVG se reconocen solas. Las que también son HTML
(<a>, <title>, <style>) no pueden saberlo: van dentro de un <g>.
Para enlazar, href a secas; xlink:href es de SVG 1.1 y no hace falta.
Límites, y por qué
- Una plantilla tiene un único elemento raíz. Es lo que permite que montar,
desmontar e hidratar sean operaciones sobre un nodo. Donde los fragmentos
hacen falta —el contenido de un componente, una rama de
<Show>— sí están. ${expr}nunca inserta un nodo. Distinguir por el tipo del valor sería adivinar la intención; para componer, un componente.<Show>y<For>necesitan un padre donde anclarse, porque lo que producen es un marcador dentro de él. No pueden ser la raíz; en la rama de otro<Show>, el padre es el de ese<Show>.- Los comentarios
<!-- … -->desaparecen al compilar, con lo que haya dentro, huecos incluidos: no llegan al DOM. - Los espacios entre etiquetas no cuentan. Un texto que es solo espacios
entre dos elementos se descarta, como hace cualquier minificador de HTML. Si
un espacio importa, va dentro del texto:
<b>uno</b>${" "}<b>dos</b>.
html, para que el editor coloree
Una plantilla es una cadena, así que el editor no colorea el marcado por su
cuenta. Las extensiones que sí lo hacen —lit-html, es6-string-html— buscan la
etiqueta html, y el compilador acepta los dos nombres:
const boton = html`<button class="grande">Hola</button>`; // igual que viewQué sale del compilador
view`<p>${() => cuenta()}</p>`;se compila a:
const _$t0 = _$tpl(["p", 0, [""]], [[], [0]], ["p", "#text"],
(r) => { const n0 = r.firstChild; return [r, n0]; }); // arriba, una vez
const [_n0, _n1] = _$clone(_$t0);
_$bindtxt(_n1, () => cuenta());La parte fija es una plantilla que se clona; el texto viene en ella, vacío, y un efecto escribe la cuenta sobre él. Se puede ver con cualquier archivo en el playground. Es una propiedad buscada: si el resultado del compilador no se puede leer, la magia volvió por la puerta de atrás.