Introducción

Cada capacidad en Aspose.PDF FOSS para TypeScript se alcanza a través de dos clases: Document y Page. Document posee la colección de páginas y todo lo relacionado con el documento — metadatos, marcadores, etiquetas de página y guardar/cargar — mientras que cada Page en doc.Pages posee todo lo que corresponde a esa única página: contenido, anotaciones y campos de formulario. Una vez que esas dos clases son familiares, el resto de la superficie de la biblioteca — conversión, anotaciones, formularios, seguridad — es realmente solo más métodos en los mismos dos objetos.

Esta publicación es una mirada más profunda a las partes de esa superficie central que la publicación introductoria solo menciona de pasada: ensamblar documentos a partir de otros documentos, crear páginas desde cero, añadir un árbol de marcadores para la navegación y etiquetar contenido para la accesibilidad. Los cuatro son llamadas directas a métodos — sin módulo separado para importar, sin dependencia extra más allá del paquete @asposefoss/pdf.

Estas son las operaciones que aparecen una vez que una canalización PDF avanza más allá de “abrir un archivo, cambiarlo, guardarlo”: combinar informes de varias fuentes en un solo documento, generar páginas programáticamente en lugar de partir de una plantilla, y hacer que la salida sea navegable y accesible en lugar de solo visualmente correcta.

Qué incluye

Ensamblar y reorganizar documentos

Document.Split() divide un documento en un nuevo Document de una sola página por página, en orden de página. Document.ExtractPages() copia un conjunto dado de números de página basados en 1 en un nuevo Document auto-contenedor, en el orden indicado — la misma página puede repetirse. Las páginas de un documento también pueden copiarse a otro: Document.Append() copia cada página de un documento fuente al final del objetivo, y Document.InsertPage() copia una sola página entre documentos en una posición específica basada en 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');

Varios documentos también pueden combinarse en uno solo en una única llamada con Document.Merge(), que crea un nuevo Document a partir de copias de cada página de cada documento que se le pasa, en orden.

Crear páginas desde cero

Document.New() crea un documento desde cero: cero páginas cuando se omite un formato, o una página en blanco del PageFormat especificado cuando se pasa uno. Páginas en blanco adicionales provienen de Document.AddPage(), que también acepta un PageFormat (o un Page existente para copiar su tamaño). El texto se dibuja en una página con Page.AddText(), posicionado en un punto (x, y) del espacio de usuario 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');

Marcadores y navegación del documento

El esquema del documento (el panel de marcadores que la mayoría de los lectores PDF muestra junto a la página) se lee con Document.GetOutlines() y se reemplaza completamente con Document.SetOutlines(), cada uno trabajando con un árbol de valores OutlineItem. Cada OutlineItem lleva un Title, un destino Dest, y opcionalmente Children para entradas anidadas, además de pistas de visualización como Open (expandido por defecto) y 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);

Los destinos nombrados de esta manera ({ name: 'intro' }) se resuelven a través de la tabla de destinos nombrados del documento, que Document.GetNamedDestinations() y Document.SetNamedDestination() gestionan directamente cuando un marcador necesita apuntar a un destino que no está vinculado al contenido de la página.

Texto estructurado y etiquetado de accesibilidad

Document.GetStructTree() devuelve el árbol de estructura lógica del documento (o null cuando el documento no está etiquetado), y Document.CreateStructTree() crea uno, marcando el documento como Etiquetado. Una vez que existe un árbol de estructura, Page.GetStructuredText() devuelve el texto de la página como valores TextBlock — fragmentos posicionados ya agrupados en líneas y bloques tipo párrafo — que es la entrada con la que trabaja una pasada de etiquetado manual: recorriendo los bloques, decidiendo cuáles son encabezados versus texto del cuerpo, y añadiendo los elementos correspondientes al árbol.

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 árbol de estructura etiquetada es en lo que se basan las funciones posteriores: la exportación semántica HTML se refluye desde él en lugar de recurrir a un diseño heurístico simple, y Document.ValidatePdfUa() verifica el documento contra un subconjunto del estándar de accesibilidad PDF/UA que depende de que la etiquetación esté presente.

Inicio rápido

Instala el paquete, luego abre un documento, extrae y recompone un subconjunto de sus páginas, y guarda el resultado:

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');

Formatos compatibles

FormatoExtensiónLeerEscribir
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Código abierto y licencias

Aspose.PDF FOSS para TypeScript se publica bajo la licencia MIT, con el código fuente publicado en GitHub. No hay marca de agua de evaluación, límite de uso ni archivo de licencia separado que gestionar, y la biblioteca puede usarse en productos comerciales sin royalties.

El paquete está actualmente en la versión 0.1.0, lo que refleja un desarrollo activo en una fase temprana. Node.js (>=22) es el único requisito de tiempo de ejecución, y el paquete no tiene otras dependencias de terceros.

Primeros pasos

Recursos relacionados