Aparar Páginas PDF: Recorte Margens e Espaços em Branco com JavaScript

Os PDFs frequentemente carregam mais espaço em branco do que o necessário — documentos digitalizados com bordas espessas, desenhos de engenharia com margens generosas ou faturas em que apenas a tabela central importa. Recortar a página é a correção natural, mas fazer isso em um fluxo de trabalho baseado em navegador não é simples. Ferramentas de desktop quebram a experiência web, e enviar o arquivo para um servidor de back-end levanta preocupações de privacidade e conformidade.

É aqui que o Spire.PDF for JavaScript entra. Ele é executado em WebAssembly e opera inteiramente dentro do navegador, carregando e salvando PDFs por meio de um sistema de arquivos virtual (VFS) sem ida e volta ao servidor. Você pode definir a área visível de cada página programaticamente e permitir que o usuário baixe o resultado recortado — tudo no lado do cliente. Para instalação e configuração do projeto, consulte Integrar o Spire.PDF for JavaScript em um projeto React. Os exemplos abaixo pressupõem que o Spire.PDF está instalado e o módulo WebAssembly está inicializado.

CropBox e MediaBox: Duas Caixas de Página Explicadas

Cada página de PDF é definida por dois retângulos, e entender a diferença entre eles é essencial antes de começar a recortar.

MediaBox descreve as dimensões físicas da página — a folha de papel inteira, por assim dizer. É o limite mais externo e define o espaço de coordenadas no qual todo o conteúdo é posicionado. Uma página A4 padrão tem um MediaBox de aproximadamente 595 × 842 pontos.

CropBox define o que o visualizador realmente exibe. É uma sub-região do MediaBox, e qualquer conteúdo que fique fora do CropBox é ocultado da visualização. Por padrão, o CropBox corresponde ao MediaBox, e é por isso que normalmente você vê a página inteira. Quando você reduz o CropBox, está efetivamente dizendo ao leitor de PDF: "Mostre apenas esta parte da página."

O ponto-chave para o recorte é que o CropBox é derivado do MediaBox. Você lê as dimensões completas da página em page.MediaBox.Width e page.MediaBox.Height, depois calcula um retângulo menor — reduzido pela margem que desejar em cada lado — e o atribui a page.CropBox. As coordenadas x e y do CropBox são medidas a partir do canto superior esquerdo da página, e width e height determinam quanto da página é mantido.

Recortar Todas as Páginas com uma Margem Uniforme

O cenário mais comum é aplicar a mesma redução de margem a todas as páginas de um documento. Você itera sobre doc.Pages, lê o MediaBox de cada página e define um CropBox que é reduzido por um número fixo de pontos nos quatro lados.

O exemplo abaixo remove 60 pontos de cada borda de cada página — o suficiente para remover uma borda branca larga ou uma moldura indesejada:

function App() {
  const cropPdfPage = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check whether the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the PDF file to be cropped into the VFS
    const inputFileName = 'ToCrop.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // Create a PdfDocument object and load the PDF document
    let doc = new pdfModule.PdfDocument();
    doc.LoadFromFile(inputFileName);

    // Trim 60 points off every side
    const margin = 60;

    for (let i = 0; i < doc.Pages.Count; i++) {
      const page = doc.Pages.get_Item(i);

      // MediaBox gives the full extent of the page, from which the crop box is derived
      // (x and y are measured from the top-left corner of the page)
      const width = page.MediaBox.Width;
      const height = page.MediaBox.Height;

      page.CropBox = new pdfModule.RectangleF({
        x: margin,
        y: margin,
        width: width - margin * 2,
        height: height - margin * 2,
      });
    }

    const outputFileName = 'CropByMargins.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Crop PDF Pages</h1>
      <button onClick={cropPdfPage}>
        Crop PDF
      </button>
    </div>
  );
}

export default App;

Ambas as páginas são recortadas por uma margem de 60 pontos, de modo que a margem branca e a moldura ao redor da página são removidas:

Ajuste o valor de margin para controlar quão agressivamente a página é recortada. Um valor maior remove mais espaço em branco; um valor menor realiza um recorte mais sutil. Como a margem é aplicada uniformemente aos quatro lados, esta abordagem funciona melhor quando a borda indesejada é aproximadamente igual em todas as extremidades — o que normalmente é o caso de documentos digitalizados e desenhos exportados.

Recorte de Página Única vs Documento Inteiro

O loop da seção anterior aplica o mesmo recorte a todas as páginas. Mas CropBox é uma propriedade em nível de página — não existe uma interface de recorte para todo o documento. O loop simplesmente garante que cada página receba a mesma margem. Essa distinção importa quando suas páginas têm necessidades diferentes.

Quando recortar o documento inteiro: Use a abordagem com loop quando todas as páginas compartilham o mesmo problema — por exemplo, um lote digitalizado em que cada página tem a mesma borda do scanner, ou um conjunto de desenhos de várias páginas exportado com margens idênticas. Um único valor de margin mantém o código simples e o resultado consistente.

