Introdução

Todas as funcionalidades em Aspose.PDF FOSS para TypeScript são acessadas por meio de duas classes: Document e Page. Document possui a coleção de páginas e tudo que está no escopo do documento — metadados, marcadores, rótulos de página e salvar/carregar — enquanto cada Page em doc.Pages possui tudo que está no escopo daquela página: conteúdo, anotações e campos de formulário. Depois que essas duas classes são compreendidas, o restante da superfície da biblioteca — conversão, anotações, formulários, segurança — é basicamente apenas mais métodos nos mesmos dois objetos.

Este post examina mais de perto as partes dessa superfície central que o post introdutório apenas menciona de passagem: montar documentos a partir de outros documentos, criar páginas do zero, adicionar uma árvore de marcadores para navegação e marcar conteúdo para acessibilidade. Todas as quatro são chamadas de método simples — sem módulo separado para importar, sem dependência extra além do próprio pacote @asposefoss/pdf.

Estas são as operações que surgem quando um pipeline PDF vai além de “abrir um arquivo, modificá-lo, salvar”: combinar relatórios de várias fontes em um único documento, gerar páginas programaticamente em vez de iniciar a partir de um modelo, e tornar a saída navegável e acessível, em vez de apenas visualmente correta.

O que está incluído

Montagem e Reorganização de Documentos

Document.Split() divide um documento em um novo Document de página única por página, na ordem das páginas. Document.ExtractPages() copia um conjunto dado de números de página baseados em 1 para um novo Document autônomo, na ordem fornecida — a mesma página pode ser repetida. Páginas de um documento também podem ser copiadas para outro: Document.Append() copia todas as páginas de um documento de origem para o final do destino, e Document.InsertPage() copia uma única página entre documentos em uma posição específica baseada em 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');

Vários documentos também podem ser combinados em um único em uma única chamada com Document.Merge(), que cria um novo Document a partir de cópias de cada página de cada documento passado para ele, em ordem.

Criando Páginas do Zero

Document.New() cria um documento do nada: zero páginas quando um formato é omitido, ou uma página em branco do PageFormat fornecido quando um é passado. Páginas em branco adicionais vêm de Document.AddPage(), que também aceita um PageFormat (ou um Page existente para copiar o tamanho). O texto é desenhado em uma página com Page.AddText(), posicionado em um ponto (x, y) no espaço de usuário do 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 e Navegação no Documento

O contorno do documento (o painel de marcadores que a maioria dos leitores de PDF exibe ao lado da página) é lido com Document.GetOutlines() e substituído integralmente por Document.SetOutlines(), cada um trabalhando com uma árvore de valores OutlineItem. Cada OutlineItem contém um Title, um destino Dest, e opcionalmente Children para entradas aninhadas, além de dicas de exibição como Open (expandidas por padrão) e 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);

Destinos nomeados desta forma ({ name: 'intro' }) são resolvidos através da tabela de destinos nomeados do documento, que Document.GetNamedDestinations() e Document.SetNamedDestination() gerenciam diretamente quando um marcador precisa apontar para um destino que não está ligado ao conteúdo da página.

Texto Estruturado e Marcação de Acessibilidade

Document.GetStructTree() devolve a árvore de estrutura lógica do documento (ou null quando o documento não está marcado), e Document.CreateStructTree() cria uma, marcando o documento como Tagged. Uma vez que a árvore de estrutura existe, Page.GetStructuredText() devolve o texto da página como valores TextBlock — fragmentos posicionados já agrupados em linhas e blocos semelhantes a parágrafos — que são a entrada de que uma passagem de marcação manual trabalha: percorrendo os blocos, decidindo quais são cabeçalhos versus texto do corpo, e anexando os elementos correspondentes à árvore.

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

Uma árvore de estrutura marcada é sobre a qual os recursos downstream são construídos: a exportação semântica HTML refluí a partir dela em vez de recorrer a um layout heurístico simples, e Document.ValidatePdfUa() verifica o documento contra um subconjunto do padrão de acessibilidade PDF/UA que depende da presença de marcação.

Início rápido

Instale o pacote, depois abra um documento, extraia e recombine um subconjunto de suas páginas e salve o 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 suportados

FormatoExtensãoLerEscrever
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

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 tem outras dependências de terceiros.

Primeiros Passos

Recursos Relacionados