Nodos

Image

Una imagen a la que apuntan tus datos, o una que produce un endpoint de generación.

A static image points at something you hold — a signature, a logo, a site photograph — with every field able to vary per recipient. A dynamic image describes what is wanted and leaves the endpoint to make it.

Helpers: Image
Clase de nodo: image
Categoría: Medios
Se resuelve: Both
Hijos: None.

Opción	Tipo	Qué hace
`id`	`string`	Stable address for the node. Engines target it and build artifacts diff on it, so treat a rename as a breaking change. Optional: a node without one takes an id from where it sits, which is what keeps branches and loops from forcing you to invent names. Two nodes claiming one id is an error rather than a race.
`src` obligatorio	`string`	Static only. Lands on the node as `path`. A `data:` URI carries the bytes and is the only form that survives into a DOCX; a path or URL draws on screen only.
`fallbackSrc`	`string`	Static only. A raster to embed in place of an SVG, which Word will not take alone. Screen renderers ignore it and draw the SVG.
`alt`	`string`	Static only. Alternative text, carried into the DOCX — and the words printed in the frame when there is no picture yet.
`width`	`number`	Static only. Rendered width in points, honoured by both renderers.
`height`	`number`	Static only. Rendered height in points, on the same terms as `width`.
`placeholder`	`string`	Dynamic only. What previews show in place of generated content. Also settable with `useSetPlaceholders`. Optional, but a document that reads badly without one cannot be reviewed.
`generalPrompt` obligatorio	`string`	Dynamic only. What this node should say.
`infoPrompt`	`string`	Dynamic only. Context the model should have but should not restate.
`negativePrompt`	`string`	Dynamic only. What to avoid — claims, tones, or facts it must not invent.
`systemPrompt`	`string`	Dynamic only. Role and voice, applied ahead of the other prompts.
`examplePrompt`	`string`	Dynamic only. What a good answer looks like, written out as finished text. Shown last, because it is what the answer gets measured against.
`derivers`	`DeriverInvocation[]`	Values the engine computes before the node resolves, written to `derived.*` and readable from a template token. Built with `derive()`. These survive publishing and run per document — use them for anything computed from request data. `useDeriver` runs one during the build instead.

Cada campo es una prop

src, alt, width y height son props simples, calculadas a partir del estado antes de devolver el elemento. Una firma que cambia según la oficina, un logotipo por marca, una fotografía indexada por referencia — todo eso se queda dentro del componente en lugar de convertirse en una bifurcación en la plantilla:

export const Signature: Image = () => {
  const [state] = useState((data: MemberData) => ({
    src: data.signatureUrl,
    manager: data.managerName,
  }));

  return (
    <Image id="signature" src={state.src} alt={`Signed by ${state.manager}`} width={180} />
  );
};

src pasa a ser path

La prop es src; el nodo resuelto la llama path. Despliega En qué se resuelve en la primera variante de abajo para verlo.

Imágenes dinámicas

Una imagen dinámica se describe en lugar de suministrarse, y admite las mismas ranuras de prompt que un párrafo dinámico.

negativePrompt se gana su sitio aquí más que en ningún otro lado. Las imágenes generadas fallan de formas predecibles — texto incrustado, logotipos inventados, caras reconocibles — y la ranura las descarta de una vez, en el nodo.

Variantes

Static

src/nodes/image/static.node.tsx

A signature whose file and caption both follow the data.

import { Image, useState } from "docxcelerate/template";
import type { SampleData } from "../sample-data.ts";

/**
 * Every field is a plain prop, computed from state before the element is
 * returned — so a signature that varies by manager needs no branching in the
 * template that places it.
 */
export const Signature: Image = () => {
  const [state] = useState((data: SampleData) => ({
    src: data.signatureUrl,
    manager: data.managerName,
  }));

  return (
    <Image
      id="signature"
      src={state.src}
      alt={`Signed by ${state.manager}`}
      width={180}
      height={60}
    />
  );
};

image · static Open ↗

En qué se resuelve

El nodo tal como aparece en el DocumentModel: el JSON que recibe un renderizador. Sin estilos, sin maquetación.

{
  "id": "signature",
  "kind": "image",
  "mode": "static",
  "path": "assets/signature-lindqvist.png",
  "alt": "Signed by Tomas Lindqvist",
  "width": 180,
  "height": 60
}

Dynamic

src/nodes/image/dynamic.node.tsx

Described rather than supplied, with the failure modes fenced off.

import { Image, useSetPlaceholders, useSetPrompts, useState } from "docxcelerate/template";
import type { SampleData } from "../sample-data.ts";

/**
 * The same prompt set as a dynamic paragraph, for artwork the engine produces
 * rather than something you hold. The placeholder is what previews show, so
 * the layout is settled before any image exists.
 */
export const CentrePhoto: Image = () => {
  const [state] = useState((data: SampleData) => ({ centreName: data.centreName }));

  useSetPrompts({
    generalPrompt: `A wide daylight photograph of the entrance to ${state.centreName}, ` +
      `people arriving, no text overlay.`,
    negativePrompt: "No logos, no recognisable faces, no stock-photo staging.",
  });

  useSetPlaceholders(`Photograph of ${state.centreName}`);

  return <Image id="centre-photo" />;
};

image · dynamic Open ↗

En qué se resuelve

El nodo tal como aparece en el DocumentModel: el JSON que recibe un renderizador. Sin estilos, sin maquetación.

{
  "id": "centre-photo",
  "kind": "image",
  "mode": "dynamic",
  "placeholder": "Photograph of Riverside Leisure Centre"
}

Qué se le pide al endpoint

Resuelto con los mismos datos de ejemplo. Una compilación de vista previa se detiene en el marcador de posición; una compilación en el momento de la petición envía estos.

general: A wide daylight photograph of the entrance to Riverside Leisure Centre, people arriving, no text overlay.
negative: No logos, no recognisable faces, no stock-photo staging.

Notas

Solo viaja una URI data:. Lleva los bytes, así que un documento escrito por un motor en otra parte sigue teniendo la imagen. Una ruta o una URL http se dibuja en pantalla, donde un navegador puede descargarla, pero en un .docx queda como una nota: al empaquetar no se descarga ni se lee nada del disco, porque la máquina que escribe el documento no es aquella donde estaba el archivo.
Word no incrusta un SVG por sí solo: dale un ráster con fallbackSrc. La pantalla dibuja el SVG y el archivo de Word recibe el ráster.
Vale la pena escribir alt en cualquier caso: describe la imagen en el archivo de Word, y es lo que imprime un nodo que aún no tiene imagen.

Editar esta página en GitHub ↗ Leer esta página en Markdown