Jak konwertować dokumenty PDF w TypeScript

Ten przewodnik pokazuje, jak konwertować zawartość PDF do innych formatów przy użyciu Aspose.PDF FOSS dla TypeScript. Page eksportuje pojedynczą stronę jako SVG lub obraz rastrowy; Document eksportuje cały plik jako HTML, Markdown lub DOCX, i może zweryfikować oraz skonwertować dokument do PDF/A. Wymaga Node.js 22 lub nowszego.

Przewodnik krok po kroku

Krok 1: Zainstaluj pakiet

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

Zweryfikuj instalację, importując klasę Document w nowym pliku TypeScript — ta linia powinna się rozwiązać bez błędu po zainstalowaniu pakietu:

import { Document } from '@asposefoss/pdf';

Krok 2: Importuj wymagane klasy

Importuj Document, aby otworzyć plik; metody konwersji użyte poniżej są wywoływane bezpośrednio na zwróconych instancjach Document i Page, więc nie są potrzebne dodatkowe importy:

import { Document } from '@asposefoss/pdf';

Krok 3: Konwertuj stronę do SVG lub obrazu rastrowego

Page.ToSvg() zwraca samodzielny ciąg <svg>. Page.ToImage() renderuje stronę do bajtów rastrowych; scale jest względne do natywnej rozdzielczości PDF 72 DPI, więc scale: 2 renderuje przy 144 DPI:

import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const png = doc.Pages[0].ToImage({ scale: 2 }); // Uint8Array of PNG bytes @144 DPI

Krok 4: Konwertuj dokument do HTML lub Markdown

Document.ToHtml() w domyślnym (semantycznym) trybie przetwarza zawartość z drzewa struktury na nagłówki i akapity; przekaż { mode: 'fixed' }, aby zamiast tego odtworzyć każdą stronę jako umieszczone SVG i absolutnie położony tekst. Document.ToMarkdown() generuje GFM Markdown dla całego dokumentu:

const semanticHtml = doc.ToHtml(); // reflowable markup, all pages
const fixedHtml = doc.ToHtml({ mode: 'fixed', fonts: 'embed' }); // positioned, fonts embedded
const markdown = doc.ToMarkdown(); // GFM Markdown, all pages

Tryb semantyczny odczytuje drzewo struktury zbudowane przez Document.GetStructTree() / Document.CreateStructTree() — w przypadku dokumentu bez tagów przechodzi do heurystycznego ciała, a eksport traci strukturę nagłówków.

Krok 5: Konwertuj dokument do DOCX

Document.ToDocx() zwraca .docx bajtów z przetworzoną zawartością i obrazami spakowanymi wewnątrz; przekaż { mode: 'textbox' }, aby zachować stałą geometrię każdej strony zamiast przetwarzania:

const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' }); // .docx keeping each page's own geometry

Krok 6: Zweryfikuj i przekonwertuj do PDF/A

Document.ValidatePdfA(level), Document.ValidatePdfX(level) i Document.ValidatePdfUa() zwracają ValidationReport opisujący, czy dokument spełnia określony standard. Document.ConvertToPdfA(level, opts) zwraca ConversionReport wymieniający, które poprawki zostały zastosowane i które problemy pozostają nierozwiązane. Uruchom konwersję na kopii Document.ExtractPages(), gdy żywy dokument musi pozostać zapisany nieprzekonwertowany:

const report = doc.ValidatePdfA('2b');
console.log(report.Passed);

const copy = doc.ExtractPages(doc.Pages.map((_, i) => i + 1));
const conversion = copy.ConvertToPdfA('2b');
console.log(conversion.applied.length, conversion.unresolved.length, conversion.passed);
copy.Save();

Typowe problemy i rozwiązania

Document.ToHtml() traci strukturę nagłówków. Tryb semantyczny przegląda drzewo struktury, więc musi być uruchomiony po przejściu tagowania — albo Document.AutoTag() lub ręcznie tworzone tagowanie za pomocą StructTreeRoot.Append(). ToHtml() wraca do heurystycznego ciała, gdy GetStructTree() returns null.

ConvertToPdfA() zmienia plik, który zamierzałeś pozostawić nieprzekonwertowany. Uruchom konwersję na kopii z Document.ExtractPages(), a następnie zapisz kopię osobno — ConvertToPdfA() mutuje dokument, na którym zostaje wywołany.

ValidatePdfA() zgłasza błędy przy pierwszym uruchomieniu. Częstą przyczyną są niewbudowane czcionki standardowe i brakujący /OutputIntent — sprawdź report.Passed oraz poszczególne wyniki reguł, aby zobaczyć, które warunki nie zostały spełnione.

Page.ToImage() wyjście wygląda na niską rozdzielczość. scale jest względem 72 DPI; podnieś je (na przykład { scale: 2 } na 144 DPI) dla wyjścia w jakości druku.

Najczęściej zadawane pytania

Jaka jest różnica między semantycznym a stałym eksportem HTML?

Tryb semantyczny przekształca dokument z jego drzewa struktury w znacznikowanie, które dobrze wyświetla się w przeglądarce o dowolnej szerokości. Tryb stały odtwarza każdą stronę jako pozycjonowane SVG oraz absolutnie umieszczony tekst, dokładnie odwzorowując oryginalny układ.

Czy `Document.ToDocx()` zachowuje oryginalny układ strony?

Domyślnie ToDocx() przetwarza treść. Przekaż { mode: 'textbox' }, aby zamiast tego zachować stałą geometrię każdej strony.

Jak sprawdzić, czy dokument spełnia PDF/A przed jego konwersją?

Wywołaj Document.ValidatePdfA(level) (na przykład '2b') i sprawdź zwrócony ValidationReport — to raportuje aktualny stan bez modyfikowania dokumentu.

Czy mogę konwertować tylko podzbiór stron?

Tak — najpierw zbuduj podzbiór Document przy użyciu Document.ExtractPages(), a następnie wywołaj metodę konwersji (ToHtml(), ToDocx(), ConvertToPdfA() i tak dalej) na tym podzbiorze.