Referenz der Einstellungen

Einstellungen steuern alles an einem Rendering, was nicht Markup ist: Papier, Ränder, Kopf- und Fußzeilen, Bildgröße, Warten, PDF-Metadaten und Standardwerte für die Formatierung. Sie werden mit jeder Version einer Vorlage gespeichert und lassen sich pro Anfrage überschreiben:

• Im Editor schreibt sie das Panel Seiteneinrichtung: Papier, Ränder, Höhe und Innenabstand von Kopf- und Fußzeile, Skalierung, Hintergrund, CSS-Seitengröße, Tailwind, Bildgröße und -format, Locale, Zeitzone und Währung sowie die Abschnitte Dokument und E-Rechnung. Schlüssel ohne eigenes Feld dort (waitFor, pageRanges, image.quality, image.clipSelector) bleiben beim Speichern erhalten; setzen Sie sie in einem Projekt oder über die API.
• In einem Projekt stehen sie in settings.json im Ordner der Vorlage; die Dateien header.html und footer.html daneben füllen header.html und footer.html der Einstellungen.
• Über die API sind es die settings einer Version (POST /templates/{id}/versions) und einer Render-Anfrage.

Wie Einstellungen kombiniert werden

Formfeed führt drei Ebenen tief zusammen, spätere haben Vorrang:

1. die Standardwerte auf dieser Seite,
2. die Einstellungen der Vorlagenversion,
3. das Objekt settings der Render-Anfrage.

Nur die Schlüssel, die Sie setzen, ändern sich; alles andere behält seinen Wert. Eine Liste ersetzt die Liste darunter. Wenn Sie einen Abschnitt auf null setzen, wird er entfernt. So schaltet eine Anfrage die Fußzeile einer Vorlage ab:

{ "template": "invoice", "data": { … }, "settings": { "margin": { "top": "30mm" }, "footer": null } }

Das Feld locale der Anfrage ist eine Kurzform für settings.locale; sendet eine Anfrage beides, hat settings.locale Vorrang.

Beispiel

{
  "paper": { "format": "A4", "landscape": false },
  "margin": {
    "top": "25mm",
    "right": "18mm",
    "bottom": "22mm",
    "left": "18mm"
  },
  "footer": {
    "html": "<div style=\"font-size: 8pt\">Seite <span class=\"pageNumber\"></span></div>",
    "height": "12mm"
  },
  "printBackground": true,
  "pdf": {
    "metadata": {
      "title": "Rechnung {{ invoice.number }}",
      "author": "Fennlor Studio GmbH"
    }
  },
  "locale": "de-DE",
  "timezone": "Europe/Berlin",
  "currency": "EUR",
  "tailwind": true
}

Seite (PDF)

Längen nehmen die Einheiten mm, cm, in und px oder eine bloße Zahl in Pixeln ("20mm", "1in", "96"). Andere Einheiten wie pt, em oder % lassen das Rendering fehlschlagen.

Schlüssel	Typ	Standard	Bedeutung
paper.format	string	"A4"	A0–A6, Letter, Legal, Tabloid, Ledger, in beliebiger Groß- und Kleinschreibung. Wird ignoriert, wenn width und height gesetzt sind. Ein anderer Name lässt das Rendering fehlschlagen.
paper.width, paper.height	Länge	null	Eigene Seitengröße, zum Beispiel "100mm" und "150mm". Beide Werte sind nötig; einer allein wird ignoriert.
paper.landscape	boolean	false	Dreht die Seite ins Querformat: Breite und Höhe tauschen, auch bei einer eigenen Größe.
margin.top, .right, .bottom, .left	Länge	20mm, 15mm, 20mm, 15mm	Seitenränder. Kopf- und Fußzeilen werden innerhalb des oberen und unteren Rands gezeichnet.
preferCssPageSize	boolean	false	@page-Regeln in Ihrem CSS bestimmen die Seitengröße statt paper.
printBackground	boolean	true	Hintergrundfarben und -bilder drucken.
scale	number	1	Skaliert den Seiteninhalt, 0.1 bis 2. Ein Wert außerhalb lässt das Rendering fehlschlagen.
pageRanges	string	""	Nur diese Seiten behalten, zum Beispiel "1-3, 5". Leer behält alle. Seitenzahl, Seitenlimit des Plans und Einheiten zählen die behaltenen Seiten.

