Sprawdzanie stanu układu w NextPDF Connect

W skrócie

Sprawdzaj stan układu dokumentu w trakcie sesji, aby pewnie podejmować decyzje dotyczące pozycjonowania. preview_layout — ponownie zweryfikowane względem rejestru narzędzi serwera, w którym PreviewLayoutTool udostępnia nazwę protokołu preview_layout — to idempotentne zapytanie tylko do odczytu. Nie renderuje pliku PDF, nie przesuwa kursora i można je wywoływać dowolną liczbę razy. Wszystkie te narzędzia należą do edycji Core: create_pdf, set_font, add_text, preview_layout, add_page oraz output_pdf.

Instalacja

composer require nextpdf/server

Skonfiguruj transport. Licencjonowana edycja nie jest potrzebna.

Przegląd koncepcyjny

preview_layout zwraca liczbę stron, bieżącą stronę, wymiary strony, marginesy i położenie kursora — czyli atrybuty geometrii właściwe dla strony (ISO 32000-2 §7.7.3.3). Użyj tych wartości, aby obliczyć pozostałą przestrzeń w pionie:

remaining = page_height - bottom_margin - cursor_y

Jeśli wartość remaining jest większa niż szacowana wysokość kolejnego bloku, kontynuuj na bieżącej stronie. W przeciwnym razie najpierw wywołaj add_page. Ponieważ wywołanie jest tylko do odczytu, w każdym transporcie zwraca zwykłą odpowiedź (PSR-18 §p2).

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwarcie sesji	Bezpieczne
`set_font`	Ustawienie aktywnej czcionki	Ostrożnie
`add_text`	Zapisanie tekstu, przesunięcie kursora	Ostrożnie
`preview_layout`	Odczyt stanu układu (bez modyfikacji)	Bezpieczne
`add_page`	Dołączenie strony, gdy zabraknie miejsca	Ostrożnie
`output_pdf`	Renderowanie i zwrócenie pliku PDF	Wymagane zatwierdzenie / przegląd (base64)

Katalog narzędzi jest źródłem informacji. Dostępne narzędzia zależą od zainstalowanej edycji.

Przykład kodu — szybki start

create_pdf (Letter, orientacja pionowa) → document_id.
set_font (helvetica 14).
add_text ×3 (akapity wyjustowane).
preview_layout → odczytaj page_dimensions, margins, cursor_position.
Oblicz remaining; jeśli wartość jest zbyt mała, wywołaj add_page.
add_text (następna sekcja).
output_pdf.

Przykład kodu — środowisko produkcyjne

Wywołuj preview_layout przed każdym blokiem, gdy nie ma pewności, że blok się zmieści. Traktuj zwrócone położenie kursora jako dokładne dla ostatniego zapisu. Jeśli od ostatniego add_text zmieniono czcionkę, marginesy lub wysokość wiersza, zapisz krótki tekst próbny i ponów zapytanie, zanim zaczniesz polegać na przewidywanym położeniu.

Przypadki brzegowe i pułapki

Nieaktualne położenie kursora po zmianie stylu. Zgłaszane położenie odzwierciedla ostatni zapis, a nie oczekujące zmiany stanu. Powtórz pomiar, jeśli precyzja ma znaczenie.
Usunięta sesja. preview_layout kończy się niepowodzeniem przy usuniętym document_id. Aby sprawdzić układ po wygenerowaniu, ustaw destroy: false w poprzednim output_pdf.
Pusty tekst lub nieznana czcionka. Obowiązują standardowe błędy walidacji danych wejściowych.

Wydajność

preview_layout to lekki odczyt. Profil dla wygenerowanego dokumentu to structural.

Uwagi dotyczące bezpieczeństwa

Zapytanie jest tylko do odczytu i nie ma żadnych efektów ubocznych. Zwracane współrzędne nie są wrażliwe, ale traktuj je jako dane ograniczone do sesji.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Obiekt strony definiuje swoje atrybuty geometrii.	ISO 32000-2	§7.7.3.3
Zapytanie tylko do odczytu zwraca zwykłą odpowiedź transportu.	PSR-18	§p2

Kontekst komercyjny

Nie dotyczy — wszystkie narzędzia należą do edycji Core.

Dostępność transportów

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	`preview_layout` to `tools/call`.
REST	Tak	Bezpieczna operacja w stylu GET.
gRPC	Tak	Unarne; idempotentne.

Poziom ryzyka HITL

preview_layout jest bezpieczne (tylko do odczytu) i nigdy nie wymaga zatwierdzenia. create_pdf jest bezpieczne. set_font, add_text oraz add_page wymagają ostrożności. output_pdf wymaga zatwierdzenia, które w trybie base64 jest obniżone do przeglądu (poziomy ryzyka HITL).

Koperta JSON bramki potwierdzenia

Sprawdzenie wykonywane tylko do odczytu nigdy nie wymaga zatwierdzenia:

{ "allowed": true }