Sterowanie czcionkami i typografią tekstu w NextPDF Connect

W skrócie

Zbuduj dokument z wieloma stylami tekstu, zmieniając czcionki między blokami. set_font ustawia aktywny krój pisma, styl i rozmiar. Ten stan obowiązuje przy każdym kolejnym wywołaniu add_text, dopóki nie zostanie zmieniony. Potrzebne są create_pdf, set_font, add_text oraz output_pdf — wszystkie należą do narzędzi Core. Parametry stanu tekstu sterują renderowaniem glifów (ISO 32000-2 §9).

Instalacja

composer require nextpdf/server

Skonfiguruj transport. Możesz korzystać z trzech wbudowanych rodzin czcionek bez dodawania plików czcionek: helvetica, times oraz courier.

Przegląd koncepcyjny

set_font przyjmuje family, style ("", "B", "I", "BI", "U") oraz size. Ustawiona czcionka obowiązuje przy każdym późniejszym wywołaniu add_text, dopóki ponownie nie wywołasz set_font. Automatyczne resetowanie nie jest wykonywane. Gdy add_text zawiera font_size, ta wartość nadpisuje aktywny rozmiar tylko dla tego jednego wywołania. Rozmiar z set_font wraca przy następnym wywołaniu. Tekst jest emitowany przez operatory wyświetlania tekstu w kolejności strumienia treści (ISO 32000-2 §9.4). add_text nie ma parametru koloru. Kolor tekstu wynika z koloru wypełnienia w stanie graficznym dokumentu.

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwiera sesję	Bezpieczne
`set_font`	Ustawia aktywny typeface/style/rozmiar	Ostrożność
`add_text`	Pisze tekst aktywną czcionką	Ostrożność
`output_pdf`	Renderuje i zwraca plik PDF	Wymagane zatwierdzenie / Przegląd (base64)

Katalog narzędzi jest obowiązującym katalogiem referencyjnym. Dostępne narzędzia zależą od zainstalowanego poziomu.

Przykład kodu — szybki start

create_pdf (A4 pionowo) → document_id.
set_font (helvetica, B, 24), a następnie add_text (tytuł, wyśrodkowany).
set_font (helvetica, "", 12), a następnie add_text (wyjustowana treść).
set_font (courier, I, 10), a następnie add_text (fragment kodu).
output_pdf.

Przykład kodu — produkcja

Ustawiaj czcionkę jawnie przed każdym blokiem, w którym typografia ma znaczenie. Nigdy nie polegaj na stanie dziedziczonym między logicznymi sekcjami. Z nadpisania font_size, obowiązującego w pojedynczym wywołaniu, korzystaj wyłącznie przy jednorazowym wyróżnieniu, ponieważ nie jest ono utrzymywane. Buduj dokument sekcja po sekcji i sprawdzaj, czy każde add_text zwraca position.

Przypadki brzegowe i pułapki

Nieznana rodzina. Wszystko poza helvetica/times/courier (na przykład arial) jest odrzucane.
Pusta rodzina. family musi być niepustym ciągiem znaków.
Nieprawidłowy styl. Używaj kodów zapisanych wielkimi literami. "bold" jest odrzucane.
Niedodatni rozmiar. size musi być liczbą dodatnią.
Rozmiar w pojedynczym wywołaniu jest tymczasowy. Nie zmienia stanu set_font.

Wydajność

Wbudowane czcionki zwiększają rozmiar pliku w pomijalnym stopniu, a wynik ma kilka KB. Profil to structural.

Uwagi dotyczące bezpieczeństwa

Tryb base64 nie powoduje żadnych skutków ubocznych w systemie plików. Wbudowane czcionki nie wczytują zewnętrznych plików czcionek, więc ten przepis nie ma powierzchni ataku związanej z parsowaniem czcionek.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Tekst jest wyświetlany przez operatory tekstu w kolejności strumienia.	ISO 32000-2	§9.4
Parametry stanu tekstu sterują renderowaniem glifów.	ISO 32000-2	§9

Kontekst komercyjny

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

Dostępność transportów

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

Poziom ryzyka HITL

create_pdf Bezpieczne; set_font/add_text Ostrożność; output_pdf Wymagane zatwierdzenie, obniżone do poziomu Przeglądu w trybie base64 (Poziomy ryzyka HITL).

Koperta JSON bramki potwierdzenia

Wynik base64:

{ "allowed": true }