Vor dem Drucken setzt Chromium die Seite in einem Fenster von der Größe des Papiers (A4 hochkant: 794 × 1123 CSS-Pixel). Skripte, die das Fenster messen, sehen also die Breite der Seite.

Kopf- und Fußzeile (PDF)

Schlüssel	Typ	Standard	Bedeutung
header.html, footer.html	string	keiner	Markup für die laufende Kopf- und Fußzeile, einmal mit der Sprache und den Daten der Vorlage gerendert und auf jede Seite gedruckt. Die Tabs Kopfzeile und Fußzeile im Editor sowie header.html und footer.html eines Projekts schreiben diese Werte. In einem Ad-hoc-Rendering mit html ohne engine werden sie so verwendet, wie sie geschrieben sind.
header.height, footer.height	CSS-Länge	keiner	Höhe des Kastens für Kopf- oder Fußzeile. Den Rand ändert sie nicht: Machen Sie margin.top (bzw. margin.bottom) mindestens so groß. Im Editor Höhe der Kopfzeile und Höhe der Fußzeile.
header.padding, footer.padding	CSS-Padding	"0 10mm"	Innenabstand des Kastens für Kopf- oder Fußzeile. Der Kasten reicht wie in Chromiums Druck über die ganze Seitenbreite, deshalb hält erst dieser Abstand den Inhalt vom Papierrand fern; 0 lässt ein Design bis zum Rand laufen. Im Editor Innenabstand der Kopfzeile und Innenabstand der Fußzeile.

header: null oder footer: null entfernt eine davon. Seitenzahlen, Gestaltung und was dort nicht funktioniert (Stylesheets, Bilder per URL, Skripte) beschreibt Kopfzeilen, Fußzeilen und Seitenzahlen.

PDF-Ausgabe

Schlüssel	Typ	Standard	Bedeutung
pdf.metadata.title	string	""	Dokumenttitel, den ein PDF-Betrachter in seiner Titelleiste zeigt. Wird mit den Daten gerendert, darf also Vorlagenausdrücke enthalten ("Rechnung {{ invoice.number }}"). Auch der <title> des Dokuments und der Wert der Klasse title in Kopf- und Fußzeilen. Ein Ad-hoc-Rendering mit html ohne engine und ein Rendering einer url ignorieren ihn.
pdf.metadata.author, pdf.metadata.subject, pdf.metadata.keywords	string	""	Eigenschaften des Dokuments, wie der Titel mit den Daten gerendert, "{{ company.name }}" wird also zum Namen; eine, die leer gerendert wird, entfällt. Ein Ad-hoc-Rendering mit html ohne engine schreibt sie unverändert. keywords ist ein einzelner String, etwa "Rechnung, 2026".
pdf.tagged	boolean	false	Den Strukturbaum schreiben (Überschriften, Listen, Tabellen, Links), nach dem ein Screenreader das Dokument liest. Ein getaggtes PDF ist noch keine PDF/UA-Datei: Das ist pdf.ua.
pdf.outline	boolean	false	Aus den Überschriften eine Lesezeichen-Gliederung erzeugen, nach Überschriftenebene verschachtelt. Chromium baut sie aus den Tags des PDFs, das PDF wird dadurch also auch getaggt.
pdf.ua	boolean oder { "check": "strict" | "report" }	false	Die Datei zu einem PDF/UA-1-Dokument machen: getaggt, repariert und gegen die maschinell prüfbaren Regeln der Norm geprüft, mit veraPDF. true (und {}) ist die strenge Prüfung, bei der ein Rendering fehlschlägt, dessen Datei nicht besteht; report liefert sie mit dem Ergebnis der Prüfung aus. Schließt pdf.tagged ein. false in einer Anfrage schaltet ab, was die Vorlage festlegt.

Der Abschnitt Dokument der Seiteneinrichtung im Editor schreibt diese Werte: Titel, Autor, Thema, Stichwörter, Lesezeichen aus den Überschriften (pdf.outline), Getaggtes PDF (pdf.tagged) und Barrierefreies PDF (PDF/UA-1) (pdf.ua).

pdf.ua gilt nur für die PDF-Ausgabe. Eine Anfrage, die es zusammen mit einer Bildausgabe, mit post.merge_after oder für eine Word- oder PowerPoint-Vorlage verlangt, wird mit 400 invalid_request beantwortet, bevor etwas gerendert wird; eine Vorlage, die es festlegt, rendert ihre Bilder wie gewohnt. Siehe Barrierefreie PDFs.

