Узлы

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.

Хелперы: Image
Вид узла: image
Категория: Медиа
Разрешается: Both
Дочерние узлы: None.

Опция	Тип	Что делает
`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` обязательно	`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` обязательно	`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.

Каждое поле — это проп

src, alt, width и height принимают либо обычное значение, либо функцию от ваших данных. Подпись, различающаяся по офисам, логотип для каждого бренда, фотография по номеру дела — всё это остаётся внутри узла, а не превращается в ветвление в шаблоне:

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 становится path

Опция называется src; в разрешённом узле она называется path. Разверните Во что это разрешается у первого варианта ниже, чтобы увидеть это.

Динамические изображения

Динамическое изображение описывается, а не передаётся, и принимает те же слоты промптов, что и динамический абзац.

Именно здесь negativePrompt оправдывает себя как нигде. Сгенерированные изображения портятся предсказуемо — впечатанный текст, выдуманные логотипы, узнаваемые лица, — и этот слот исключает всё это один раз, прямо в узле.

Варианты

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 ↗

Во что это разрешается

Узел в том виде, в каком он попадает в DocumentModel: JSON, который получает рендерер. Без стилей и без вёрстки.

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

Во что это разрешается

Узел в том виде, в каком он попадает в DocumentModel: JSON, который получает рендерер. Без стилей и без вёрстки.

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

О чём просят эндпоинт

Разрешено на тех же тестовых данных. Сборка предпросмотра останавливается на заполнителе; сборка во время запроса отправляет их.

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.

Примечания

Переносится только data:-URI. Он несёт байты, поэтому документ, написанный движком в другом месте, всё ещё содержит картинку. Путь или http-адрес рисуется на экране, где браузер может его загрузить, но в .docx попадает лишь заметкой: при упаковке ничего не загружается и не читается с диска — машина, которая пишет документ, не та, где лежал файл.
Word не встраивает SVG сам по себе: дайте растр через fallbackSrc. Экран рисует SVG, а файл Word получает растр.
alt стоит написать в любом случае: он описывает картинку в файле Word и печатается вместо узла, у которого картинки ещё нет.

Изменить эту страницу на GitHub ↗ Читать эту страницу в Markdown