Cómo convertir documentos PDF en TypeScript

Esta guía muestra cómo convertir contenido PDF a otros formatos con Aspose.PDF FOSS para TypeScript. Page exporta una página única como SVG o una imagen raster; Document exporta todo el archivo como HTML, Markdown o DOCX, y puede validar y convertir un documento a PDF/A. Requiere Node.js 22 o posterior.

Guía paso a paso

Paso 1: Instalar el paquete

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

Verifique la instalación importando la clase Document en un nuevo archivo TypeScript — esta línea debería resolverse sin error una vez que el paquete esté instalado:

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

Paso 2: Importar las clases requeridas

Importa Document para abrir el archivo; los métodos de conversión utilizados a continuación se llaman directamente sobre las instancias devueltas de Document y Page, por lo que no se requieren importaciones adicionales:

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

Paso 3: Convertir una página a SVG o a una imagen rasterizada

Page.ToSvg() devuelve una cadena independiente de <svg>. Page.ToImage() renderiza la página a bytes rasterizados; scale es relativo a los 72 DPI nativos del PDF, por lo que scale: 2 se renderiza a 144 DPI:

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

const doc = Document.OpenFile('input.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const png = doc.Pages[0].ToImage({ scale: 2 }); // Uint8Array of PNG bytes @144 DPI

Paso 4: Convertir un documento a HTML o a Markdown

Document.ToHtml() en su modo predeterminado (semántico) reorganiza el contenido del árbol estructural en encabezados y párrafos; pasa { mode: 'fixed' } para reproducir cada página como SVG posicionado y texto colocado de forma absoluta. Document.ToMarkdown() genera Markdown GFM para todo el documento:

const semanticHtml = doc.ToHtml(); // reflowable markup, all pages
const fixedHtml = doc.ToHtml({ mode: 'fixed', fonts: 'embed' }); // positioned, fonts embedded
const markdown = doc.ToMarkdown(); // GFM Markdown, all pages

El modo semántico lee el árbol estructural creado por Document.GetStructTree() / Document.CreateStructTree() — en un documento sin etiquetar recurre a un cuerpo heurístico y la exportación pierde su estructura de encabezados.

Paso 5: Convertir un documento a DOCX

Document.ToDocx() devuelve .docx bytes con el contenido reorganizado y las imágenes empaquetadas dentro; pasa { mode: 'textbox' } para mantener la geometría fija de cada página en lugar de reorganizarla:

const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' }); // .docx keeping each page's own geometry

Paso 6: Validar y convertir a PDF/A

Document.ValidatePdfA(level), Document.ValidatePdfX(level) y Document.ValidatePdfUa() devuelven un ValidationReport que describe si el documento cumple con el estándar indicado. Document.ConvertToPdfA(level, opts) devuelve un ConversionReport que enumera los ajustes que aplicó y los problemas que quedan sin resolver. Ejecute la conversión en una copia Document.ExtractPages() cuando el documento en vivo aún deba guardarse sin convertir:

const report = doc.ValidatePdfA('2b');
console.log(report.Passed);

const copy = doc.ExtractPages(doc.Pages.map((_, i) => i + 1));
const conversion = copy.ConvertToPdfA('2b');
console.log(conversion.applied.length, conversion.unresolved.length, conversion.passed);
copy.Save();

Problemas y soluciones comunes

Document.ToHtml() pierde la estructura de encabezados. El modo semántico recorre el árbol estructural, por lo que debe ejecutarse después de una pasada de etiquetado — ya sea Document.AutoTag() o etiquetado manual mediante StructTreeRoot.Append(). ToHtml() recurre a un cuerpo heurístico cuando GetStructTree() returns null.

ConvertToPdfA() modifica el archivo que deseabas mantener sin convertir. Ejecute la conversión sobre una copia de Document.ExtractPages(), y luego guarde la copia por separado — ConvertToPdfA() modifica el documento sobre el que se invoca.

ValidatePdfA() informa fallos la primera vez que se ejecuta. Una causa frecuente es que las fuentes estándar no están incrustadas y falta /OutputIntent — comprueba report.Passed y los hallazgos individuales de la regla para ver qué condiciones no se cumplieron.

Page.ToImage() la salida parece de baja resolución. scale es relativa a 72 DPI; aumente (por ejemplo { scale: 2 } para 144 DPI) para obtener una salida de calidad de impresión.

Preguntas frecuentes

¿Cuál es la diferencia entre la exportación semántica y la fija de HTML?

El modo semántico refluye el documento desde su árbol de estructura a un marcado que se visualiza bien en un navegador a cualquier ancho. El modo fijo reproduce cada página como SVG posicionado y texto colocado absolutamente, reproduciendo el diseño original exactamente.

¿`Document.ToDocx()` preserva el diseño original de la página?

Por defecto, ToDocx() refluye el contenido. Pase { mode: 'textbox' } para mantener la geometría fija propia de cada página en su lugar.

¿Cómo puedo comprobar si un documento cumple con PDF/A antes de convertirlo?

Llame a Document.ValidatePdfA(level) (por ejemplo '2b') e inspeccione el ValidationReport devuelto — esto informa del estado actual sin modificar el documento.

¿Puedo convertir solo un subconjunto de páginas?

Sí — construye un subconjunto Document primero con Document.ExtractPages(), luego llama al método de conversión (ToHtml(), ToDocx(), ConvertToPdfA(), y así sucesivamente) en ese subconjunto.