Núcleo API
API principal
Esta guía muestra cómo abrir, editar, ensamblar y guardar documentos PDF con las clases Document y Page — los puntos de entrada para cada operación en Aspose.PDF FOSS para TypeScript. Document carga, crea, ensambla y guarda archivos PDF completos; Page, accesible a través de doc.Pages, expone operaciones de texto, imagen, anotación y flujo de contenido por página.
Ciclo de vida del documento
Document.OpenFile() abre un PDF a partir de una ruta de archivo; Document.Open() acepta un Uint8Array en memoria. Las páginas pueden inspeccionarse y editarse in situ, y Document.WriteTo() escribe el resultado de nuevo — opcionalmente con compresión de xref-stream y 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
División, fusión y extracción de páginas
Document.Split() devuelve un Document por página. Document.ExtractPages() toma una lista de páginas basada en 1, que permite repeticiones, y devuelve un nuevo Document con solo esas páginas. Document.Append() y Document.InsertPage() copian páginas entre documentos, y Document.Merge() combina varios documentos en 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
Creación de un nuevo documento
Document.New() inicia un documento en blanco en un PageFormat dado. Page.AddText() coloca texto posicionado, y Document.AddPage() agrega más páginas, incluido un formato rotado como 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');Marcas de agua y números de página
Page.AddText() también admite rotación, color y opacidad, lo cual es suficiente para renderizar un número de página y una marca de agua diagonal sin clases adicionales.
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');Introspección del flujo de contenido
parseContentStream() decodifica el flujo bruto /Contents de una página en una lista de pares operador/operando, y serializeContentStream() convierte una lista de operadores editada de nuevo en bytes.
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
Flujo de texto en múltiples columnas
Page.AddTextBlock() fluye una cadena larga de texto dentro de una región rectangular y devuelve cualquier texto que no haya cabido, el cual puede pasarse a una segunda llamada para continuar el flujo en otra columna.
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
Consejos y mejores prácticas
- Utilice
Document.OpenFile()para rutas de archivo yDocument.Open()para datosUint8Arrayen memoria. - Los números de página pasados a métodos como
RemovePage()yExtractPages()son basados en 1, mientras quedoc.Pageses una matriz basada en 0. - Pase
{ compressed: true }aDocument.WriteTo()para habilitar la compresión xref-stream y object-stream en la salida. Document.ExtractPages()acepta números de página repetidos, de modo que la misma página de origen puede aparecer más de una vez en el resultado.- Lea
page.Rectpara calcular posiciones relativas al ancho y alto reales de la página en lugar de codificar coordenadas de forma fija.
Problemas comunes
| Problema | Causa | Solución |
|---|---|---|
Document.Open() / OpenFile() lanza InvalidPasswordError | El PDF está protegido con contraseña y no se proporcionó ninguna contraseña (o la incorrecta) | Pasar { password: '...' } a Document.OpenFile() / Document.Open() |
RemovePage() elimina la página incorrecta | Los números de página pasados a RemovePage() son base 1, no base 0 | Pase un número de página basado en 1, distinto del índice de matriz doc.Pages |
La salida de WriteTo() es mayor de lo esperado | El guardado por defecto no utiliza compresión xref/object-stream | Pase { compressed: true } a Document.WriteTo() |
FAQ
¿Document.Open() acepta tanto rutas de archivo como datos en memoria?
Document.OpenFile() se abre a partir de una ruta de archivo; Document.Open() acepta un Uint8Array de bytes en memoria.
¿La numeración de páginas empieza en 0 o en 1?
Ambas, dependiendo del API: doc.Pages es una matriz simple basada en 0, pero los métodos como RemovePage() y ExtractPages() utilizan numeración de páginas basada en 1.
¿Puedo cifrar un documento al guardarlo?
Sí — pasa una opción encrypt a WriteTo() / Save() con algorithm: 'aes256' | 'aes128' | 'rc4' y contraseñas de usuario/propietario opcionales.
¿Cómo reduzco el tamaño del archivo de salida?
Pasa { compressed: true } a Document.WriteTo() para habilitar la compresión de xref-stream y object-stream.
¿Puedo inspeccionar los operadores crudos del flujo de contenido de una página?
Sí — parseContentStream(doc.Pages[0].Contents) devuelve la lista de operadores, y serializeContentStream() convierte una lista editada de nuevo a bytes.
API Reference Resumen
| Clase / Método | Descripción |
|---|---|
Document | Punto de entrada central para crear, cargar y guardar documentos PDF |
Document.OpenFile() / Document.Open() | Cargar un PDF desde una ruta de archivo o bytes en memoria |
Document.New() | Iniciar un documento en blanco con un PageFormat dado |
Document.WriteTo() / Document.Save() | Escribir el documento en una ruta de archivo o devolver bytes |
Document.Split() / Document.Merge() / Document.ExtractPages() | Dividir, combinar y extraer páginas entre documentos |
Document.Append() / Document.InsertPage() | Copiar páginas de un documento a otro |
Page | Una sola página PDF; expone métodos de texto, imagen, anotación y content-stream |
Page.AddText() / Page.AddTextBlock() | Agregar texto posicionado o con flujo a una página |
parseContentStream() / serializeContentStream() | Analizar y volver a serializar los operadores crudos del content-stream de una página |