Linearizando um PDF para Visualização Rápida na Web em JavaScript (React)

Você clica em um link para um PDF grande e recebe um quadro em branco. O indicador gira, alguns megabytes chegam e só então a primeira página aparece. O arquivo estava bom, a rede estava boa — o documento simplesmente foi gravado em uma ordem que obriga o visualizador a esperar pelo todo antes de conseguir desenhar qualquer coisa. É esse o problema que a linearização resolve, e é uma correção estrutural, não uma correção de tamanho: os mesmos bytes, organizados de modo que as partes necessárias para renderizar a primeira página fiquem no início.

Este artigo lineariza um PDF no navegador com o Spire.PDF for JavaScript. A biblioteca roda em WebAssembly e trabalha no documento por meio de um sistema de arquivos virtual (VFS), então um arquivo pode ser reestruturado na máquina do usuário sem ser enviado a um serviço remoto de otimização.

As instruções de configuração estão em Integrando o Spire.PDF for JavaScript em um Projeto React. O exemplo abaixo pressupõe que o pacote esteja instalado e o módulo WebAssembly tenha sido inicializado.

O que realmente significa visualização rápida na web

Um PDF é um contêiner, e seus objetos são armazenados na ordem em que foram gravados por quem o produziu. Um visualizador, por outro lado, precisa de um pequeno conjunto específico — o catálogo do documento, a árvore de páginas e os objetos que sustentam a primeira página — antes de conseguir pintar qualquer coisa. Se esses objetos estiverem perto do fim do arquivo, atrás de uma grande imagem incorporada, o visualizador não tem escolha a não ser continuar baixando até alcançá-los.

Visualização rápida na web é o nome voltado ao consumidor para um PDF linearizado: aquele cujo layout interno coloca os objetos da primeira página perto do início, de modo que um cliente compatível com requisições de intervalo de bytes via HTTP possa solicitar apenas esses bytes, renderizar a primeira página imediatamente e buscar o restante em segundo plano. O leitor vê conteúdo enquanto o download continua, em vez de encarar um quadro vazio.

A consequência prática é que dois arquivos de tamanho idêntico podem parecer completamente diferentes ao abrir. Mesmo número de páginas, mesmas imagens, mesmo texto — tempo diferente até a primeira pintura.

Como a linearização reorganiza um arquivo

A linearização reescreve o layout do arquivo sem tocar no que ele contém:

• Os objetos dos quais a primeira página depende são movidos para o começo do arquivo.
• Um dicionário de linearização é gravado perto do início para que um cliente possa descobrir o layout antes de ler o documento inteiro.
• Uma tabela de dicas registra onde ficam os objetos de cada página, o que permite a um leitor saltar para uma página arbitrária com uma requisição de intervalo de bytes.
• As informações de referência cruzada são posicionadas para poderem ser lidas cedo, em vez de no fim do arquivo.

Tudo o que um leitor realmente vê — texto, imagens, fontes, arte vetorial, links, anotações, favoritos, metadados — é mantido sem alterações. As palavras na página são as mesmas palavras nos mesmos lugares. O que mudou foi a ordem dos bytes, não o conteúdo. É por isso que um documento linearizado é impossível de identificar olhando para ele: abra o original e a saída lado a lado e eles são indistinguíveis, porque a diferença só aparece em quando as peças podem ser lidas.

Linearizando um documento no navegador

O uso espelha os outros conversores da biblioteca: entregue o arquivo de entrada ao PdfToLinearizedPdfConverter e depois chame ToLinearizedPdf para gravar o documento reestruturado.

function App() {
  const convertToLinearized = 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 converted into the VFS
    const inputFileName = 'Business_Data_Overview.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // Define the output file name
    const outputFileName = 'LinearizedDocument.pdf';

    // Construct the linearization converter from the input file and write out the linearized document
    const converter = new pdfModule.PdfToLinearizedPdfConverter({ filePath: inputFileName });
    converter.ToLinearizedPdf({ filePath: outputFileName });
    converter.Dispose();

    // 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>Linearize a PDF</h1>
      <button onClick={convertToLinearized}>
        Start Converting
      </button>
    </div>
  );
}

export default App;

ToLinearizedPdf grava um novo arquivo, então a entrada permanece no VFS e o original fica disponível para comparação. Nada na chamada depende do conteúdo do documento — um relatório, um manual e um arquivo digitalizado passam pelos mesmos dois membros.

O documento linearizado não parece diferente na página; a mudança está dentro da estrutura do arquivo

Linearizar ou comprimir

Essas duas operações são rotineiramente confundidas porque ambas são descritas como "otimizar um PDF", mas elas respondem a perguntas diferentes.

Um arquivo pode precisar de ambos, e a ordem importa. A compressão reescreve o documento, e qualquer operação que reescreva um PDF descarta o layout linearizado — então, se você quiser ambos, comprima primeiro e linearize por último, para que a estrutura linearizada seja o estado final do arquivo.

Quando a linearização vale a pena

