Guia para Vue

Aprenda a montar sliders com @reelkit/vue.

Slider básico

O componente <Reel> embrulha o controlador do slider do core. Use o slot #item para desenhar cada slide com virtualização — só os slides visíveis são montados.

ReelIndicator

Componente opcional que mostra indicadores de progresso no estilo Instagram, sinalizando a posição atual dentro do slider. Colocado dentro de um <Reel>, ele se liga sozinho aos valores de count e active do componente pai pelo provide/inject do Vue — sem ligação manual.

API imperativa — ref de template

O componente <Reel> expõe a interface ReelExpose por um ref de template. Use ref() para guardar a referência e chamar métodos imperativos como next(), prev() e goTo().

Direção horizontal

Defina direction="horizontal" para um slider que desliza para os lados. A direção do indicador deve acompanhar.

Dimensionamento automático

A prop size é opcional. Sem ela, o <Reel> mede o próprio contêiner com ResizeObserver e acompanha o layout definido no CSS. O contêiner precisa ganhar tamanho do elemento pai (flex, grid ou dimensões explícitas no CSS).

Transições

Passe a prop transition para personalizar a animação entre os slides. O ReelKit traz cinco transições que saem no tree-shaking: slideTransition (padrão), fadeTransition, flipTransition, cubeTransition e zoomTransition.

Modo cíclico

Ligue a navegação circular sem fim com a prop loop. O slider passa do último slide ao primeiro sem emenda (e vice-versa).

Callbacks de eventos

O componente <Reel> emite vários eventos para você acompanhar o estado do slider:

Navegação

Formas de navegação já incluídas:

Estado na URL

useOverlayUrlState monta um controlador de estado na URL para o overlay e devolve o controlador inteiro; você o entrega a um <LightboxUrlOverlay> pela prop :controller. Quem manda no estado aberto é a barra de endereços, então um overlay ligado a ela se abre sozinho e o link vira a forma normal de abrir. A primeira escrita de um parâmetro ausente empilha uma entrada no histórico e cada escrita seguinte a substitui, então percorrer os itens nunca soterra o botão voltar. Guarde o controlador para ler value/position e para fechar por código com set(null), a mesma escrita de baixo nível que o overlay usa internamente ao trocar de slide.

O objeto de opções recebe param, codec e locator (os três obrigatórios), mais um adapter opcional. O codec e o locator formam um par combinado que divide o mesmo Id, então em uma galeria simples com ?photo=3 espalhe ...urlIndexKey(() => props.images.length), que devolve as duas metades de uma vez. urlIndexKey liga o parâmetro a um índice de slide e o limita pela contagem atual que o getter devolve, então um ?photo=99 velho ou fora do intervalo é rejeitado e se cura sozinho saindo da URL, em vez de abrir um slide que ninguém nomeou. Passe um getter, e não um número: o setup do Vue roda uma única vez, então um comprimento capturado envelheceria conforme o feed paginado cresce. Por baixo, ele embrulha createIndexLocator (a metade do locator) e a combina com indexCodec. Um feed paginado ou uma galeria endereçada por identidade fornece o próprio par codec + locator. A tabela completa de opções está na referência da API para Vue.

Padrão do slot #item

No lugar da render prop do React, o Vue usa o slot com escopo #item. É ele que viabiliza a virtualização — só os slides visíveis são montados. O escopo do slot entrega três propriedades:

Composables

@reelkit/vue traz composables para os cenários comuns de overlay:

Pontos principais

• Composition API

  Importe Reel, ReelIndicator e os composables direto no seu <script setup> — não é preciso registrar plugin nenhum

• slot com escopo #item

  O equivalente, no Vue, à prop itemBuilder do React — dá virtualização com a sintaxe de template de sempre

• Ref de template

  Use ref<ReelExpose>() para navegar de forma imperativa — sem precisar de callbacks de evento

• @after-change

  Emite (index, rangeIndex) — acompanhe o índice atual para atualizar a interface

• contexto por provide/inject

  O ReelIndicator se liga sozinho ao Reel que o envolve pelo provide/inject do Vue — sem passar props de mão em mão

Dicas de desempenho

• Deixe os templates dos slides leves

  O slot #item roda para cada slide visível (normalmente 3 por vez). Evite cálculos pesados ou estruturas muito aninhadas lá dentro.

• Carregue os dados perto da borda

  Use @after-change para perceber quando o leitor se aproxima do fim e busque o lote seguinte antes que os slides acabem — é assim que nasce um feed sem fim.

• Use refs para o estado imperativo

  Guarde a referência de ReelExpose e o índice atual em ref()s do Vue, para ter reatividade fina sem renderizações desnecessárias.

• Desligue a roda em páginas roláveis

  Defina :enable-wheel="false" quando o slider estiver dentro de um layout rolável, para não capturar a rolagem da página.