Vue Lightbox

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

Ver demonstração ao vivo →

Recursos

Instalação

Não esqueça de importar os estilos:

Uso básico

Importe a folha de estilo e o componente LightboxOverlay, e comande a abertura e o fechamento com v-model:is-open.

Slots com escopo

Seis slots nomeados com escopo permitem personalizar por completo as superfícies do overlay. Omita o slot para manter o padrão embutido; não coloque nada dentro do slot (com v-if="false", por exemplo) para esconder aquela seção inteira.

Suporte a vídeo

Os slides de vídeo são opcionais, para que o bundle padrão fique livre de toda a fiação de áudio e vídeo. Chame useVideoSlideRenderer(items) e repasse o VideoSlideRenderer / VideoControlsRenderer devolvidos aos slots #slide e #controls do overlay. Envolva o overlay no SoundProvider devolvido, para que o botão de som embutido tenha contexto.

Tela cheia

Use useFullscreen, de @reelkit/vue, para observar ou alternar o estado de tela cheia de um elemento referenciado. O botão de tela cheia embutido da galeria usa esse mesmo composable.

Estado na URL

Ver demonstração ao vivo →

Monte um controlador com useOverlayUrlState, de @reelkit/vue, e entregue-o ao LightboxUrlOverlay como controller: a partir daí, quem manda na galeria é a barra de endereços. Ela se abre quando o parâmetro nomeia um slide e se fecha quando o parâmetro some. Os links dão para compartilhar, e o botão voltar fecha a galeria. É um componente separado do LightboxOverlay, então cada um carrega exatamente um comando do estado aberto — o modelo is-open ou o controller da URL, nunca os dois.

Voltar só fecha quando você abriu de dentro do app — o link empilhou uma entrada, então voltar desempilha até a galeria. 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 de fechar ou o Escape removem o parâmetro ali mesmo e mantêm você na galeria.

O composable recebe um objeto de opções e devolve um UrlStateController (com set, index, value). Guarde-o para o controle programático: set é a escrita de baixo nível que o overlay usa internamente (troca de slide, e set(null) para fechar). Ele também conduz o overlay por código — set(index) o abre, exatamente como navegar até o parâmetro. Ainda assim, prefira um link para abrir: o href dá para compartilhar, abre em nova aba e o botão voltar o fecha — tudo de graça, sem nenhum handler.

As opções completas de useOverlayUrlState (param, adapter, codec, locator) estão na referência da API para Vue.

O próprio LightboxUrlOverlay recebe apenas :controller (obrigatório), um emit @close e todas as props visuais e de comportamento que o LightboxOverlay repassa (items, transition-fn, os slots com escopo e assim por diante) — mas nenhum is-open.

• Abrir custa uma entrada no histórico; percorrer os slides a substitui, então cem deslizes não acrescentam nenhuma — um único passo para trás sempre sai da galeria.
• Um link compartilhado como ?photo=3 abre a galeria naquele slide. Um parâmetro que não nomeia slide nenhum é retirado da URL, em vez de afirmar um slide que não abre.

Em um app com rotas, passe um adaptador. Escrever direto no histórico deixa a localização do roteador desatualizada, e a navegação seguinte derruba o parâmetro.

Links estáveis. O índice é posicional, então um favorito 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 e o locator você mesmo: o codec escreve a identidade na URL, o locator descobre onde ela está agora.

Galerias infinitas ou paginadas. locate é síncrono, então só responde pelos itens já carregados — um link compartilhado para a imagem 400 de um feed que carregou 20 volta vazio. locateAsync é o plano B, chamado somente quando ele 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. Uma resposta que chega depois de a URL ter mudado, depois de um fechamento ou depois da desmontagem é descartada, então uma busca lenta não pode abrir um slide que ninguém pediu. O que ela devolver é palavra final — informa o índice dos dados que acabou de buscar, e a galeria o aceita como está, sem reler items, que o Vue ainda não renderizou de novo.

Referência da API

Props do LightboxOverlay

LightboxOverlayProps

Props do LightboxUrlOverlay

LightboxUrlOverlayProps

Aceita todas as props visuais e de comportamento acima, menos is-open, substituída por controller. Emite close, slide-change e api-ready, mas nenhum update:is-open. initial-index é ignorada aqui — quem escolhe o slide é a posição do controlador, então um valor passado ao lado dela seria sobrescrito a cada abertura.

Eventos do LightboxOverlay

Interface LightboxItem

Tipos de escopo dos slots

Transições

Passe qualquer TransitionTransformFn pela prop transition-fn. Importar apenas a transição que você usa deixa o bundler descartar as outras. Sem esta prop, vale slideTransition.

Carregamento de conteúdo e tratamento de erros

Quando você assume a renderização pelo slot #slide, três callbacks de ciclo de vida ficam disponíveis no escopo do slot 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 #slide

Slot de carregamento próprio

Use o slot #loading para substituir o girador padrão.

Slot de erro próprio

Use o slot #error para substituir o ícone padrão de imagem quebrada.

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/vue-lightbox/styles.css. Para mudar cor, tamanho e z-index, prefira as propriedades CSS documentadas na seção Temas, abaixo.

Temas

Sobrescreva qualquer propriedade CSS --rk-lightbox-* em :root (ou em qualquer ancestral de .rk-lightbox-overlay) para trocar o tema. Declarações direto em .rk-lightbox-overlay sombreariam os valores herdados, então mantenha as sobrescritas em um seletor ancestral.

Acessibilidade

A raiz do overlay é um diálogo modal (role="dialog", aria-modal="true"). Defina a prop aria-label 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 da posição (por exemplo, "Image 2 of 5").

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/vue.

Atalhos de teclado