Pro edycja

Converter — pełna dokumentacja referencyjna

W skrócie

NextPDF\Pro\Converter eksportuje istniejący plik PDF do pozycjonowanego HTML, uproszczonego SVG lub zwykłego tekstu oraz dzieli zawartość dokumentu na typowane regiony strukturalne. Ta pełna dokumentacja referencyjna wylicza powierzchnię publicznego API, macierz pokrycia operatorów, kontrakt zachowania oraz tryby awarii. Jest to eksporter wydobywający zawartość, a nie renderer odwzorowujący piksel w piksel.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga funkcji czasu wykonania nie bramkuje tego modułu. Klasy konwertera rozwiązują się zawsze, gdy pakiet Pro jest zainstalowany i licencjonowany.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub zawodzi z	Uwagi
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Eksportuje każdą stronę zawierającą tekst do jednego samodzielnego dokumentu HTML5	`ConversionResult` (cel `Html5`)	`InvalidArgumentException`, gdy `$pdfData` jest puste	Pusta konfiguracja przyjmuje domyślnie `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Eksportuje jedną stronę do samodzielnego dokumentu SVG	`ConversionResult` (cel `Svg`; `pageCount` zawsze wynosi 1)	`InvalidArgumentException`, gdy `$pdfData` jest puste	`$pageIndex` poza zakresem daje SVG zawierające wyłącznie tło
`PdfToTextConverter::convert()`	`string $pdfData`	Wydobywa zdekodowany tekst ze wszystkich stron, rozdzielony znacznikiem podziału strony	`ConversionResult` (cel `PlainText`)	`InvalidArgumentException`, gdy `$pdfData` jest puste	Tylko ten cel dekoduje sekwencje ucieczki ciągów literalnych
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Wydobywa zdekodowany tekst dla jednej strony liczonej od zera	`string`	Nie zgłasza wyjątku; zwraca `''` dla brakującej strony lub pustego wejścia	W przeciwieństwie do `convert()`, brak zabezpieczenia przed pustym wejściem
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Klasyfikuje zawartość strony do typowanych segmentów strukturalnych, wykorzystując heurystyki przestrzenne i czcionek	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException`, gdy wejście jest puste lub struktura PDF nie może zostać sparsowana	Oparty na regułach; nie wykonuje wnioskowania AI
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Niezmienne ustawienia konwersji	`ConversionConfig`	—	`embedFonts` i `embedImages` są przyjmowane, lecz nieużywane w 3.1.0
`ConversionResult::size()`	—	Długość wygenerowanego wyjścia w bajtach	`int`	—	Publiczne pola tylko do odczytu: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Zgłasza, czy wyjście jest niepuste	`bool`	—	Powłoki dokumentów HTML i SVG nigdy nie są puste; zamiast tego sprawdź `pageCount`
`ConversionTarget`	Przypadki oparte na łańcuchach `Html5`, `Svg`, `PlainText`	Wybiera cel eksportu	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` mapuje na `html`, `svg`, `txt`

Sygnatury punktów wejścia:

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

Kontrakt zachowania

Wejściem są surowe bajty PDF; wyjściem jest obiekt wartości ConversionResult. Trzy konwertery eksportu dzielą ten sam model skanowania: lokalizują granice stream/endstream, wyodrębniają bloki tekstowe BT/ET i parsują operatory pokazywania tekstu. Nie parsują tablicy odwołań skrośnych i nie dekompresują skompresowanych strumieni. DocumentSegmentationEngine różni się: rozwiązuje zwiastun (trailer), katalog i drzewo stron oraz dekompresuje zawartość stron FlateDecode przed klasyfikacją.

Pokrycie operatorów:

Operator PDF	HTML	SVG	Tekst
`Tj` (pokaż ciąg)	tak	tak	tak
`TJ` (pokaż tablicę)	tak	tak	tak
`'` (przejdź + pokaż)	nie	nie	tak
`Td` / `Tm` (pozycja)	tak	tak	nd.
`Tf` (rozmiar czcionki)	tak	tak	nd.
`re` (prostokąt)	nie	tak	nie
`m` / `l` (linia)	nie	tak	nie
`RG` (obrys RGB)	nie	tak (stosowany do obrysu prostokąta/linii)	nie
krzywe, cieniowanie, przycinanie, obrazy	nie	nie	nie