A linearização compensa em um cenário específico: um documento grande o bastante para que o download seja perceptível, entregue via HTTP a um visualizador compatível com requisições de intervalo.

• Manuais, catálogos e relatórios longos servidos de um site. Este é o caso clássico — dezenas de megabytes, abertos a partir de um link, com leitores que querem ir direto a um capítulo.
• Leitores móveis em conexões lentas. A primeira página aparece a partir dos primeiros bytes solicitados, então o tempo de carregamento percebido cai mesmo quando o download total não cai.
• Documentos que os leitores costumam acessar pelo meio. As requisições de intervalo de bytes permitem que um cliente busque uma página posterior primeiro, o que só é possível com a tabela de dicas que um arquivo linearizado carrega.

Não vale a pena em outros casos. Um arquivo aberto do disco local não é buscado via HTTP, então não há requisição de intervalo para aproveitar. Um documento curto já é renderizado antes que a diferença pudesse ser sentida. E um fluxo de trabalho interno de impressão não faz streaming nem saltos — ele quer o documento inteiro, em ordem, de uma vez.

Confirmando que a saída está linearizada

Como as páginas visíveis são idênticas, "parece certo" não prova nada. A mudança está no arquivo, então a verificação precisa ler o arquivo.

Um PDF linearizado carrega um dicionário de linearização perto do início de seus bytes, e o marcador é texto simples, então os primeiros algumas centenas de bytes da saída bastam para confirmar. Tanto a entrada quanto a saída estão no VFS, o que torna a comparação questão de algumas leituras de arquivo:

// Read the head of the file and look for the linearization marker
const bytes = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const head = new TextDecoder('latin1').decode(bytes.slice(0, 1024));
const linearized = head.includes('/Linearized');

Isso é uma proteção útil para um pipeline: converta um documento e então confirme que o marcador está presente antes de repassar o arquivo. Se ele estiver ausente, o arquivo foi reescrito por algo posteriormente à linearização — lembre-se de que qualquer nova gravação, incluindo uma etapa de compressão, descarta o layout linearizado.

Problemas comuns

A primeira página ainda demora para aparecer. Verifique como o arquivo é entregue. A linearização só ajuda quando o cliente pode solicitar partes do arquivo — servido via HTTP com suporte a intervalos. Se o arquivo inteiro for buscado de uma vez, ou o documento for curto, a operação não pode mudar o que você está vendo.

A saída tem uma linha extra de texto. Uma compilação sem licença acrescenta Evaluation Warning : The document was created with Spire.PDF for JavaScript. ao documento, uma vez por chamada de conversão. Uma licença temporária de 30 dias remove isso junto com os limites funcionais — entre em contato com a equipe de vendas para obter uma.

O tamanho do arquivo não diminuiu. Normalmente não vai diminuir. A linearização reordena os bytes existentes; não remove nenhum. Se o tamanho é o problema, isso é uma tarefa de compressão, não de linearização.

Nada acontece no primeiro clique. O módulo WebAssembly carrega de forma assíncrona. if (!pdfModule) return; é a proteção no exemplo; em uma interface real, desabilite o controle até que o módulo esteja pronto em vez de mostrar um alerta.

Perguntas frequentes

Linearizar um PDF altera seu conteúdo ou qualidade? Não. Texto, imagens, fontes, formatação, links e metadados são mantidos exatamente; apenas a ordem interna dos bytes muda. As páginas parecem e se comportam de forma idêntica.

Linearizar é o mesmo que comprimir um PDF? Não. Comprimir remove redundância para produzir menos bytes; linearizar reorganiza os bytes que já existem para que a primeira página possa ser lida mais cedo. Uma visa o tamanho do download, a outra o tempo até a primeira renderização.

Ajuda se o arquivo for aberto do disco local? Raramente. O benefício vem do streaming via HTTP com requisições de intervalo de bytes, então um documento aberto de um caminho local não tem nada a ganhar.

Um arquivo linearizado permanecerá linearizado? Somente até que algo o reescreva. Qualquer ferramenta que grave o documento novamente — uma etapa de compressão, uma edição, uma mesclagem — descarta o layout linearizado, então a linearização deve ser a última etapa do pipeline.

Funciona em um arquivo criptografado ou protegido por senha? A criptografia é uma questão separada do layout. Descriptografe o documento primeiro e deixe o conversor trabalhar em um arquivo já legível.

Posso converter vários arquivos de uma vez? Sim. O conversor é uma operação de um arquivo por vez, então um lote é um laço — os mesmos dois membros, com um nome de saída distinto para cada entrada.

Veja também

• Como converter PDF em escala de cinza em JavaScript (React)
• Reduzindo o tamanho de arquivos PDF: imagens, fontes e fluxos de conteúdo em JavaScript (React)
• Como obter a contagem de páginas de um PDF em JavaScript (React)
• Integrando o Spire.PDF for JavaScript em um Projeto React
• Página do produto Spire.PDF for JavaScript