Osadzanie obrazów przez NextPDF Connect

W skrócie

Osadź obraz w pliku Portable Document Format (PDF) za pomocą NextPDF Connect. Jako źródła użyj ścieżki pliku, którą serwer może odczytać, albo wbudowanego identyfikatora URI danych base64. Służą do tego create_pdf, add_image oraz output_pdf — wszystkie są narzędziami Core. NextPDF rysuje obraz jako obiekt XObject obrazu malowany przez operator Do (ISO 32000-2 §8.9).

Instalacja

composer require nextpdf/server

Skonfiguruj transport. NextPDF obsługuje formaty rastrowe PNG, JPEG i GIF.

Przegląd koncepcyjny

add_image przyjmuje source i rozstrzyga jego typ w tej stałej kolejności:

Identyfikator URI danych — ciąg znaków, który zaczyna się od data:. NextPDF dekoduje typ MIME (Multipurpose Internet Mail Extensions) oraz ładunek base64 do pliku tymczasowego, osadza obraz, a następnie usuwa plik tymczasowy.
Surowy base64 — NextPDF dekoduje długi ciąg znaków base64 i traktuje go jako PNG.
Ścieżka pliku — NextPDF traktuje wszystko inne jako ścieżkę w systemie plików, którą proces serwera musi być w stanie odczytać.

Obraz jest umieszczany w punkcie x/y, w jednostkach użytkownika (domyślnie milimetry). Jeśli przekażesz tylko width, NextPDF obliczy wysokość tak, aby zachować proporcje. Jeśli przekażesz zarówno width, jak i height, NextPDF przeskaluje obraz do tych dokładnych wymiarów. Osadzony obiekt to obiekt zewnętrzny malowany w treści strony (ISO 32000-2 §8.8).

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwarcie sesji	Bezpieczne
`add_image`	Osadzenie obrazu ze ścieżki lub identyfikatora URI danych	Ostrożnie
`output_pdf`	Renderowanie i zwrócenie PDF	Wymagane zatwierdzenie / Przegląd (base64)

Katalog narzędzi jest oficjalnym punktem odniesienia. Dostępne narzędzia zależą od zainstalowanej edycji.

Przykład kodu — szybki start

create_pdf (A4 pionowo, tytuł) → document_id.
add_image z source ustawionym na ścieżkę bezwzględną, x, y, width.
add_image z source ustawionym na identyfikator URI data:image/png;base64,... oraz jawnie podanymi width i height.
output_pdf → base64.

Przykład kodu — produkcja

Użyj identyfikatora URI danych dla obrazu wygenerowanego w pamięci przez host, takiego jak renderowany wykres lub zrzut ekranu. Użyj ścieżki pliku dla zasobu, który już istnieje na serwerze. Zawsze używaj ścieżek bezwzględnych. Ścieżka względna jest rozwiązywana względem katalogu roboczego serwera, który zwykle nie jest katalogiem hosta. Przed dalszym przetwarzaniem sprawdź, czy odpowiedź add_image zgłasza obraz na oczekiwanej stronie.

Przypadki brzegowe i pułapki

Nie znaleziono ścieżki. Dla brakującej ścieżki pliku zwracany jest błąd nieznalezienia obrazu.
Nieobsługiwany format. NextPDF odrzuca SVG, BMP i WebP. Najpierw przekonwertuj obraz.
Nieprawidłowy base64 / identyfikator URI danych. Niepoprawny ładunek albo identyfikator URI danych bez separatora w postaci przecinka zwraca błąd dekodowania.
Zbyt duży obraz. Obraz większy niż strona jest przycinany przy krawędzi, a nie odrzucany. Oblicz width/height względem strony pomniejszonej o jej marginesy (A4 pionowo to 210×297 mm).

Wydajność

Rozmiar danych wyjściowych rośnie wraz z zawartością obrazu. Dwa małe obrazy mają zazwyczaj 10–50 KB. Osadzanie obrazów ma szerszy budżet niż sam tekst. Ta strona używa profilu structural.

Uwagi dotyczące bezpieczeństwa

W trybie ścieżki pliku odczyt z systemu plików serwera odbywa się z uprawnieniami procesu serwera. Ogranicz, które ścieżki host może przekazywać. Nie pozwalaj niezaufanym wywołującym wskazywać w source dowolnych plików serwera. Tryb base64 przenosi wbudowane bajty, dzięki czemu nie ujawnia ścieżki serwera.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Obraz jest obiektem XObject obrazu malowanym przez `Do`.	ISO 32000-2	§8.9
Obrazy są obiektami zewnętrznymi malowanymi w treści strony.	ISO 32000-2	§8.8

Kontekst komercyjny

Nie dotyczy — wszystkie narzędzia są zawarte w Core.

Dostępność transportu

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	Duże ładunki base64 powiększają ramkę stdio.
REST	Tak	W przypadku dużych zasobów preferuj multipart lub ścieżkę na serwerze.
gRPC	Tak	Unary; wbudowanego base64 dotyczą ograniczenia rozmiaru wiadomości.

Poziom ryzyka HITL

create_pdf ma poziom Bezpieczne, add_image ma poziom Ostrożnie, a output_pdf ma poziom Wymagane zatwierdzenie — obniżony do poziomu Przegląd w trybie base64. Odczyt w trybie ścieżki odbywa się po stronie serwera i nie podlega osobnej bramce, więc ogranicz go w warstwie zasad (Poziomy ryzyka HITL).

Koperta JSON dla bramki potwierdzenia

Dane wyjściowe base64 w tym przykładzie:

{ "allowed": true }