Introduzione

Ogni funzionalità in Aspose.PDF FOSS per TypeScript è raggiunta attraverso due classi: Document e Page. Document gestisce la collezione di pagine e tutto ciò che è a livello di documento — metadati, segnalibri, etichette di pagina e salvataggio/caricamento — mentre ogni Page in doc.Pages gestisce tutto ciò che è legato a quella singola pagina: contenuto, annotazioni e campi modulo. Una volta familiarizzati con queste due classi, il resto della superficie della libreria — conversione, annotazioni, moduli, sicurezza — è in realtà solo altri metodi sugli stessi due oggetti.

Questo post è uno sguardo più approfondito alle parti di quella superficie di base che il post introduttivo menziona solo di sfuggita: assemblare documenti a partire da altri documenti, creare pagine dal nulla, aggiungere un albero di segnalibri per la navigazione e etichettare il contenuto per l’accessibilità. Tutte e quattro sono semplici chiamate di metodo — nessun modulo separato da importare, nessuna dipendenza aggiuntiva oltre al pacchetto @asposefoss/pdf stesso.

Queste sono le operazioni che emergono una volta che una pipeline PDF supera “apri un file, modificalo, salvalo”: combinare report da diverse fonti in un unico documento, generare pagine programmaticamente invece di partire da un modello, e rendere l’output navigabile e accessibile anziché solo visivamente corretto.

Cosa è incluso

Assemblare e Riorganizzare Documenti

Document.Split() suddivide un documento in un nuovo Document a pagina singola per pagina, in ordine di pagina. Document.ExtractPages() copia un insieme dato di numeri di pagina indicizzati a partire da 1 in un nuovo Document autonomo, nell’ordine fornito — la stessa pagina può essere ripetuta. Le pagine di un documento possono anche essere copiate in un altro: Document.Append() copia ogni pagina di un documento sorgente alla fine del documento di destinazione, e Document.InsertPage() copia una singola pagina tra documenti in una posizione specifica indicizzata a partire da 1.

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

const report = Document.OpenFile('report.pdf');

const parts = report.Split();                      // one Document per page
const chapter = report.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

const cover = Document.OpenFile('cover.pdf');
report.InsertPage(1, cover.Pages[0]);               // copy a single page across documents
report.Append(chapter);                             // copy chapter's pages onto report

report.WriteTo('assembled.pdf');

Diversi documenti possono anche essere combinati in uno solo in una singola chiamata con Document.Merge(), che crea un nuovo Document dalle copie di ogni pagina di ogni documento passato, in ordine.

Creare pagine da zero

Document.New() crea un documento dal nulla: zero pagine quando un formato è omesso, o una pagina vuota del PageFormat fornito quando ne viene passato uno. Pagine vuote aggiuntive provengono da Document.AddPage(), che accetta anche un PageFormat (o un Page esistente per copiare le dimensioni). Il testo viene disegnato su una pagina con Page.AddText(), posizionato a un punto (x, y) nello spazio utente PDF.

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

const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

Segnalibri e navigazione del documento

La struttura del documento (il pannello dei segnalibri che la maggior parte dei lettori PDF mostra accanto alla pagina) viene letta con Document.GetOutlines() e sostituita integralmente con Document.SetOutlines(), ciascuna operante su un albero di valori OutlineItem. Ogni OutlineItem contiene un Title, una destinazione Dest, e opzionalmente Children per voci nidificate, più suggerimenti di visualizzazione come Open (espanso per impostazione predefinita) e Bold.

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

const items: OutlineItem[] = [
  { Title: 'Introduction', Dest: { name: 'intro' } },
  {
    Title: 'Chapters',
    Open: true,
    Children: [
      { Title: 'Chapter 1', Dest: { name: 'ch1' } },
      { Title: 'Chapter 2', Dest: { name: 'ch2' } },
    ],
  },
];
doc.SetOutlines(items);

Le destinazioni nominate in questo modo ({ name: 'intro' }) si risolvono tramite la tabella delle destinazioni nominate del documento, che Document.GetNamedDestinations() e Document.SetNamedDestination() gestiscono direttamente quando un segnalibro deve puntare a una destinazione non legata al contenuto della pagina.

Testo strutturato e marcatura di accessibilità

Document.GetStructTree() restituisce l’albero di struttura logica del documento (o null quando il documento non è marcato), e Document.CreateStructTree() ne crea uno, marcando il documento come Tagged. Una volta che esiste un albero di struttura, Page.GetStructuredText() restituisce il testo della pagina come valori TextBlock — frammenti posizionati già raggruppati in linee e blocchi simili a paragrafi — che costituiscono l’input da cui parte una passata di marcatura manuale: percorrere i blocchi, decidere quali sono intestazioni rispetto al testo del corpo, e aggiungere gli elementi corrispondenti all’albero.

function handTagPage(doc: Document, page: Page, heading: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('handTagPage: the document is not tagged yet');
  for (const block of page.GetStructuredText()) {
    const text = block.text.trim();
    if (text.length === 0) continue;
    const el = root.Append(text.startsWith(heading) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

Un albero di struttura con tag è ciò su cui si basano le funzionalità a valle: l’esportazione semantica HTML rielabora il flusso a partire da esso invece di ricorrere a un layout euristico semplice, e Document.ValidatePdfUa() verifica il documento rispetto a un sottoinsieme dello standard di accessibilità PDF/UA che dipende dalla presenza dei tag.

Guida rapida

Installa il pacchetto, poi apri un documento, estrai e ricombina un sottoinsieme delle sue pagine e salva il risultato:

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('report.pdf');

const chapter = doc.ExtractPages([3, 4, 5]);   // subset (1-based, repeats allowed) as a new Document
const cover = Document.OpenFile('cover.pdf');

doc.InsertPage(1, cover.Pages[0]);             // copy a single page across documents
doc.Append(chapter);                           // copy chapter's pages onto doc

doc.WriteTo('assembled.pdf');

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 c’è alcun watermark di valutazione, limite d’uso 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 nelle fasi iniziali. Node.js (>=22) è l’unico requisito di runtime, e il pacchetto non ha altre dipendenze di terze parti.

Iniziare

Risorse correlate