Tworzenie wielostronicowego dokumentu w NextPDF Connect

W skrócie

Utwórz dokument złożony z kilku stron w NextPDF Connect. add_page dołącza stronę, która dziedziczy domyślną geometrię dokumentu albo korzysta z jawnie ustawionej orientacji. Po każdym add_page kursor wraca do lewego górnego marginesu nowej strony. Korzystasz z czterech narzędzi Core: create_pdf, add_text, add_page oraz output_pdf.

Instalacja

composer require nextpdf/server

Skonfiguruj transport: Model Context Protocol (MCP) stdio, REST lub gRPC. Licencjonowana edycja nie jest wymagana.

Przegląd koncepcyjny

Dokument korzysta z drzewa stron. Dostęp do każdej strony odbywa się przez to drzewo (ISO 32000-2 §7.7.3). Strona ma własne atrybuty geometrii, w tym pole multimediów definiujące widoczny obszar (ISO 32000-2 §7.7.3.3). create_pdf automatycznie tworzy pierwszą stronę, a add_page dołącza każdą kolejną. Pomiń page_size/orientation, aby odziedziczyć domyślne ustawienia dokumentu. Ustaw orientation: "landscape", aby strona A4 miała wymiary 297×210 mm.

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwarcie sesji, utworzenie pierwszej strony	Bezpieczne
`add_text`	Zapis tekstu w bieżącym miejscu kursora	Ostrożnie
`add_page`	Dołączenie strony (dziedziczenie lub jawne nadpisanie)	Ostrożnie
`output_pdf`	Renderowanie i zwrócenie pliku PDF	Wymagana zgoda / przegląd (base64)

Nazwy narzędzi odpowiadają nazwom protokołu z rejestru. Autorytatywnym źródłem jest katalog narzędzi. Dostępne narzędzia zależą od zainstalowanej edycji.

Przykład kodu — szybki start

Przebieg:

create_pdf (A4 pionowo, tytuł, autor) → document_id.
add_text (tytuł, duża czcionka, wyśrodkowanie), a następnie add_text (akapit wprowadzający, czcionka tekstu).
add_page tylko z document_id → dziedziczy A4 pionowo. Zwracany jest nowy page_number, a kursor jest resetowany.
add_text z nagłówkiem sekcji i treścią na stronie 2.
add_page z orientation: "landscape" → szeroka strona A4.
add_text z treścią dla szerokiego układu.
output_pdf → base64.

Przykład kodu — środowisko produkcyjne

Waliduj każdą odpowiedź. Po add_page treść zaczyna się od góry nowej strony. Reset kursora to zamierzone zachowanie, a nie błąd. Śledź position.page w odpowiedziach add_text, aby wykryć, kiedy treść przeszła na kolejną stronę. Wywołaj output_pdf dokładnie raz, a następnie odrzuć document_id.

Przypadki brzegowe i pułapki

Reset kursora. Po add_page kursor znajduje się przy lewym górnym marginesie nowej strony. Częstym błędem jest oczekiwanie, że pozycja kursora będzie kontynuowana z poprzedniej strony.
Wymagany document_id. Każde narzędzie poza create_pdf wymaga document_id. Pominięcie go jest błędem.
Nieprawidłowa orientacja. Dozwolone są tylko "portrait" i "landscape".
Edycja po wygenerowaniu. Dodanie treści po output_pdf z destroy: true kończy się niepowodzeniem, ponieważ sesja już nie istnieje.

Wydajność

Wielostronicowy dokument tekstowy mieści się w przewidzianym budżecie stron, a wynikowy plik ma kilka KB. Profil to structural: wartość /ID w trailerze oraz znaczniki czasu nie są stabilne między uruchomieniami.

Uwagi dotyczące bezpieczeństwa

Tryb base64 nie ma skutków ubocznych. Zapis do pliku przechodzi przez bramkę; zobacz sekcję human-in-the-loop (HITL). document_id jest nieprzezroczystym uchwytem. Nie współdziel go między równoczesnymi żądaniami.

Zgodność

Stwierdzenie	Specyfikacja	Punkt	reference_id
Dostęp do stron odbywa się przez drzewo stron.	ISO 32000-2	§7.7.3
Obiekt strony definiuje własne atrybuty geometrii.	ISO 32000-2	§7.7.3.3

Kontekst komercyjny

Nie dotyczy — wszystkie narzędzia są częścią Core.

Dostępność transportów

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	`tools/call` dla narzędzia.
REST	Tak	Jedna operacja na każde narzędzie.
gRPC	Tak	Wywołanie unarne na każde narzędzie.

Poziom ryzyka HITL

create_pdf ma poziom Bezpieczne; add_text i add_page wymagają Ostrożności; output_pdf ma poziom Wymagana zgoda, w trybie base64 obniżany do Przegląd. Zapis do pliku pozostaje na poziomie Wymagana zgoda. Zobacz output-approval oraz poziomy ryzyka HITL.

Koperta JSON dla bramki potwierdzenia

Dla wyniku base64:

{ "allowed": true }

Formularz wyzwania pokazano w output-approval.