Layout-Zustand mit NextPDF Connect prüfen

Auf einen Blick

Prüfen Sie den Layout-Zustand eines Dokuments während der Sitzung, damit Sie Positionierungsentscheidungen sicher treffen können. preview_layout wurde erneut anhand der Werkzeugregistrierung des Servers verifiziert; dort stellt PreviewLayoutTool den Protokollnamen preview_layout bereit. Die Abfrage ist schreibgeschützt und idempotent. Sie rendert kein PDF, bewegt den Cursor nicht weiter und kann beliebig oft aufgerufen werden. Alle diese Werkzeuge gehören zu Core: create_pdf, set_font, add_text, preview_layout, add_page und output_pdf.

Installation

composer require nextpdf/server

Binden Sie einen Transport an. Eine lizenzierte Stufe ist nicht erforderlich.

Konzeptioneller Überblick

preview_layout gibt die Seitenanzahl, die aktuelle Seite, die Seitenabmessungen, die Ränder und die Cursor-Position zurück — einschließlich der eigenen Geometrieattribute der Seite (ISO 32000-2 §7.7.3.3). Berechnen Sie aus diesen Werten den verbleibenden vertikalen Raum:

remaining = page_height - bottom_margin - cursor_y

Wenn remaining die geschätzte Höhe Ihres nächsten Blocks übersteigt, fahren Sie auf der aktuellen Seite fort. Andernfalls rufen Sie zuerst add_page auf. Da der Aufruf schreibgeschützt ist, gibt er über jeden Transport eine normale Antwort zurück (PSR-18 §p2).

API-Oberfläche

Werkzeug	Rolle	Risikostufe
`create_pdf`	Sitzung öffnen	Sicher
`set_font`	Aktive Schriftart festlegen	Vorsicht
`add_text`	Text schreiben, Cursor vorrücken	Vorsicht
`preview_layout`	Layout-Zustand lesen (keine Mutation)	Sicher
`add_page`	Eine Seite anhängen, wenn der Platz ausgeht	Vorsicht
`output_pdf`	Das PDF rendern und zurückgeben	Genehmigung erforderlich / Überprüfung (base64)

Der Werkzeugkatalog ist der maßgebliche Katalog. Welche Werkzeuge verfügbar sind, hängt von der installierten Stufe ab.

Codebeispiel — Schnellstart

create_pdf (Letter-Hochformat) → document_id.
set_font (helvetica 14).
add_text ×3 (Absätze im Blocksatz).
preview_layout → page_dimensions, margins, cursor_position lesen.
remaining berechnen; wenn der Wert zu klein ist, add_page.
add_text (nächster Abschnitt).
output_pdf.

Codebeispiel — Produktion

Rufen Sie preview_layout vor jedem Block auf, bei dem unklar ist, ob er passt. Betrachten Sie den zurückgegebenen Cursor als korrekt für den letzten Schreibvorgang. Wenn Sie seit dem letzten add_text die Schriftart, die Ränder oder die Zeilenhöhe geändert haben, schreiben Sie eine kurze Probe und fragen Sie erneut ab, bevor Sie sich auf die vorhergesagte Position verlassen.

Grenzfälle & Fallstricke

Veralteter Cursor nach einer Stiländerung. Die gemeldete Position spiegelt den letzten Schreibvorgang wider, keine etwaigen ausstehenden Zustandsänderungen. Fragen Sie erneut ab, wenn Präzision wichtig ist.
Zerstörte Sitzung. preview_layout schlägt bei einer zerstörten document_id fehl. Um das Layout nach der Ausgabe zu prüfen, setzen Sie destroy: false im vorherigen output_pdf.
Leerer Text oder unbekannte Schriftart. Es gelten die üblichen Eingabevalidierungsfehler.

Leistung

preview_layout ist ein kostengünstiger Lesevorgang. Das Profil für das erzeugte Dokument ist structural.

Sicherheitshinweise

Die Abfrage ist schreibgeschützt und hat keine Nebenwirkungen. Die zurückgegebenen Koordinaten sind nicht sensibel; behandeln Sie sie jedoch als sitzungsbezogen.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Ein Seitenobjekt definiert seine Geometrieattribute.	ISO 32000-2	§7.7.3.3
Eine schreibgeschützte Abfrage gibt eine normale Transportantwort zurück.	PSR-18	§p2

Kommerzieller Kontext

Nicht zutreffend — alle Werkzeuge gehören zu Core.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja	`preview_layout` ist ein `tools/call`.
REST	Ja	Sicherer Vorgang im GET-Stil.
gRPC	Ja	Unär; idempotent.

HITL-Risikostufe

preview_layout ist Sicher (schreibgeschützt) und blockiert nie. create_pdf ist Sicher. set_font, add_text und add_page sind Vorsicht. output_pdf ist Genehmigung erforderlich, im base64-Modus auf Überprüfung herabgestuft (HITL-Risikostufen).

JSON-Umschlag der Bestätigungssperre

Eine schreibgeschützte Prüfung blockiert nie:

{ "allowed": true }