Pozycjonowanie. Każdy blok BT/ET rozwiązuje jedną pozycję z pierwszego dopasowania Td lub Tm; Tm ma pierwszeństwo, gdy występują oba. Oś Y jest odwracana z przestrzeni użytkownika PDF do przestrzeni wyjściowej z początkiem w lewym górnym rogu. Rozmiar czcionki domyślnie wynosi 12 pt, gdy brak Tf.
Geometria strony. HTML i SVG zakładają obszar strony A4 (595 x 842 pt) pomnożony przez scaleFactor. Korzeń SVG niesie odpowiadające atrybuty viewBox, szerokości i wysokości nad białym prostokątem tła.
Kolor obrysu. Operatory RG są rozwiązywane pozycyjnie, więc strumień zmieniający kolor obrysu więcej niż raz koloruje każdy prostokąt i linię według najbliższego poprzedzającego operatora. Składowe są ograniczane do zakresu 0..1 przed konwersją na hex. Wypełnienie prostokąta jest zawsze czarne; operator wypełnienia rg nie jest ewaluowany.
Dekodowanie ciągów. Cel tekstowy dekoduje sekwencje ucieczki ciągów literalnych zgodnie z ISO 32000-2:2020 §7.3.4.2: nazwane sekwencje ucieczki, kody ósemkowe \ddd maskowane do jednego bajtu, kontynuacje wiersza z odwrotnym ukośnikiem oraz usuwanie osamotnionego odwrotnego ukośnika. Cele HTML i SVG emitują surowe bajty spomiędzy nawiasów po ucieczkowaniu HTML lub XML; nie dekodują sekwencji ucieczki.
Składanie wyjścia. Cel tekstowy łączy teksty bloków spacją, a strony znacznikiem --- Page Break --- obramowanym pustymi wierszami. Cel HTML emituje jeden pozycjonowany bezwzględnie <div> na blok tekstowy wewnątrz kontenera strony niosącego skonfigurowaną klasę CSS oraz atrybut data-page.
Determinizm. Dla identycznego wejścia i konfiguracji wygenerowane bajty HTML, SVG lub tekstu są stabilne. processingTimeMs jest pomiarem czasu rzeczywistego i jest wyłączony z powierzchni deterministycznej.

Przypadki brzegowe i tryby awarii

Puste wejście: każdy punkt wejścia convert() i segment() zgłasza InvalidArgumentException (“PDF data must not be empty”). Nie jest generowany żaden częściowy wynik. extractPage() jest wyjątkiem: zwraca '' bez zgłaszania wyjątku.
Strumienie bez BT/ET są pomijane przez konwertery HTML i tekstu. Plik PDF zawierający wyłącznie takie strumienie daje zerowy pageCount z pustym wyjściem tekstowym lub powłokę HTML bez stron.
isValid() sprawdza wyłącznie niepustość wyjścia. Konwertery HTML i SVG zawsze emitują powłokę dokumentu, więc isValid() pozostaje true nawet wtedy, gdy nie znaleziono tekstu; użyj pageCount (HTML, tekst), aby wykryć puste wydobycie.
Zawartość FlateDecode nie jest dekompresowana przez trzy konwertery eksportu. Pliki PDF zawierające wyłącznie skompresowaną zawartość eksportują przez nie niewiele treści lub wcale. segment() dekompresuje strumienie stron FlateDecode.
segment() ogranicza dekompresję rozmiarem pojedynczego strumienia, współczynnikiem kompresji oraz budżetem skumulowanym. Strumień przekraczający pułap degraduje się do pustej zawartości strony zamiast wyczerpywać pamięć; nie zgłasza wyjątku.
segment() zgłasza InvalidArgumentException, gdy zwiastun (trailer), przesunięcie tablicy odwołań skrośnych, katalog dokumentu lub drzewo stron nie mogą zostać rozwiązane.
Indeksowanie stron różni się w zależności od konwertera. Konwertery HTML i tekstu liczą tylko strumienie zawierające tekst; konwerter SVG liczy strumienie zawierające dowolny rozpoznany operator graficzny lub tekstowy. Ten sam $pageIndex może zatem adresować różne strumienie.
Numeryczne korekty kerningu TJ są odrzucane; ciągi tablicy są łączone bez odstępów międzyglifowych.
Mapowanie glif-do-Unicode nie jest stosowane. Tekst złożony czcionkami z niestandardowymi kodowaniami eksportuje się jako surowa sekwencja bajtów.
Obrócony tekst, transformacje nietekstowe oraz przepływ kolumnowy są przybliżane pozycjonowaniem według pierwszego dopasowania i mogą nie odtwarzać oryginalnego układu.
W tym module nie zachodzi żadna operacja kryptograficzna, więc tryb FIPS nie ma zachowania specyficznego dla modułu.