E-Rechnung

einvoice macht die Vorlage zur Rechnungsvorlage: Jedes PDF, das aus ihr gerendert wird, ist eine ZUGFeRD- oder Factur-X-E-Rechnung, gebaut aus dem _invoice-Block der Daten. Die Bildausgabe derselben Vorlage ist nicht betroffen. Der Abschnitt E-Rechnung der Seiteneinrichtung im Editor schreibt diesen Wert. Live-E-Rechnungen brauchen den Plan Starter oder höher; siehe Pläne und Einheiten.

Schlüssel	Typ	Standard	Bedeutung
einvoice	object	keiner	Legt die E-Rechnung fest. {} übernimmt die Standardwerte unten.
einvoice.profile	en16931, basic	en16931	Das Profil der Rechnung.
einvoice.flavour	factur-x, zugferd	factur-x	Der Name und die Version, die das Rendering meldet. Die Datei ist dieselbe.
einvoice.xml	embedded, both	embedded	both speichert das XML zusätzlich als eigene Datei neben dem PDF.
einvoice.display_check	warn, strict	warn	Was passiert, wenn das PDF einen Wert des XML nicht zeigt: eine Warnung oder ein fehlgeschlagenes Rendering.

settings.einvoice und post.einvoice einer Anfrage überlagern diese Werte Feld für Feld, und post.einvoice: false schaltet sie für eine Anfrage ab. Siehe die Optionen.

Bildausgabe

Wird von Vorlagen der Art image genutzt und von jedem Rendering mit output: "png", "jpg" oder "webp".

Schlüssel	Typ	Standard	Bedeutung
image.format	png, jpeg, webp	png	Was eine Bildvorlage erzeugt, wenn die Anfrage kein output nennt. jpg wird ebenfalls akzeptiert. Das output einer Anfrage hat immer Vorrang; eine Anfrage kann stattdessen auch settings.image.format setzen.
image.width, image.height	integer (CSS-px)	1200, 630	Größe des Viewports. html und body nehmen diese Größe ebenfalls an.
image.deviceScaleFactor	number	2	Pixeldichte. 2 verdoppelt die Pixelmaße der Datei: aus 1200 × 630 werden 2400 × 1260.
image.quality	integer	90	Qualität für JPEG und WebP, 1–100. WebP mit 100 ist verlustfrei. PNG ignoriert den Wert.
image.fullPage	boolean	false	Die gesamte Scrollhöhe statt des Viewports aufnehmen.
image.transparent	boolean	false	Transparenter Hintergrund für PNG und WebP; JPEG hat keinen. Nur dort, wo die Seite keinen eigenen Hintergrund malt. Im Editor Transparenter Hintergrund (PNG).
image.clipSelector	string	null	CSS-Selektor eines einzelnen Elements, das statt des ganzen Viewports aufgenommen wird; der erste Treffer zählt. Passt innerhalb von 30 Sekunden kein Element, schlägt das Rendering mit render_timeout fehl.
design	object	keiner	Die Ebenen einer Vorlage aus dem visuellen Editor. Das ist, was Sie bearbeiten, nicht was gerendert wird: Ein Render verwendet das HTML und CSS, das der Editor daraus schreibt, und ein design in einer Render-Anfrage wird ignoriert. Höchstens 256 kB. Ein Projekt legt es in design.json ab.

Auf Inhalte warten

Bevor Formfeed druckt, ist die Seite geladen und keine ihrer Anfragen läuft mehr (das Laden darf bis zu 30 Sekunden dauern), ihre Schriften sind bereit, mit data-ff-fit markierter Text ist angepasst, und die Bedingungen unten sind erfüllt. Eine Seite, die von sich aus laden kann, ein url-Rendering oder eine Vorlage mit einem eigenen Skript, einem Event-Handler-Attribut wie onload oder einem Frame, wird erst gedruckt, wenn das Netzwerk außerdem eine halbe Sekunde geruht hat, denn ihr Code kann noch eine Anfrage starten. Die Skripte, die Formfeed für Diagramme und angepassten Text einfügt, zählen nicht. Diese Schlüssel sind für Seiten, die später fertig werden, meist wegen JavaScript.

