Wypełnianie formularza PDF w NextPDF Connect (Pro)

W skrócie

Wypełniaj interaktywne pola formularza PDF za pomocą NextPDF Connect i formatu XML Forms Data Format (XFDF). Narzędzie do podpisów i formularzy to fill_form. Dostawca narzędzi Pro rejestruje new FillFormTool(), którego nazwa w protokole to fill_form. fill_form to narzędzie z poziomu Pro. Podczas uruchamiania serwer sprawdza obecność pakietu Pro za pomocą class_exists() i rejestruje narzędzie tylko wtedy, gdy pakiet jest obecny. W samym Core fill_form nie występuje w rejestrze.

Instalacja

composer require nextpdf/server
composer require nextpdf/pro

Powiąż transport. Następnie za pomocą diagnostic.capabilities potwierdź, że narzędzie jest dostępne (zobacz environment-diagnostics). Nie zakładaj, że zestaw narzędzi jest stały.

Przegląd koncepcyjny

XFDF odwzorowuje nazwy pól na wartości za pomocą elementów <field>. Każda nazwa musi odpowiadać polu AcroForm, które istnieje już w dokumencie docelowym. Każde pole jest przechowywane w słowniku pól formularza interaktywnego (ISO 32000-2 §12.7), a dostarczona wartość staje się wartością pola (ISO 32000-2 §12.7). Jeśli nazwa nie odpowiada żadnemu polu, narzędzie ją pomija, zamiast traktować to jako błąd. Narzędzie raportuje liczbę wypełnionych i pominiętych pól.

Powierzchnia API

Narzędzie	Poziom	Rola	Poziom ryzyka
`create_pdf`	Core	Otwarcie sesji	Bezpieczne
`fill_form`	Pro	Zastosowanie wartości XFDF do pól AcroForm	Ostrożność
`output_pdf`	Core	Renderowanie i zwrócenie pliku PDF	Wymagane zatwierdzenie / Przegląd (base64)

Nazwy narzędzi odpowiadają nazwom protokołów w rejestrze. Katalog narzędzi jest wiążącym katalogiem. Zainstalowany poziom określa, które narzędzia są dostępne. Narzędzia Pro pojawiają się tylko wtedy, gdy zainstalowany jest pakiet Pro.

Przykład kodu — szybki start

create_pdf (lub wczytaj szablon, który zawiera już pola formularza).
fill_form z xfdf_data, które odwzorowuje nazwy pól na wartości.
output_pdf → base64.

Wynik zawiera fields_filled, fields_skipped oraz dopasowane nazwy pól.

Przykład kodu — produkcja

Użyj szablonu z kontrolowanymi nazwami pól AcroForm. Zweryfikuj XFDF względem schematu XFDF, zanim go wyślesz. Sprawdź fields_skipped oraz zwróconą listę nazw, aby wykryć niezgodności nazw (nazwy rozróżniają wielkość liter). Przy dużych operacjach wypełniania pozostań poniżej limitu rozmiaru XFDF i w razie potrzeby podziel dane.

Przypadki brzegowe i pułapki

Niepoprawny składniowo XFDF. Błąd parsowania wskazuje miejsce, w którym wystąpił problem. Użyj sekwencji ucieczki dla encji XML i dołącz xmlns.
Niezgodność nazw. Pole bez dopasowania jest po cichu pomijane, a fields_skipped się zwiększa. Nazwy rozróżniają wielkość liter.
Brak pól formularza. Dokument bez AcroForm skutkuje zerem wypełnionych pól.
XFDF zbyt duży. Serwer odrzuca dane przekraczające limit rozmiaru. Podziel je lub usuń zbędne białe znaki.
Brak Pro. W samym Core fill_form nie jest zarejestrowane, a jego wywołanie zwraca błąd nieznanego narzędzia. Najpierw sprawdź za pomocą diagnostic.capabilities.

Wydajność

Wypełnianie jest szybkie w porównaniu z renderowaniem. Rozmiar wyniku waha się od kilku KB do dziesiątek KB, zależnie od liczby pól i osadzania czcionek. Profil ma wartość structural.

Uwagi dotyczące bezpieczeństwa

Wartości pól stają się treścią dokumentu. Nie umieszczaj sekretów w polach formularza, jeśli później zwracasz plik PDF niezaufanym kanałem. Ścieżka base64 nie ma skutków ubocznych w systemie plików. Zapis do pliku podlega bramkowaniu.

Zgodność

Stwierdzenie	Specyfikacja	Punkt	reference_id
Pole formularza jest przechowywane w słowniku pól formularza interaktywnego.	ISO 32000-2	§12.7
Dostarczone dane stają się wartością pola.	ISO 32000-2	§12.7

Kontekst komercyjny

fill_form to narzędzie z poziomu Pro. Serwer rejestruje je tylko wtedy, gdy pakiet Pro zostanie poprawnie rozwiązany podczas uruchamiania (sprawdzenie class_exists()). Wdrożenia Core go nie udostępniają.

Dostępność transportów

Transport	Dostępne	Uwagi
MCP (stdio)	Tak (Pro)	Dostępne tylko wtedy, gdy zainstalowany jest Pro.
REST	Tak (Pro)	Tak samo.
gRPC	Tak (Pro)	Tak samo.

Poziom ryzyka HITL

fill_form jest oznaczone jako Ostrożność, ponieważ jest odwracalną mutacją treści. output_pdf ma poziom Wymagane zatwierdzenie, obniżany do poziomu Przegląd w trybie base64 (poziomy ryzyka HITL).

Koperta JSON bramki potwierdzenia

Wynik base64:

{ "allowed": true }

Zapis do pliku zwraca kopertę wyzwania opisaną w output-approval.