PhotoSwipe para TYPO3

Galerias de imagens no celular só funcionam com lightboxes otimizadas para toque

A maioria dos sites TYPO3 usa lightboxes criadas para navegadores de desktop: Fancybox, Colorbox, Magnific Popup. No smartphone e no tablet, essas soluções parecem deslocadas, porque o zoom e a navegação não respondem a gestos de toque, e sim a cliques do mouse. O PhotoSwipe é uma biblioteca JavaScript construída desde a base para telas sensíveis ao toque. A extensão TYPO3 integra o PhotoSwipe como galeria de imagens, com pinch-to-zoom, navegação por swipe e layout responsivo. Com menos de 30 KB (minificado + gzip), o PhotoSwipe é também uma das soluções de lightbox mais leves do mercado.

Para sites com grande parcela de acessos móveis, ou seja, praticamente todos hoje em dia, isso não é uma melhoria opcional, e sim um requisito funcional. O visitante espera os mesmos gestos que conhece do app de fotos nativo do seu smartphone.

Os cenários típicos incluem galerias de portfólio, fotos de produtos e acervos de mídia

O cenário mais comum são galerias de portfólio em sites de agências, escritórios de arquitetura ou fotógrafos. Um fotógrafo mostra de 20 a 40 imagens por projeto. O visitante clica numa miniatura, vê a imagem em resolução máxima, amplia com o gesto de pinça e desliza para a próxima. Deep linking significa que cada imagem tem um endereço próprio, que pode ser compartilhado ou linkado; desde o PhotoSwipe v5, porém, é preciso implementá-lo por conta própria, porque o módulo de hash embutido deixou de existir. Para SEO esses endereços não contam, pois o Google não trata fragmentos depois do sinal # como URLs próprias; na busca de imagens contam elementos <img> com texto alternativo significativo e nomes de arquivo descritivos.

Um segundo cenário são páginas de detalhe de produto em instalações TYPO3 próximas do e-commerce. Um fabricante de móveis mostra cinco ângulos de cada produto. O PhotoSwipe exibe essas fotos como galeria com zoom em alta resolução, ativado pela roda do mouse no desktop e por toque duplo nas telas sensíveis ao toque. A qualidade do zoom depende diretamente da resolução da imagem original. Recomendamos pelo menos 2000 pixels de largura para fotos de produtos que serão vistas com zoom.

Terceiro cenário: acervos de mídia e salas de imprensa. Uma universidade disponibiliza 500 fotos de eventos. O PhotoSwipe renderiza a galeria com boa performance, porque as imagens só são carregadas quando o visitante folheia até elas (lazy loading). A visão geral de miniaturas mostra 50 imagens por página sem tempo de carregamento perceptível.

A arquitetura técnica liga o PhotoSwipe à ampliação de imagens do TYPO3

A extensão não traz elemento de conteúdo próprio: ela ativa o PhotoSwipe na ampliação de imagens nativa do TYPO3. Os redatores mantêm as imagens como de costume nos elementos de conteúdo de imagem, a partir da mediateca do FAL, ativam a ampliação ao clicar e incluem legendas opcionais. Na renderização, a extensão acrescenta ao link a largura e a altura de cada imagem como atributos data; com eles, a biblioteca JavaScript do PhotoSwipe monta a galeria.

O PhotoSwipe em si não tem dependências: nada de jQuery, nada de framework. A biblioteca consiste em um arquivo CSS e um arquivo JS. A extensão TYPO3 registra os dois pela API PHP do AssetCollector no seu ext_localconf.php, ou seja, em todas as páginas, contenham ou não uma galeria. Para evitar requisições desnecessárias, inclua os arquivos com os ViewHelpers Fluid f:asset.css e f:asset.script no template da galeria; assim eles só entram em páginas com galeria.

Para imagens responsivas, a extensão suporta atributos srcset: o navegador carrega o tamanho de imagem adequado a cada viewport. O processamento de imagens do TYPO3 gera as variantes automaticamente. Em combinação com a conversão para WebP (veja a extensão webp), as galerias PhotoSwipe atingem tempos de carregamento ideais.

Os problemas frequentes envolvem conflitos com outras lightboxes e dimensões de imagem ausentes

O problema mais comum é o conflito com uma extensão de lightbox já instalada. Se Fancybox e PhotoSwipe estiverem ativos ao mesmo tempo, os dois reagem ao clique na imagem e geram overlays duplicados. A solução: desativar a extensão de lightbox antiga e remover os includes de CSS/JS dela do setup TypoScript. Um grep por “fancybox” ou “colorbox” nos arquivos TypoScript mostra se restos da biblioteca antiga ainda estão sendo carregados.

Segundo problema: dimensões de imagem ausentes. Para o zoom, o PhotoSwipe precisa conhecer as dimensões reais em pixels de cada imagem. Se a extensão não consegue lê-las nos metadados do FAL, o zoom não funciona ou salta para um tamanho errado. A solução: verificar os metadados do FAL de todas as imagens da galeria. O TYPO3 lê width e height automaticamente no upload, mas imagens importadas ou inseridas via CLI às vezes ficam com os metadados vazios.

O PhotoSwipe v5 roda no TYPO3 v12 e v13 sem atualizar os templates

A biblioteca PhotoSwipe está atualmente na versão 5. A extensão TYPO3 foi adaptada a diferentes versões do TYPO3 e roda de forma estável no v12. Para o TYPO3 v13, não é preciso atualizar templates, porque a versão 2.0.10 da extensão suporta igualmente o v12.4 e o v13. Nos upgrades de TYPO3, a Gosign atualiza todas as extensões de frontend, inclusive a lightbox, e verifica se os gestos de toque funcionam corretamente nas versões atuais de iOS e Android.