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 y Document.Open() para datos Uint8Array en memoria.
  • Los números de página pasados a métodos como RemovePage() y ExtractPages() son basados en 1, mientras que doc.Pages es una matriz basada en 0.
  • Pase { compressed: true } a Document.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.Rect para calcular posiciones relativas al ancho y alto reales de la página en lugar de codificar coordenadas de forma fija.

Problemas comunes

ProblemaCausaSolución
Document.Open() / OpenFile() lanza InvalidPasswordErrorEl 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 incorrectaLos números de página pasados a RemovePage() son base 1, no base 0Pase un número de página basado en 1, distinto del índice de matriz doc.Pages
La salida de WriteTo() es mayor de lo esperadoEl guardado por defecto no utiliza compresión xref/object-streamPase { 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étodoDescripción
DocumentPunto 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
PageUna 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

Ver también

 Español