Renderowanie tabeli HTML w NextPDF Connect

W skrócie

Renderuj ustrukturyzowane dane tabelaryczne z ciągu znaków zawierającego tabelę HTML. add_table sanityzuje dane wejściowe za pomocą ścisłej listy dozwolonych elementów DOMDocument przed obliczeniem układu, dzięki czemu wynik pozostaje spójny nawet wtedy, gdy znaczniki źródłowe się różnią. Użyj narzędzi Core create_pdf, add_table oraz output_pdf. Tabela jest rozkładana jako siatka row/column (CSS Tables 3 §3.1).

Instalacja

composer require nextpdf/server

Skonfiguruj transport. Dane wejściowe muszą zawierać element główny <table> z wierszami <tr> oraz komórkami <th>/<td>.

Przegląd koncepcyjny

add_table wymusza stałą listę dozwolonych elementów (table, thead, tbody, tfoot, tr, th, td, caption, b, i, u, strong, em, br, p, span). Wszystkie atrybuty są usuwane z każdego elementu — style, class, width, colspan, rowspan, id i pozostałe. Każdy znacznik spoza listy dozwolonych jest zastępowany własną zawartością tekstową. Tekst w komórkach korzysta z aktywnego stanu czcionki dokumentu, ustawianego za pomocą set_font przed add_table. Tekst jest emitowany przez operatory wyświetlania tekstu w kolejności strumienia treści (ISO 32000-2 §9.4). O szerokości kolumn decyduje silnik układu, a nie wbudowany kod CSS.

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
create_pdf	Otwiera sesję	Bezpieczne
set_font	Ustawia czcionkę tekstu w komórkach (opcjonalnie, przed add_table)	Ostrożność
add_table	Sanityzuje i rozkłada tabelę	Ostrożność
output_pdf	Renderuje i zwraca PDF	Wymagana zgoda / Przegląd (base64)

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

Przykład kodu — szybki start

1. create_pdf (A4 pionowo, tytuł) → document_id.
2. add_table z kompletnym ciągiem znaków <table>...</table> (wiersz nagłówka i wiersze danych).
3. output_pdf → base64 lub, z parametrem file_path, zapis pliku objęty bramką.

Kursor przesuwa się poniżej ostatniego wyrenderowanego wiersza, pozostawiając miejsce na następną treść.

Przykład kodu — środowisko produkcyjne

Przed wysłaniem zweryfikuj kod HyperText Markup Language (HTML). Ustaw czcionkę komórek za pomocą set_font, aby uzyskać deterministyczną typografię. Jeśli polegasz na wartości domyślnej, wynikowa czcionka zależy od implementacji. Aby kontrolować, które narzędzia może wywoływać host, ogranicz rejestr za pomocą zasad bezpieczeństwa.

Przypadki brzegowe i pułapki

• Pusty kod HTML lub kod bez tabeli. Dane wejściowe bez <table> zwracają błąd informujący o braku tabeli do wyrenderowania.
• Nieprawidłowe znaczniki. Niezbalansowane znaczniki powodują błąd parsowania, dlatego najpierw zweryfikuj strukturę.
• Tabela szersza niż strona. Zmniejsz liczbę kolumn, skróć treść lub przełącz się na orientację poziomą.
• Przepełnienie. Wysoka tabela przechodzi na nową stronę. Sprawdź position.page w odpowiedzi lub wywołaj add_page z wyprzedzeniem.

Wydajność

Niewielka tabela renderuje się w ramach budżetu, a wynik ma kilka KB. Profil: structural. Sanityzacja przebiega w jednym przejściu po sparsowanym drzewie DOM.

Uwagi dotyczące bezpieczeństwa

Usuwanie atrybutów jest bezwarunkowe i nie można go obejść. Chroni przed wstrzyknięciem stylów i skryptów przez znaczniki komórek. Nie zostanie zachowany żaden wbudowany kod CSS, obsługa zdarzeń ani adres URL javascript:. Lista dozwolonych elementów stanowi granicę zaufania, dlatego nie traktuj wyrenderowanego wyniku jako wiernego odwzorowania dowolnych stylów źródłowych.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Tabele są rozkładane jako siatka komórek row/column.	CSS Tables 3	§3.1
Tekst jest wyświetlany przez operatory tekstu w kolejności strumienia.	ISO 32000-2	§9.4

Kontekst komercyjny

Nie dotyczy — każde narzędzie tutaj należy do Core.

Fragment macierzy obsługi CSS (tylko zweryfikowane)

add_table nie uruchamia ogólnego silnika CSS. Jedynym zachowaniem „CSS” jest stały model siatki tabeli: wiersze i kolumny pochodzą ze struktury tabeli, a silnik układu dobiera szerokości. Stylizacja wbudowana celowo nie jest obsługiwana, ponieważ atrybuty są usuwane. Informacje o obsłudze CSS na poziomie silnika (poza Connect) znajdziesz w macierzy obsługi CSS projektu.

Ograniczenie strumieniowania jednoprzebiegowego

add_table parsuje dostarczone znaczniki do drzewa DOM jednokrotnie i rozkłada je w jednym przejściu. Nie wykonuje ponownego rozkładu na podstawie zewnętrznych arkuszy stylów. Tabela, która przepełnia stronę, przechodzi na następną stronę, zamiast cofać się i wykonywać ponowny rozkład.

Budżet pamięci dla dużych tabel

Bardzo duże tabele utrzymują sparsowane drzewo DOM i rozłożone komórki w pamięci przez całe wywołanie. Podziel duże zbiory danych na wiele wywołań add_table, aby pozostać w ramach budżetu szczytowego zużycia pamięci.

Dostępność transportów

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	Duży kod HTML powiększa ramkę stdio.
REST	Tak	Wyślij kod HTML w treści żądania.
gRPC	Tak	Unary; obowiązują limity rozmiaru komunikatu.

Poziom ryzyka HITL

create_pdf jest na poziomie Bezpieczne; set_font oraz add_table są na poziomie Ostrożność; output_pdf wymaga zgody, a w trybie base64 jest obniżone do poziomu Przegląd. Wyjście do pliku pozostaje na poziomie Wymagana zgoda. Zobacz output-approval.

Koperta JSON bramki potwierdzenia

Wyjście base64:

{ "allowed": true }

Wyjście do pliku zwraca kopertę wyzwania opisaną w output-approval.

Zobacz też

• Typografia czcionek
• Hello world
• Katalog narzędzi