Konformancja

NextPDF dokumentuje funkcje względem cytowanych klauzul. Deklaracje wsparcia opisują zaimplementowane zachowanie; nie są wynikami testów zgodności ani certyfikatami, a NextPDF nie posiada żadnego certyfikatu.

Deklaracja	Klauzula specyfikacji	Status
Operator pokazywania tekstu `Tj` sparsowany	ISO 32000-2:2020 §9.4	Zweryfikowane (zestaw testów jednostkowych)
Operator pokazywania tekstu tablicowego `TJ` sparsowany	ISO 32000-2:2020 §9.4	Zweryfikowane (zestaw testów jednostkowych)
Operator przejdź-i-pokaż `'` sparsowany (tylko cel tekstowy)	ISO 32000-2:2020 §9.4	Zweryfikowane (zestaw testów jednostkowych)
Sekwencje ucieczki ciągów literalnych zdekodowane (tylko cel tekstowy)	ISO 32000-2:2020 §7.3.4.2	Zaimplementowane; bajty zwracane bez zmian, interpretacja zestawu znaków odbywa się dalej
Konstrukcja ścieżki `re`, `m`, `l` rozpoznana (cel SVG)	ISO 32000-2:2020 §8.5.2	Częściowe: podzbiór bez krzywych, zamykania ani ewaluacji trybu malowania
Pełna maszyna stanu tekstu i renderowanie stron	—	Nieobsługiwane (poza zakresem)

Converter parsuje operatory pokazywania tekstu, aby odzyskać zawartość; nie implementuje pełnej maszyny stanu tekstu, więc pozycjonowanie glifów jest przybliżone, a nie dokładne według specyfikacji.

Uwagi programistyczne

Parsowanie jest liniowe względem długości pliku PDF w bajtach. Pamięć odpowiada wejściu powiększonemu o wygenerowany łańcuch wyjściowy. Frontmatter performance_budget jest odniesieniem na pojedyncze wywołanie dla typowego dokumentu biurowego.
Konwertery parsują niezaufane bajty PDF za pomocą ograniczonego skanowania strpos/substr. Nie wykonują osadzonego kodu JavaScript i nie podążają za odwołaniami zewnętrznymi. Traktuj eksportowany HTML jako niezaufaną zawartość i ucieczkuj go dla miejsca docelowego.
Wyjście HTML jest ucieczkowane za pomocą htmlspecialchars (ENT_QUOTES, HTML5); tekst SVG jest ucieczkowany jako XML. Skonfigurowana cssClass jest ucieczkowana przed emisją.
Konsumpcja konfiguracji: scaleFactor dotyczy celów HTML i SVG; cssClass dotyczy tylko HTML; embedFonts i embedImages są zarezerwowane i obecnie nieużywane; pole target nie nadpisuje własnego formatu wyjściowego konwertera.
Konwertery eksportu są dostarczane od wersji 1.9.0; DocumentSegmentationEngine jest dostarczany od wersji 2.1.0 i stanowi podstawę narzędzia Pro MCP segment_document oraz kontraktu segmentacji Interop.
PdfPageExtractor i PdfPageData w tej samej przestrzeni nazw są wewnętrzne dla silnika segmentacji i nie są publicznym API.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.