Angular Lightbox

Galeria de imagens e vídeos em tela cheia para Angular, construída sobre @reelkit/angular-lightbox.

Ver demonstração ao vivo →

Recursos

Instalação

Uso básico

Importe os estilos e o componente standalone RkLightboxOverlayComponent no array imports do seu componente.

Slots de template

Quatro diretivas de slot de template permitem personalizar por completo a interface do overlay, sem precisar copiar o componente. Cada slot recebe um objeto de contexto fortemente tipado.

Suporte a vídeo

Para ter slides de vídeo é preciso optar por eles, pelo slot de template rkLightboxSlide e pelo RkLightboxVideoSlideComponent. Esse desenho evita embutir o player de vídeo em galerias que só precisam de imagens.

Tela cheia

Use fullscreenSignal, requestFullscreen e exitFullscreen, de @reelkit/angular, para observar ou alternar o estado de tela cheia.

Estado na URL

Ver demonstração ao vivo →

RkLightboxUrlOverlayComponent é um componente à parte cujo estado aberto vive na barra de endereços. Monte um controlador com createOverlayUrlState e entregue-o como [controller]: a galeria se abre quando o parâmetro nomeia um slide e se fecha quando ele some. Os links dão para compartilhar, e o botão voltar fecha a galeria em vez de sair da página.

Chame-o em um contexto de injeção — na inicialização de um campo ou no construtor. Ele se liga na hora e se solta pelo DestroyRef, então um componente destruído com a galeria aberta não deixa nenhuma escuta para trás. As opções completas estão na referência da API para Angular.

• Abrir empilha uma entrada no histórico. Percorrer os slides substitui essa entrada, então N passos não acrescentam nenhuma e um único passo para trás sempre sai da galeria.
• Voltar só fecha quando a galeria foi aberta de dentro do app — foi o link que empilhou a entrada. Um link compartilhado aberto direto em uma aba nova não tem histórico atrás de si, então o voltar do navegador sai do site; o botão ✕ ou o Escape removem o parâmetro ali mesmo e você continua na página.
• Um parâmetro que não nomeia slide nenhum — um favorito velho, um valor editado à mão — é retirado da URL, em vez de ficar afirmando um slide que não abre.
• Os slots de template funcionam sem mudança: o componente de URL faz ele mesmo as seis consultas de slot e repassa cada template à galeria, então rkLightboxControls e seus irmãos ficam dentro dele exatamente como ficariam dentro de rk-lightbox-overlay.
• Em uma aplicação com rotas, passe um adaptador construído sobre o Router. Escrever no histórico por trás do Router deixa a localização dele desatualizada, e a navegação seguinte derruba o parâmetro.

Em um app com rotas, passe um adaptador. Escrever no histórico por trás do Router deixa a localização dele desatualizada, e a navegação seguinte derruba o parâmetro; então construa um adaptador sobre o Router e passe-o como adapter:

Links estáveis. O índice é posicional — um ?photo=3 favoritado abre outra imagem assim que a lista muda de ordem. urlStableIdKey usa o id estável de cada item, varrendo a lista atual — uma chamada resolve o caso comum.

Passe hashCodec: base64UrlCodec para escrever o id em base64url na URL — é um disfarce reversível, não um hash criptográfico.

Quer endereçar por outro campo (um slug), ou paginar um feed infinito com locateAsync? Monte o codec (o fio) e o locator (a busca) você mesmo:

Galerias infinitas ou paginadas. locate é síncrono, então só responde pelas imagens já carregadas — um link compartilhado para a imagem 400 de um feed que carregou 20 volta vazio. locateAsync é o plano B, chamado somente quando locate falha: carregue as páginas necessárias e devolva o índice que a identidade acabou tendo. Enquanto a busca corre, a galeria fica fechada e o parâmetro é deixado em paz, então o link direto sobrevive; um null ou uma rejeição derrubam o parâmetro.

Inputs do RkLightboxUrlOverlayComponent

Aceita todos os inputs de rk-lightbox-overlay, menos isOpen, substituído por um controlador. Os outputs são os mesmos, closed e slideChange; quem fecha é a URL, então closed é um aviso, não o mecanismo.

Inputs do RkLightboxOverlayComponent

Outputs do RkLightboxOverlayComponent

Interface LightboxItem

Tipos de contexto dos slots de template

Transições

Passe qualquer TransitionTransformFn pelo input transitionFn. Importar apenas a transição que você usa deixa o bundler descartar as outras. Sem este input, vale slideTransition.

Carregamento de conteúdo e tratamento de erros

Ao usar o slot de template rkLightboxSlide, três callbacks de ciclo de vida ficam disponíveis no contexto para informar o estado de carregamento. A galeria acompanha o estado de cada slide e mostra o girador ou o ícone de erro conforme o caso. Um pré-carregador guarda em cache as URLs quebradas, então voltar a um slide que falhou pula a nova tentativa.

Callbacks de ciclo de vida

Ligando os callbacks no rkLightboxSlide

Template de carregamento próprio

Use a diretiva rkLightboxLoading para substituir o girador padrão.

Template de erro próprio

Use a diretiva rkLightboxError para substituir o ícone de erro padrão.

Classes CSS

Todas as classes CSS são simples (sem escopo), então dá para alcançá-las com seletores de especificidade maior em uma folha de estilo carregada depois de @reelkit/angular-lightbox/styles.css. Para mudar cor, tamanho e z-index, prefira as propriedades CSS documentadas na seção Temas, abaixo.

Temas

Cada cor, tamanho, z-index e transição vive em uma propriedade CSS. Sobrescreva uma ou várias em :root (ou em qualquer ancestral da galeria) para trocar o tema sem mexer no código dos componentes. Os tokens são os mesmos do lightbox do React, então as sobrescritas valem para os dois bindings.

Cole o trecho abaixo em uma folha de estilo carregada depois de @reelkit/angular-lightbox/styles.css.

Acessibilidade

A raiz do overlay é um diálogo modal (role="dialog", aria-modal="true"). Defina o input ariaLabel para mudar o que o leitor de tela anuncia; o padrão é "Image gallery". Cada slide carrega role="group", aria-roledescription="slide" e um aria-label derivado do título da imagem e da posição.

A galeria captura o foco ao abrir e o devolve ao gatilho ao fechar. Tab e Shift+Tab percorrem os elementos focáveis lá dentro; um foco que escapa (clique fora, foco por código) é trazido de volta. Implementado com captureFocusForReturn e createFocusTrap, de @reelkit/core.

Atalhos de teclado