Come convertire documenti PDF in TypeScript

Questa guida mostra come convertire il contenuto PDF in altri formati con Aspose.PDF FOSS per TypeScript. Page esporta una singola pagina come SVG o un’immagine raster; Document esporta l’intero file come HTML, Markdown o DOCX, e può convalidare e convertire un documento in PDF/A. Richiede Node.js 22 o versioni successive.

Guida passo-passo

Passo 1: Installa il pacchetto

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

Verifica l’installazione importando la classe Document in un nuovo file TypeScript — questa riga dovrebbe risolversi senza errori una volta installato il pacchetto:

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

Passo 2: Importa le classi richieste

Importa Document per aprire il file; i metodi di conversione usati di seguito vengono chiamati direttamente sulle istanze Document e Page restituite, quindi non sono necessari ulteriori import:

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

Passo 3: Converti una pagina in SVG o in un’immagine raster

Page.ToSvg() restituisce una stringa <svg> autonoma. Page.ToImage() rende la pagina in byte raster; scale è relativo ai 72 DPI nativi del PDF, quindi scale: 2 rende a 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

Passo 4: Converti un documento in HTML o Markdown

Document.ToHtml() nella sua modalità predefinita (semantica) riorganizza il contenuto dall’albero di struttura in intestazioni e paragrafi; passa { mode: 'fixed' } per riprodurre ogni pagina come SVG posizionato e testo assolutamente posizionato invece. Document.ToMarkdown() genera Markdown GFM per l’intero documento:

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

La modalità semantica legge l’albero di struttura costruito da Document.GetStructTree() / Document.CreateStructTree() — su un documento non etichettato ricade su un corpo euristico e l’esportazione perde la sua struttura di intestazioni.

Passo 5: Converti un documento in DOCX

Document.ToDocx() restituisce .docx byte con contenuto riorganizzato e immagini incluse; passa { mode: 'textbox' } per mantenere la geometria fissa di ciascuna pagina invece di riorganizzare:

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

Passo 6: Convalida e Converti in PDF/A

Document.ValidatePdfA(level), Document.ValidatePdfX(level) e Document.ValidatePdfUa() restituiscono un ValidationReport che descrive se il documento soddisfa lo standard nominato. Document.ConvertToPdfA(level, opts) restituisce un ConversionReport che elenca le correzioni applicate e i problemi ancora irrisolti. Esegui la conversione su una copia Document.ExtractPages() quando il documento attivo deve rimanere salvato non convertito:

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();

Problemi Comuni e Correzioni

Document.ToHtml() perde la struttura dei titoli. La modalità semantica percorre l’albero della struttura, quindi deve essere eseguita dopo un passaggio di etichettatura — oppure Document.AutoTag() o un’etichettatura manuale tramite StructTreeRoot.Append(). ToHtml() ricade su un corpo euristico quando GetStructTree() returns null.

ConvertToPdfA() modifica il file che intendevi mantenere non convertito. Esegui la conversione su una copia da Document.ExtractPages(), quindi salva la copia separatamente — ConvertToPdfA() modifica il documento su cui viene chiamato.

ValidatePdfA() riporta errori la prima volta che viene eseguito. Una causa comune è la non incorporazione di font standard e un /OutputIntent — controlla report.Passed e i risultati delle singole regole per vedere quali condizioni non sono state soddisfatte.

Page.ToImage() l’output sembra a bassa risoluzione. scale è relativo a 72 DPI; aumentalo (ad esempio { scale: 2 } per 144 DPI) per un output di qualità stampa.

Domande frequenti

Qual è la differenza tra l’esportazione semantica e fissa di HTML?

La modalità semantica riformatta il documento dalla sua struttura ad albero in markup che viene visualizzato correttamente in un browser a qualsiasi larghezza. La modalità fissa riproduce ogni pagina come SVG posizionato e testo assolutamente posizionato, corrispondendo esattamente al layout originale.

Il `Document.ToDocx()` preserva il layout originale della pagina?

Per impostazione predefinita, ToDocx() riformatta il contenuto. Fornisci { mode: 'textbox' } per mantenere invece la geometria fissa di ciascuna pagina.

Come verifico se un documento soddisfa PDF/A prima di convertirlo?

Chiama Document.ValidatePdfA(level) (ad esempio '2b') e ispeziona il ValidationReport restituito — questo riporta lo stato attuale senza modificare il documento.

Posso convertire solo un sottoinsieme di pagine?

Sì — costruisci prima un sottoinsieme Document con Document.ExtractPages(), poi chiama il metodo di conversione (ToHtml(), ToDocx(), ConvertToPdfA(), e così via) su quel sottoinsieme.