Como Converter Documentos PDF em TypeScript

Este guia mostra como converter o conteúdo de PDF para outros formatos com Aspose.PDF FOSS para TypeScript. Page exporta uma única página como SVG ou uma imagem raster; Document exporta o arquivo inteiro como HTML, Markdown ou DOCX, e pode validar e converter um documento para PDF/A. Requer Node.js 22 ou posterior.

Guia Passo a Passo

Passo 1: Instalar o Pacote

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 a instalação importando a classe Document em um novo arquivo TypeScript — esta linha deve ser resolvida sem erro assim que o pacote for instalado:

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

Passo 2: Importar Classes Necessárias

Importe Document para abrir o arquivo; os métodos de conversão usados abaixo são chamados diretamente nas instâncias Document e Page retornadas, portanto não são necessárias importações adicionais:

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

Etapa 3: Converter uma página para SVG ou uma imagem raster

Page.ToSvg() devolve uma string <svg> independente. Page.ToImage() renderiza a página em bytes raster; scale é relativo ao DPI nativo de 72 do PDF, portanto scale: 2 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

Etapa 4: Converter um documento para HTML ou Markdown

Document.ToHtml() em seu modo padrão (semântico) reorganiza o conteúdo da árvore de estrutura em cabeçalhos e parágrafos; passe { mode: 'fixed' } para reproduzir cada página como SVG posicionado e texto absolutamente posicionado. Document.ToMarkdown() produz Markdown GFM para todo o 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

O modo semântico lê a árvore de estrutura construída por Document.GetStructTree() / Document.CreateStructTree() — em um documento sem marcação ele recorre a um corpo heurístico e a exportação perde sua estrutura de cabeçalhos.

Etapa 5: Converter um documento para DOCX

Document.ToDocx() devolve .docx bytes com o conteúdo reorganizado e imagens empacotadas internamente; passe { mode: 'textbox' } para manter a geometria fixa de cada página em vez de reorganizar:

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

Etapa 6: Validar e Converter para PDF/A

Document.ValidatePdfA(level), Document.ValidatePdfX(level), e Document.ValidatePdfUa() retornam um ValidationReport descrevendo se o documento cumpre o padrão nomeado. Document.ConvertToPdfA(level, opts) retorna um ConversionReport listando quais correções foram aplicadas e quais problemas permanecem não resolvidos. Execute a conversão em uma cópia Document.ExtractPages() quando o documento ativo ainda precisar ser salvo sem conversão:

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 Comuns e Correções

Document.ToHtml() perde a estrutura de títulos. O modo semântico percorre a árvore de estrutura, portanto deve ser executado após uma passagem de marcação — seja Document.AutoTag() ou marcação feita manualmente via StructTreeRoot.Append(). ToHtml() recorre a um corpo heurístico quando GetStructTree() returns null.

ConvertToPdfA() altera o arquivo que você pretendia manter sem conversão. Execute a conversão em uma cópia de Document.ExtractPages(), então salve a cópia separadamente — ConvertToPdfA() modifica o documento no qual é chamado.

ValidatePdfA() relata falhas na primeira vez que é executado. Uma causa comum são fontes padrão não incorporadas e um ausente /OutputIntent — verifique report.Passed e as descobertas individuais das regras para ver quais condições não foram atendidas.

Page.ToImage() a saída parece de baixa resolução. scale é relativo a 72 DPI; aumente-o (por exemplo { scale: 2 } para 144 DPI) para saída de qualidade de impressão.

Perguntas Frequentes

Qual é a diferença entre a exportação semântica e fixa de HTML?

O modo semântico reestrutura o documento a partir de sua árvore de estrutura em marcação que é exibida bem em um navegador em qualquer largura. O modo fixo reproduz cada página como SVG posicionado e texto absolutamente posicionado, correspondendo exatamente ao layout original.

O `Document.ToDocx()` preserva o layout original da página?

Por padrão, o ToDocx() reestrutura o conteúdo. Passe { mode: 'textbox' } para manter a geometria fixa de cada página em vez disso.

Como verifico se um documento atende ao PDF/A antes de convertê-lo?

Chame Document.ValidatePdfA(level) (por exemplo, '2b') e inspecione o ValidationReport retornado — isso relata o estado atual sem modificar o documento.

Posso converter apenas um subconjunto de páginas?

Sim — construa um subconjunto Document primeiro com Document.ExtractPages(), depois chame o método de conversão (ToHtml(), ToDocx(), ConvertToPdfA(), e assim por diante) nesse subconjunto.