Núcleo API

API de núcleo

Este guia mostra como abrir, editar, montar e salvar documentos PDF com as classes Document e Page — os pontos de entrada para cada operação no Aspose.PDF FOSS para TypeScript. Document carrega, cria, monta e salva arquivos PDF completos; Page, acessado através de doc.Pages, expõe operações de texto, imagem, anotação e fluxo de conteúdo por página.

Ciclo de Vida do Documento

Document.OpenFile() abre um PDF a partir de um caminho de arquivo; Document.Open() aceita um Uint8Array em memória. As páginas podem ser inspecionadas e editadas no local, e Document.WriteTo() grava o resultado de volta — opcionalmente com compressão de xref-stream e object-stream.

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

// Open from disk (or Document.Open(uint8array) for in-memory data)
const doc = Document.OpenFile('input.pdf');

// Inspect and edit pages
const pages = doc.Pages;
console.log(pages.length);
pages[0].Rotate = 90;
doc.RemovePage(2);                 // 1-based page number
doc.Reorder([3, 1, 2]);

// Metadata
doc.SetMetadata({ title: 'Report', author: 'Jane', custom: { Dept: 'R&D' } });

// Save
doc.WriteTo('output.pdf');         // or: const bytes = doc.Save();
doc.WriteTo('small.pdf', { compressed: true }); // xref stream + object streams

Dividindo, Mesclando e Extraindo Páginas

Document.Split() retorna um Document por página. Document.ExtractPages() recebe uma lista de páginas baseada em 1, permitindo repetições, e devolve um novo Document contendo apenas essas páginas. Document.Append() e Document.InsertPage() copiam páginas entre documentos, e Document.Merge() combina vários documentos em um só.

const parts = doc.Split();                       // one Document per page
const chapter = doc.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

docA.Append(docB);                               // copy all of docB's pages onto docA
docA.InsertPage(1, docB.Pages[0]);               // copy a single page across documents

Criando um Novo Documento

Document.New() inicia um documento em branco em um PageFormat especificado. Page.AddText() posiciona texto, e Document.AddPage() acrescenta mais páginas, incluindo um formato rotacionado como PageFormat.A4.landscape().

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

Marcas d’água e números de página

Page.AddText() também suporta rotação, cor e opacidade, o que é suficiente para renderizar um número de página e uma marca d’água diagonal sem classes adicionais.

const doc = Document.OpenFile('in.pdf');
const page = doc.Pages[0];

// Page number, right-aligned near the bottom-right corner.
const w = page.Rect[2] - page.Rect[0];
page.AddText(`Page ${page.Number}`, w - 40, 20, { fontSize: 10, align: 'right' });

// Semi-transparent diagonal watermark, centered on the page.
page.AddText('DRAFT', page.Rect[2] / 2, page.Rect[3] / 2, {
  font: 'Times-Bold', fontSize: 64, color: [0.7, 0.7, 0.7], opacity: 0.4, rotate: 45, align: 'center',
});

doc.WriteTo('out.pdf');

Introspecção do fluxo de conteúdo

parseContentStream() decodifica o fluxo bruto de /Contents de uma página em uma lista de pares operador/operando, e serializeContentStream() converte a lista de operadores editada de volta em bytes.

import { parseContentStream, serializeContentStream } from '@asposefoss/pdf';

const ops = parseContentStream(doc.Pages[0].Contents);
// ops: { operator: string, operands: PdfObject[], inlineImage?: {...} }[]
for (const op of ops) {
  if (op.operator === 'Tj') console.log('text op:', op.operands);
}
const bytes = serializeContentStream(ops);       // round-trips operators + operands

Fluxo de texto em múltiplas colunas

Page.AddTextBlock() insere uma longa sequência de texto em uma região retangular e devolve qualquer texto que não coube, o qual pode ser passado para uma segunda chamada para continuar o fluxo em outra coluna.

const rest = page.AddTextBlock(longText, [72, 600, 200, 150], {
  font: 'Times-Roman', fontSize: 11, align: 'justify', valign: 'top', leading: 14,
});
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // continue into a 2nd column

Dicas e boas práticas

• Use Document.OpenFile() para caminhos de arquivo e Document.Open() para dados Uint8Array em memória.
• Os números de página passados para métodos como RemovePage() e ExtractPages() são baseados em 1, enquanto doc.Pages é um array base 0.
• Passe { compressed: true } para Document.WriteTo() para habilitar a compressão de xref-stream e object-stream na saída.
• Document.ExtractPages() aceita números de página repetidos, de modo que a mesma página de origem pode aparecer mais de uma vez no resultado.
• Leia page.Rect para calcular posições relativas à largura e altura reais da página, em vez de codificar coordenadas fixas.

Problemas Comuns

FAQ

Document.Open() aceita tanto caminhos de arquivos quanto dados em memória?

Document.OpenFile() abre a partir de um caminho de arquivo; Document.Open() aceita um Uint8Array de bytes em memória.

A numeração de páginas é baseada em 0 ou em 1?

Ambos, dependendo do API: doc.Pages é um array simples baseado em 0, mas métodos como RemovePage() e ExtractPages() utilizam numeração de páginas baseada em 1.

Posso criptografar um documento ao salvá-lo?

Sim — passe uma opção encrypt para WriteTo() / Save() com algorithm: 'aes256' | 'aes128' | 'rc4' e senhas opcionais de usuário/proprietário.

Como reduzo o tamanho do arquivo de saída?

Passe { compressed: true } para Document.WriteTo() para habilitar a compressão de xref-stream e object-stream.

Posso inspecionar os operadores brutos do fluxo de conteúdo de uma página?

Sim — parseContentStream(doc.Pages[0].Contents) devolve a lista de operadores, e serializeContentStream() converte uma lista editada de volta em bytes.

API Reference Resumo

Ver também

• Aspose.PDF — Enterprise Documentation