Quando recortar uma única página: Remova o loop e atribua o CropBox diretamente à página desejada. Isso é útil quando apenas uma página precisa ser recortada — por exemplo, uma capa com um logotipo superdimensionado, ou uma fatura em que apenas a região da tabela na página 2 deve ser visível. Você também pode aplicar valores de recorte diferentes a páginas diferentes combinando lógica por página dentro do loop.

Veja como recortar apenas a primeira página, mantendo um bloco de 400 × 500 pontos começando na posição (80, 80) a partir do canto superior esquerdo:

// Crop page 1 only: keep a 400 x 500 point block starting at (80, 80) from the top-left corner
const page = doc.Pages.get_Item(0);
page.CropBox = new pdfModule.RectangleF({ x: 80, y: 80, width: 400, height: 500 });

Os valores de x e y especificam onde a região visível começa, medidos a partir do canto superior esquerdo da página. Os valores de width e height definem o tamanho dessa região. Tudo fora desse retângulo é ocultado do visualizador.

Recorte Suave: O Que Acontece com o Conteúdo

Há um detalhe importante sobre o CropBox que é fácil de ignorar: ele realiza um recorte suave, não um recorte rígido.

Quando você define o CropBox, está alterando o limite visível da página — o retângulo que os visualizadores de PDF exibem e que as impressoras usam como área da página. Mas o conteúdo que fica fora desse limite não é removido do arquivo. Ele ainda está lá, apenas oculto. Isso tem duas consequências práticas:

1. O tamanho do arquivo não diminui. O texto, as imagens e os gráficos vetoriais recortados permanecem no fluxo de dados do PDF. Se seu objetivo é reduzir o tamanho do arquivo recortando margens, definir apenas o CropBox não alcançará isso.

2. O conteúdo recortado ainda é pesquisável. O texto fora do CropBox visível ainda pode ser encontrado por funções de pesquisa e copiado por usuários que sabem como selecionar além da área visível. Isso geralmente é aceitável para recorte de margens, mas significa que o recorte não é uma forma de censurar ou remover com segurança informações sensíveis.

Se você precisa realmente eliminar conteúdo — para censura, redução do tamanho do arquivo ou para garantir que texto oculto não possa ser recuperado —, deve reconstruir a página. A abordagem é criar um novo documento, extrair o conteúdo visível da página recortada usando page.CreateTemplate(), desenhá-lo em uma nova página no novo documento e salvar o resultado. Isso produz um recorte rígido em que o conteúdo fora dos limites não existe mais no arquivo.

Para a maioria dos casos de uso de recorte de margens e remoção de espaços em branco, no entanto, o recorte suave com CropBox é exatamente o que você deseja: é rápido, simples e produz um resultado visualmente limpo sem a sobrecarga de reconstruir o documento.

Perguntas Frequentes

Posso recortar uma única página em vez do documento inteiro?

Sim. Como CropBox é uma propriedade por página, não há um método integrado de "recortar o documento inteiro" — o loop do exemplo principal é apenas uma conveniência para aplicar a mesma margem a todas as páginas. Para recortar apenas uma página, pule o loop e atribua o CropBox diretamente a essa página:

// Crop page 1 only: keep a 400 x 500 point block starting at (80, 80) from the top-left corner
const page = doc.Pages.get_Item(0);
page.CropBox = new pdfModule.RectangleF({ x: 80, y: 80, width: 400, height: 500 });

Como desfaço um recorte?

Definir CropBox modifica a caixa da página no local, e o documento não armazena a caixa anterior. Você pode esperar que atribuir page.MediaBox de volta a page.CropBox restaurasse a visualização original, mas isso não funciona como pretendido — as coordenadas são aplicadas em relação à origem da área visível atual, então apenas as dimensões mudam enquanto a origem permanece fixa. Após um recorte de 60 pontos, reatribuir as dimensões do MediaBox ainda deixa a área visível começando em (60, 60).

A solução mais simples é recarregar o arquivo original, se você ainda o tiver. Se apenas o arquivo recortado estiver disponível, você pode deslocar a origem de volta para o canto superior esquerdo usando deslocamentos negativos e restaurar as dimensões completas da página:

// Undo when the crop offset was (offsetX, offsetY)
page.CropBox = new pdfModule.RectangleF({
  x: -offsetX,
  y: -offsetY,
  width: page.MediaBox.Width,
  height: page.MediaBox.Height,
});

O arquivo não ficou menor e o conteúdo recortado ainda é pesquisável — por quê?

Esse é o comportamento esperado. O CropBox realiza um recorte suave: ele altera apenas o limite visível da página, enquanto o conteúdo fora desse limite permanece no arquivo e ainda pode ser encontrado por pesquisa de texto ou operações de cópia. Se você precisa remover fisicamente o conteúdo do PDF, definir o CropBox não é suficiente — você precisaria reconstruir a página criando um novo documento, extraindo o conteúdo visível com page.CreateTemplate(), desenhando-o em uma nova página e salvando em um novo arquivo.

Veja Também

• Como Integrar o Spire.PDF for JavaScript em um Projeto React
• Visão Geral do Spire.PDF for JavaScript