Nodes

Image

Een afbeelding waar jouw data naar wijst, of een die een generatie-endpoint produceert.

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
Nodesoort: image
Categorie: Media
Wordt opgelost: Both
Children: None.

Optie	Type	Wat het doet
`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` verplicht	`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` verplicht	`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.

Elk veld is een prop

src, alt, width en height accepteren elk een gewone waarde of een functie van je data. Een handtekening die per vestiging verschilt, een logo per merk, een foto op kenmerk — het blijft allemaal binnen de node in plaats van een vertakking in het template te worden:

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 wordt path

De optie heet src; de opgeloste node noemt het path. Klap Waartoe het wordt opgelost open bij de eerste variant hieronder om het te zien.

Dynamische afbeeldingen

Een dynamische afbeelding wordt beschreven in plaats van aangeleverd, en gebruikt dezelfde promptslots als een dynamische alinea.

negativePrompt verdient hier meer dan waar ook zijn plek. Gegenereerde beelden gaan op voorspelbare manieren mis — ingebakken tekst, verzonnen logo’s, herkenbare gezichten — en het slot sluit die in één keer uit, in de node.

Varianten

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 ↗

Waartoe het wordt opgelost

De node zoals hij in het DocumentModel verschijnt: de JSON die een renderer aangereikt krijgt. Geen opmaak, geen lay-out.

{
  "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 ↗

Waartoe het wordt opgelost

De node zoals hij in het DocumentModel verschijnt: de JSON die een renderer aangereikt krijgt. Geen opmaak, geen lay-out.

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

Wat er aan het endpoint wordt gevraagd

Opgelost tegen dezelfde voorbeelddata. Een previewbuild stopt bij de placeholder; een build op het moment van de aanvraag stuurt deze mee.

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.

Aantekeningen

Alleen een data:-URI reist mee. Die draagt de bytes, dus een document dat elders wordt geschreven heeft de afbeelding nog. Een pad of http-URL wordt op het scherm getekend, waar een browser hem kan ophalen, maar belandt in een .docx als een notitie: bij het inpakken wordt niets opgehaald of van schijf gelezen, want de machine die het document schrijft is niet die waar het bestand stond.
Word sluit een SVG niet alleen in — geef er een raster bij via fallbackSrc. Het scherm tekent de SVG, het Word-bestand krijgt het raster.
alt is hoe dan ook de moeite waard: het beschrijft de afbeelding in het Word-bestand, en het is wat een node zonder afbeelding in de plaats print.

Deze pagina bewerken op GitHub ↗ Deze pagina als Markdown lezen