PDF.js para TYPO3

PDF.js incorpora o renderer PDF comprovado da Mozilla diretamente em páginas TYPO3, a solução leve quando redatores querem mostrar PDFs no navegador sem forçar download e sem a pesada engrenagem de um flipbook

Quando visitantes clicam em um PDF, o navegador ou abre em nova aba, faz download ou redireciona a um viewer externo. Nenhuma dessas variantes satisfaz redatores que querem apresentar um documento no contexto de uma página. O PDF.js resolve isso integrando como módulo JavaScript autônomo o viewer que o Firefox e o Chrome usam internamente, diretamente na página TYPO3. O resultado é uma apresentação consistente em todos os navegadores e dispositivos, sem que usuários precisem instalar plugin ou sair do documento.

Uma vantagem frequentemente ignorada: o usuário não deixa a página. Enquanto um PDF aberto em nova aba costuma significar o fim da sessão, a conexão de analytics permanece com o viewer embutido. Quem mede quanto tempo visitantes realmente olham um documento pode atribuir o tempo diretamente à página de conteúdo e ver quais documentos realmente são lidos.

Cenários típicos de uso

O caso de uso mais frequente é a incorporação de documentos individuais em páginas de conteúdo, como um whitepaper em uma página de produto, um formulário de pedido em uma página de serviço ou um programa de evento ao lado da descrição do evento. A redação faz upload do PDF no FAL e o referencia via content element, o PDF.js renderiza inline. A identidade visual da página é preservada, porque borda, sombra e controles são estilizados via template do próprio site package.

O segundo caso são centros de download, nos quais vários PDFs são apresentados com uma prévia. Em vez de ícones de arquivo cegos, os usuários veem a primeira página do documento e podem, com um clique, decidir se continuam lendo ou iniciam o download completo. Para catálogos, formulários e cartilhas informativas, essa prévia frequentemente é o fator decisivo para que um documento seja clicado.

Em terceiro: disponibilização acessível de documentos de órgãos públicos e universidades. O PDF.js expõe o text layer do PDF, de forma que leitores de tela consigam ler o conteúdo, desde que o PDF tenha sido exportado corretamente como Tagged PDF.

Arquitetura técnica

Para TYPO3 existe o PDF.js em duas variantes: como extensão TYPO3 clássica que entrega a biblioteca JavaScript e adiciona um content element no backend, ou como integração pura em site package, em que os assets do PDF.js ficam diretamente no build do próprio frontend. A variante extensão é mais confortável para redatores, porque eles conseguem configurar seleção, zoom padrão e parâmetros de prévia via backend TYPO3. A variante site package é mais limpa para desenvolvedores, porque controla a versão e integra ao processo de build existente.

Tecnicamente, o PDF.js é formado por duas partes: um parser que carrega o arquivo PDF e o decompõe em um grafo de objetos interno, e um viewer que renderiza esses objetos em um elemento canvas. As duas partes rodam totalmente no cliente. A abordagem worker garante que o parsing aconteça em uma thread separada e não bloqueie a main thread, importante para scroll fluido em documentos extensos.

A integração acontece via um bloco TypoScript e um partial Fluid que incorpora um iframe ou um container com o viewer. A URL do PDF é passada como query parameter, a configuração dos elementos de UI (botões de zoom, navegação de página, link de download) é feita via bloco de configuração do PDF.js.

Problemas frequentes e soluções

O primeiro problema é Cross Origin. Quando o PDF é carregado de outro domínio ou de um bucket S3, o navegador bloqueia o acesso por razões de segurança. A solução é ou uma configuração CORS correta no file server ou um proxy server-side via middleware TYPO3 que entrega o PDF sob o mesmo domínio.

Segundo problema: performance em documentos grandes. Um manual de 200 páginas carrega rápido, o viewer só mostra as páginas visíveis. O problema surge quando o próprio PDF não é otimizado para web e cada imagem individual foi embutida em resolução plena de impressão. Aqui só ajuda reduzir o documento fonte previamente com Ghostscript ou ferramenta comparável, antes de chegar ao FAL.

Terceiro problema: acessibilidade sem text layer. Se o PDF é um scan puro sem OCR, leitores de tela não recebem texto. O PDF.js sozinho então não ajuda, o PDF precisa passar antes por um OCR. Para órgãos públicos brasileiros, isso não é opção, mas obrigação segundo as normas brasileiras de acessibilidade digital e as diretrizes do e-MAG.

Migração e compatibilidade de versões

O PDF.js como biblioteca é mantido continuamente pela Mozilla e é basicamente independente da versão TYPO3. As cascas de extensão TYPO3 que integram o PDF.js, no entanto, frequentemente ficam para trás em relação à versão da biblioteca. Quem atualiza para TYPO3 v12 ou v13 deve verificar se a extensão usada tem versão compatível ou se a migração para integração em site package é o caminho melhor.

Na comparação direta com pdfviewhelpers (geração PDF no servidor) e rflipbook (efeito flipbook), o PDF.js é a opção com menor overhead e a maior compatibilidade entre navegadores. Para incorporações individuais de PDF, quase sempre é a escolha melhor do que uma solução flipbook pesada.

Quem integra o PDF.js por conta própria no site package deve definir uma estratégia de versão clara. A biblioteca recebe atualizações regulares de segurança, porque parsers de PDF são historicamente alvo popular de ataques. Um ritmo anual de atualização é o mínimo, para órgãos públicos e infraestruturas críticas, mais para trimestral. A integração via npm e um processo de build de frontend torna isso muito mais fácil do que a cópia clássica no diretório do projeto.

A Gosign integra o PDF.js como componente de site package ou como extensão TYPO3, conforme quanto controle redatores precisam. Em projetos existentes com viewers legados, a Gosign acompanha a migração e garante que acessibilidade e tempo de carregamento não sejam sacrificados pelo conforto.