# Image

> Ein Bild, auf das Ihre Daten zeigen, oder eines, das ein Generierungs-Endpoint erzeugt.

Source: https://docxcelerate.com/de/docs/nodes/image/

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.

> **Was die Renderer heute tun:** Both shipped renderers print a labelled frame in place of the picture — `[image: <alt>]` in the DOCX, a dashed box in the browser. The node carries its path, alt and size through unchanged.

- **Helper:** `Image`
- **Node-Art:** `image`
- **Kategorie:** Medien
- **Wird aufgelöst:** Both
- **Kinder:** None.

| Option | Typ | Was sie bewirkt |
| --- | --- | --- |
| `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` _erforderlich_ | `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` _erforderlich_ | `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. |

## Jedes Feld ist ein Prop

`src`, `alt`, `width` und `height` sind einfache Props, aus dem State berechnet,
bevor das Element zurückgegeben wird. Eine Unterschrift, die je Standort
abweicht, ein Logo je Marke, ein Foto nach Aktenzeichen — all das bleibt in der
Komponente, statt zu einer Verzweigung im Template zu werden:

```tsx
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} />
  );
};
```

## Aus src wird path

Das Prop heißt `src`; der aufgelöste Node nennt sie `path`. Klappen Sie *Wozu
es aufgelöst wird* bei der ersten Variante unten auf, um es zu sehen.

## Dynamische Bilder

Ein dynamisches Bild wird beschrieben statt geliefert und nimmt dieselben
Prompt-Slots wie ein dynamischer Absatz.

`negativePrompt` verdient hier seinen Platz mehr als irgendwo sonst. Generierte
Bilder scheitern auf vorhersehbare Weise — eingebackener Text, erfundene Logos,
erkennbare Gesichter — und der Slot schließt das einmalig aus, im Node.

## Varianten

### Static

A signature whose file and caption both follow the data.

Source: `src/nodes/image/static.node.tsx`

```tsx
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}
    />
  );
};
```

**Wozu es aufgelöst wird**

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

### Dynamic

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

Source: `src/nodes/image/dynamic.node.tsx`

```tsx
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" />;
};
```

**Wozu es aufgelöst wird**

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

**Was der Endpoint gefragt wird**

- `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.

## Anmerkungen

- **Nur eine `data:`-URI reist mit.** Sie trägt die Bytes, also hat auch ein
  anderswo geschriebenes Dokument das Bild noch. Ein Pfad oder eine http-URL
  wird am Bildschirm gezeichnet, wo ein Browser sie laden kann, landet in einer
  `.docx` aber nur als Notiz: beim Packen wird nichts geladen und nichts von
  der Platte gelesen, denn die Maschine, die das Dokument schreibt, ist nicht
  die, auf der die Datei lag.
- Word bettet ein SVG nicht allein ein — gib ihm ein Raster über `fallbackSrc`.
  Der Bildschirm zeichnet das SVG, die Word-Datei bekommt das Raster.
- `alt` lohnt sich in beiden Fällen: es beschreibt das Bild in der Word-Datei,
  und ein Node, der noch kein Bild hat, druckt es an dessen Stelle.