Introdução
O post introdutório mostra a forma básica de conversão: Document.ToHtml(), Document.ToMarkdown() e Document.ToDocx(), cada um chamado sem argumentos para obter um padrão razoável. Cada um desses métodos aceita um objeto de opções que altera o que realmente é gerado — marcação semântica versus uma cópia fiel ao pixel, um documento Word refluível versus um que reproduz o layout exato de cada página.
Este post aborda essas opções, além de uma direção de conversão que a introdução não menciona: validar um documento contra as normas PDF/A, PDF/X e PDF/UA e remediá-lo para conformidade com Document.ConvertToPdfA() e seus irmãos.
O que está incluído
HTML Export: Semântico vs Fixo
Document.ToHtml() chamado sem opções percorre a árvore de estrutura do documento e gera marcação refluível — cabeçalhos e parágrafos que são lidos naturalmente em um navegador em qualquer largura. Esse modo depende de o documento estar marcado primeiro (Document.CreateStructTree() ou uma passagem de marcação equivalente); sem uma árvore de estrutura, a exportação recai para um corpo heurístico simples em vez de marcação semântica verdadeira. Passar { mode: 'fixed', fonts: 'embed' } muda totalmente a estratégia de renderização: cada página torna-se um SVG posicionado e texto colocado absolutamente, com cada programa de fonte incorporável inserido como um base64 WOFF @font-face, de modo que a página tenha a mesma aparência sem que o leitor tenha as fontes instaladas.
// Semantic mode reflows from the structure tree, so this must run after the
// tagging pass: ToHtml falls back to a heuristic body when GetStructTree() is
// null, and the export loses its heading structure silently.
const semantic = doc.ToHtml();
const fixed = doc.ToHtml({ mode: 'fixed', fonts: 'embed' });
As duas saídas atendem a propósitos diferentes: o HTML semântico é o que você deseja para leitura ou republicação de conteúdo na web, e o HTML fixo é o que você deseja quando o layout visual exato da página precisa permanecer inalterado em um navegador.
Exportações Word e Vetoriais
Document.ToDocx() chamado sem opções produz um .docx refluído: parágrafos e imagens que um processador de texto pode reformatar e editar como um documento normal. Passar { mode: 'textbox' } em vez disso mantém a geometria própria de cada página, colocando o conteúdo em caixas de texto fixas ao invés de deixá-lo refluír — mais próximo de uma cópia visual fiel do que de um documento editável. Page.ToSvg() renderiza uma única página para uma string <svg> independente, útil quando é necessária uma cópia vetorial, independente de resolução, de uma página ao invés de uma imagem raster.
import { Document } from '@asposefoss/pdf';
const doc = Document.OpenFile('in.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' }); // .docx keeping each page's own geometry
Validando e Convertendo para PDF/A, PDF/X e PDF/UA
Document.ValidatePdfA(), Document.ValidatePdfX() e Document.ValidatePdfUa() verificam cada documento contra um subconjunto curado e verificável por máquina do padrão correspondente — PDF/A (ISO 19005) para arquivamento de longo prazo, PDF/X (ISO 15930) para produção de impressão e PDF/UA (ISO 14289-1) para acessibilidade — e retornam um ValidationReport com um sinalizador Passed resumindo o resultado. Document.ConvertToPdfA() (e o equivalente ConvertToPdfX()/ConvertToPdfUa()) tenta remediar o documento para esse nível, então revalida, retornando um ConversionReport que lista quais ações foram realmente aplicadas e quais problemas permanecem não resolvidos.
import { Document } from '@asposefoss/pdf';
const doc = Document.OpenFile('in.pdf');
const pdfa = doc.ValidatePdfA('2b');
console.log(`validate: PDF/A-2b ${pdfa.Passed ? 'passes' : 'fails'}`);
// Conversion runs against a copy: the live document is still saved
// unconverted, so ConvertToPdfA must never touch it directly.
const pages = doc.Pages;
const allPages: number[] = [];
for (let i = 1; i <= pages.length; i++) allPages.push(i);
const copy = doc.ExtractPages(allPages);
const conversion = copy.ConvertToPdfA('2b');
console.log(`pdf/a convert: ${conversion.applied.length} action(s) applied, `
+ `${conversion.unresolved.length} unresolved`);
console.log(`result: ${conversion.passed ? 'passes' : 'still fails'} PDF/A-2b`);
A conversão não garante alcançar conformidade total em uma única passagem — causas comuns de falha remanescente incluem fontes não incorporadas e a ausência de intenção de saída, ambas aparecem em conversion.unresolved.
Início Rápido
Instale o pacote, então renderize uma página para SVG e todo o documento para HTML refluído e DOCX:
git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run buildimport { Document } from '@asposefoss/pdf';
const doc = Document.OpenFile('in.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const html = doc.ToHtml(); // reflowable HTML (falls back without a structure tree)
const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
// fs.writeFileSync('page1.svg', svg);
// fs.writeFileSync('out.html', html);
// fs.writeFileSync('out.docx', docx);
Formatos suportados
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| ✓ | ✓ | ||
| Markdown | md | ✓ | ✓ |
| SVG | svg | ✓ | ✓ |
| TIFF | tiff | ✓ | ✓ |
| DOCX | docx | — | ✓ |
| HTML | html | — | ✓ |
| PNG | png | — | ✓ |
| EPUB | epub | — | ✓ |
Código aberto e licenciamento
Aspose.PDF FOSS para TypeScript é lançado sob a licença MIT, com o código-fonte publicado em GitHub. Não há marca d’água de avaliação, limite de uso ou arquivo de licença separado para gerenciar, e a biblioteca pode ser usada em produtos comerciais sem royalties.
O pacote está atualmente na versão 0.1.0, refletindo desenvolvimento ativo em estágio inicial. Node.js (>=22) é o único requisito de runtime, e o pacote não possui outras dependências de terceiros.