Schlüssel	Typ	Standard	Bedeutung
waitFor.networkIdle	boolean oder "auto"	"auto"	"auto" wartet wie oben beschrieben. true wartet immer auf eine halbe Sekunde Ruhe im Netzwerk, wie es jedes Rendering bis zum 18. Oktober 2026 tat; false druckt direkt nach dem Ereignis load und den Schriften, was einer Seite hilft, die ständig nachfragt.
waitFor.selector	string	null	Warten, bis ein Element existiert und sichtbar ist, das auf diesen CSS-Selektor passt (ein Element mit display: none oder ohne Größe zählt nicht).
waitFor.timeoutMs	integer	5000	Wie lange auf selector gewartet wird, in Millisekunden; höchstens 30.000. Ist das Element bis dahin nicht erschienen, schlägt das Rendering mit render_timeout fehl.
waitFor.delayMs	integer	0	Zusätzliche feste Pause in Millisekunden nach allem anderen, höchstens 10.000; ein größerer Wert zählt als 10.000.

{ "waitFor": { "selector": "#report-ready", "timeoutMs": 8000 } }

Formatierung und Gestaltung

Schlüssel	Typ	Standard	Bedeutung
locale	BCP-47-Tag	"en-GB"	Formatiert Datumsangaben und Zahlen, wählt das Übersetzungswörterbuch und setzt <html lang>. Skripte in der Seite sehen sie als Sprache des Browsers. Das Feld locale der Anfrage setzt sie pro Rendering.
timezone	IANA-Zeitzone	"Europe/Berlin"	Zeitzone für Datumsangaben, der Helfer und des JavaScripts in der Seite.
currency	ISO-4217-Code	"EUR"	Standardwährung von money.
tailwind	boolean	false	Die Tailwind-Utility-Klassen kompilieren, die das Dokument nutzt; siehe Tailwind CSS.

Word- und PowerPoint-Vorlagen

Word- und PowerPoint-Vorlagen übernehmen Papier, Ränder, Kopf- und Fußzeilen aus dem Dokument; die Einstellungen für Seite, Kopf- und Fußzeile, Warten und Bildausgabe oben gelten für sie nicht, ebenso wenig pdf.metadata.title, pdf.tagged, pdf.outline und pdf.ua (pdf.ua wird abgelehnt). Was sie nutzen:

Schlüssel	Typ	Standard	Bedeutung
office.output	docx, pptx, pdf	das eigene Format der Vorlage	Was ein Rendering erzeugt, das kein output nennt. Eine docx-Vorlage erlaubt docx oder pdf, eine pptx-Vorlage pptx oder pdf. Im Panel Einstellungen der Vorlage heißt es Ausgabe, wenn ein Rendering keine angibt.
locale, timezone, currency		wie oben	Formatierung der Helfer, wie in HTML-Vorlagen.
pdf.metadata.author, pdf.metadata.subject, pdf.metadata.keywords	string	""	Werden unverändert in die PDF-Ausgabe geschrieben: Anders als eine HTML-Vorlage rendert eine Word- oder PowerPoint-Vorlage sie nicht mit den Daten. Eine Ausgabe als docx oder pptx behält die Eigenschaften des Dokuments.
einvoice		wie oben	Auch ihre PDF-Ausgabe kann eine E-Rechnung sein.

Über die API

Das Objekt settings von POST /v1/renders nutzt genau diese Schlüssel. Bei Ad-hoc-Renderings mit html gibt es keine Vorlage, daher überlagern die Einstellungen der Anfrage direkt die Standardwerte:

{
  "html": "<h1>Versandetikett</h1>",
  "settings": {
    "paper": { "width": "100mm", "height": "150mm" },
    "margin": { "top": "5mm", "right": "5mm", "bottom": "5mm", "left": "5mm" }
  }
}

Mit "engine": "jinja2" (oder liquid, handlebars) ist das html eine Vorlage: Es wird mit data gerendert, ebenso header.html, footer.html und die Felder von pdf.metadata. Ohne engine werden Markup, Kopf- und Fußzeile so verwendet, wie sie geschrieben sind, und pdf.metadata.title wird nicht angewendet; geben Sie dem Dokument dann einen eigenen <title>. Ein Rendering einer url nutzt die Einstellungen für Seite, Kopf- und Fußzeile, Warten und Bild.