Introduzione

Il post introduttivo mostra la forma di base della conversione: Document.ToHtml(), Document.ToMarkdown() e Document.ToDocx(), ciascuno chiamato senza argomenti per ottenere un valore predefinito ragionevole. Ognuno di questi metodi accetta un oggetto opzioni che cambia ciò che realmente viene prodotto — markup semantico rispetto a una copia fedele al pixel, un documento Word riformattabile rispetto a uno che riproduce l’esatta disposizione di ogni pagina.

Questo post copre quelle opzioni, oltre a una direzione di conversione che l’introduzione non affronta affatto: convalidare un documento rispetto agli standard PDF/A, PDF/X e PDF/UA e rimediarlo per conformarlo a Document.ConvertToPdfA() e ai suoi fratelli.

Cosa è incluso

HTML Export: Semantico vs Fisso

Document.ToHtml() chiamato senza opzioni percorre l’albero di struttura del documento e genera markup riformattabile — intestazioni e paragrafi che si leggono naturalmente in un browser a qualsiasi larghezza. Questa modalità dipende dal documento etichettato prima (Document.CreateStructTree() o un passaggio di etichettatura equivalente); senza un albero di struttura, l’esportazione ricade in un semplice corpo euristico invece di un vero markup semantico. Passare { mode: 'fixed', fonts: 'embed' } commuta a una strategia di rendering completamente diversa: ogni pagina diventa SVG posizionato e testo posizionato assolutamente, con ogni programma di font incorporabile inserito inline come un WOFF base64 @font-face così la pagina appare identica anche senza che il lettore abbia i font installati.

// Semantic mode reflows from the structure tree, so this must run after the
// tagging pass: ToHtml falls back to a heuristic body when GetStructTree() is
// null, and the export loses its heading structure silently.
const semantic = doc.ToHtml();
const fixed = doc.ToHtml({ mode: 'fixed', fonts: 'embed' });

I due output servono a scopi diversi: il HTML semantico è ciò che desideri per la lettura o la ripubblicazione di contenuti sul web, e il HTML fisso è ciò che vuoi quando l’esatta disposizione visiva della pagina deve sopravvivere invariata in un browser.

Esportazioni Word e Vettoriali

Document.ToDocx() chiamato senza opzioni produce un .docx riformattato: paragrafi e immagini che un elaboratore di testi può riavvolgere e modificare come un documento normale. Passare { mode: 'textbox' } invece mantiene la geometria propria di ogni pagina, posizionando il contenuto in caselle di testo fisse anziché lasciarlo riformattare — più vicino a una copia visiva fedele che a un documento modificabile. Page.ToSvg() rende una singola pagina in una stringa <svg> autonoma, utile quando è necessaria una copia vettoriale, indipendente dalla risoluzione, di una pagina anziché un’immagine raster.

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

const doc = Document.OpenFile('in.pdf');
const svg = doc.Pages[0].ToSvg();               // standalone <svg> string
const docx = doc.ToDocx();                       // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' });   // .docx keeping each page's own geometry

Validazione e conversione a PDF/A, PDF/X e PDF/UA

Document.ValidatePdfA(), Document.ValidatePdfX() e Document.ValidatePdfUa() verificano ciascuno il documento rispetto a un sottoinsieme curato e verificabile da macchine dello standard corrispondente — PDF/A (ISO 19005) per l’archiviazione a lungo termine, PDF/X (ISO 15930) per la produzione di stampa e PDF/UA (ISO 14289-1) per l’accessibilità — e restituiscono un ValidationReport con un flag Passed che riassume il risultato. Document.ConvertToPdfA() (e l’equivalente ConvertToPdfX()/ConvertToPdfUa()) tenta di correggere il documento verso quel livello, quindi riesegue la validazione, restituendo un ConversionReport che elenca le azioni effettivamente applicate e le problematiche ancora non risolte.

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

const doc = Document.OpenFile('in.pdf');
const pdfa = doc.ValidatePdfA('2b');
console.log(`validate: PDF/A-2b ${pdfa.Passed ? 'passes' : 'fails'}`);

// Conversion runs against a copy: the live document is still saved
// unconverted, so ConvertToPdfA must never touch it directly.
const pages = doc.Pages;
const allPages: number[] = [];
for (let i = 1; i <= pages.length; i++) allPages.push(i);
const copy = doc.ExtractPages(allPages);
const conversion = copy.ConvertToPdfA('2b');

console.log(`pdf/a convert: ${conversion.applied.length} action(s) applied, `
  + `${conversion.unresolved.length} unresolved`);
console.log(`result: ${conversion.passed ? 'passes' : 'still fails'} PDF/A-2b`);

La conversione non garantisce di raggiungere la piena conformità in un solo passaggio — le cause più comuni di un errore residuo includono font non incorporati e un’intenzione di output mancante, entrambi visibili in conversion.unresolved.

Avvio rapido

Installa il pacchetto, quindi genera una pagina in SVG e l’intero documento in HTML riformattato e DOCX:

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
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('in.pdf');

const svg = doc.Pages[0].ToSvg();   // standalone <svg> string
const html = doc.ToHtml();          // reflowable HTML (falls back without a structure tree)
const docx = doc.ToDocx();          // .docx bytes, reflowed, images in the package

// fs.writeFileSync('page1.svg', svg);
// fs.writeFileSync('out.html', html);
// fs.writeFileSync('out.docx', docx);

Formati supportati

FormatoEstensioneLeggiScrivi
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Open Source e Licenze

Aspose.PDF FOSS per TypeScript è rilasciato sotto licenza MIT, con il codice sorgente pubblicato su GitHub. Non esiste alcun watermark di valutazione, limite di utilizzo o file di licenza separato da gestire, e la libreria può essere usata in prodotti commerciali senza royalties.

Il pacchetto è attualmente alla versione 0.1.0, a testimonianza di uno sviluppo attivo in fase iniziale. Node.js (>=22) è l’unico requisito di runtime e il pacchetto non ha altre dipendenze di terze parti.

Guida introduttiva

Risorse correlate