Nucleo API
API principale
Questa guida mostra come aprire, modificare, assemblare e salvare documenti PDF con le classi Document e Page — i punti di ingresso per ogni operazione in Aspose.PDF FOSS per TypeScript. Document carica, crea, assembla e salva interi file PDF; Page, raggiunta tramite doc.Pages, espone operazioni di testo, immagine, annotazione e flusso di contenuti per pagina.
Ciclo di vita del documento
Document.OpenFile() apre un PDF da un percorso file; Document.Open() accetta un Uint8Array in memoria. Le pagine possono essere ispezionate e modificate sul posto, e Document.WriteTo() scrive il risultato nuovamente — opzionalmente con compressione xref-stream e object-stream.
import { Document } from '@asposefoss/pdf';
// Open from disk (or Document.Open(uint8array) for in-memory data)
const doc = Document.OpenFile('input.pdf');
// Inspect and edit pages
const pages = doc.Pages;
console.log(pages.length);
pages[0].Rotate = 90;
doc.RemovePage(2); // 1-based page number
doc.Reorder([3, 1, 2]);
// Metadata
doc.SetMetadata({ title: 'Report', author: 'Jane', custom: { Dept: 'R&D' } });
// Save
doc.WriteTo('output.pdf'); // or: const bytes = doc.Save();
doc.WriteTo('small.pdf', { compressed: true }); // xref stream + object streams
Divisione, unione ed estrazione delle pagine
Document.Split() restituisce un Document per pagina. Document.ExtractPages() accetta un elenco di pagine basato su indice 1, con ripetizioni consentite, e restituisce un nuovo Document contenente solo quelle pagine. Document.Append() e Document.InsertPage() copiano pagine tra documenti, e Document.Merge() combina più documenti in uno.
const parts = doc.Split(); // one Document per page
const chapter = doc.ExtractPages([3, 4, 5]); // subset (1-based, repeats allowed) as a new Document
docA.Append(docB); // copy all of docB's pages onto docA
docA.InsertPage(1, docB.Pages[0]); // copy a single page across documents
Creazione di un nuovo documento
Document.New() avvia un documento vuoto a un dato PageFormat. Page.AddText() inserisce testo posizionato, e Document.AddPage() aggiunge ulteriori pagine, incluso un formato ruotato come PageFormat.A4.landscape().
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');Filigrane e numeri di pagina
Page.AddText() supporta anche rotazione, colore e opacità, il che è sufficiente per generare un numero di pagina e una filigrana diagonale senza classi aggiuntive.
const doc = Document.OpenFile('in.pdf');
const page = doc.Pages[0];
// Page number, right-aligned near the bottom-right corner.
const w = page.Rect[2] - page.Rect[0];
page.AddText(`Page ${page.Number}`, w - 40, 20, { fontSize: 10, align: 'right' });
// Semi-transparent diagonal watermark, centered on the page.
page.AddText('DRAFT', page.Rect[2] / 2, page.Rect[3] / 2, {
font: 'Times-Bold', fontSize: 64, color: [0.7, 0.7, 0.7], opacity: 0.4, rotate: 45, align: 'center',
});
doc.WriteTo('out.pdf');Introspezione del flusso di contenuto
parseContentStream() decodifica il flusso grezzo /Contents di una pagina in un elenco di coppie operatore/operando, e serializeContentStream() converte un elenco di operatori modificato nuovamente in byte.
import { parseContentStream, serializeContentStream } from '@asposefoss/pdf';
const ops = parseContentStream(doc.Pages[0].Contents);
// ops: { operator: string, operands: PdfObject[], inlineImage?: {...} }[]
for (const op of ops) {
if (op.operator === 'Tj') console.log('text op:', op.operands);
}
const bytes = serializeContentStream(ops); // round-trips operators + operands
Flusso di testo a più colonne
Page.AddTextBlock() indirizza una lunga stringa di testo in una regione rettangolare e restituisce il testo che non è stato inserito, il quale può essere passato a una seconda chiamata per continuare il flusso in un’altra colonna.
const rest = page.AddTextBlock(longText, [72, 600, 200, 150], {
font: 'Times-Roman', fontSize: 11, align: 'justify', valign: 'top', leading: 14,
});
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // continue into a 2nd column
Suggerimenti e migliori pratiche
- Usa
Document.OpenFile()per i percorsi dei file eDocument.Open()per i datiUint8Arrayin memoria. - I numeri di pagina passati a metodi come
RemovePage()eExtractPages()sono basati su 1, mentredoc.Pagesè un array basato su 0. - Passa
{ compressed: true }aDocument.WriteTo()per abilitare la compressione xref-stream e object-stream in output. Document.ExtractPages()accetta numeri di pagina ripetuti, quindi la stessa pagina di origine può apparire più di una volta nel risultato.- Leggi
page.Rectper calcolare le posizioni relative alla larghezza e all’altezza effettive della pagina, invece di codificare manualmente le coordinate.
Problemi comuni
| Problema | Causa | Correzione |
|---|---|---|
Document.Open() / OpenFile() lancia InvalidPasswordError | Il PDF è protetto da password e non è stata fornita alcuna password (o è stata fornita quella sbagliata) | Passa { password: '...' } a Document.OpenFile() / Document.Open() |
RemovePage() rimuove la pagina sbagliata | I numeri di pagina passati a RemovePage() sono basati su 1, non su 0 | Passa un numero di pagina basato su 1, distinto dall’indicizzazione dell’array doc.Pages |
WriteTo() output è più grande del previsto | Il salvataggio predefinito non utilizza la compressione xref/object-stream | Passa { compressed: true } a Document.WriteTo() |
FAQ
Document.Open() accetta sia percorsi di file che dati in memoria?
Document.OpenFile() si apre da un percorso di file; Document.Open() accetta un Uint8Array di byte in memoria.
La numerazione delle pagine è basata su 0 o su 1?
Entrambe, a seconda del API: doc.Pages è un semplice array a base 0, ma metodi come RemovePage() e ExtractPages() accettano numeri di pagina a base 1.
Posso cifrare un documento mentre lo salvo?
Sì — passa un’opzione encrypt a WriteTo() / Save() con algorithm: 'aes256' | 'aes128' | 'rc4' e password opzionali per utente/proprietario.
Come ridurre la dimensione del file di output?
Passa { compressed: true } a Document.WriteTo() per abilitare la compressione xref-stream e object-stream.
Posso ispezionare gli operatori grezzi del content-stream di una pagina?
Sì — parseContentStream(doc.Pages[0].Contents) restituisce l’elenco degli operatori, e serializeContentStream() converte un elenco modificato nuovamente in byte.
API Reference Riepilogo
| Classe / Metodo | Descrizione |
|---|---|
Document | Punto di ingresso centrale per la creazione, il caricamento e il salvataggio dei documenti PDF |
Document.OpenFile() / Document.Open() | Carica un PDF da un percorso del file o da byte in memoria |
Document.New() | Inizia un documento vuoto con un dato PageFormat |
Document.WriteTo() / Document.Save() | Scrivi il documento su un percorso del file o restituisci i byte |
Document.Split() / Document.Merge() / Document.ExtractPages() | Dividi, unisci ed estrai pagine tra documenti |
Document.Append() / Document.InsertPage() | Copia le pagine da un documento a un altro |
Page | Una singola pagina PDF; espone metodi per testo, immagine, annotazione e content-stream |
Page.AddText() / Page.AddTextBlock() | Aggiungi testo posizionato o a flusso a una pagina |
parseContentStream() / serializeContentStream() | Analizza e riserializza gli operatori raw del content-stream di una pagina |