Guia para Angular

Aprenda a montar sliders com @reelkit/angular.

Componente rk-reel

O componente rk-reel embrulha o controlador do slider do core. É standalone e usa ChangeDetectionStrategy.OnPush.

Dimensionamento automático

O input size é opcional. Sem ele, o rk-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).

Padrão de template rkReelItem

No lugar da render prop do React, o Angular usa a diretiva estrutural rkReelItem em um ng-template. É ela que viabiliza a virtualização — só os slides visíveis são instanciados. O contexto do template entrega três variáveis:

Navegação

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

Estado na URL

createOverlayUrlState monta um controlador de estado na URL para o overlay e devolve o controlador inteiro; você o entrega a um componente *UrlOverlay pelo input [controller]. Chame-o em um contexto de injeção — na inicialização de um campo; ele se liga na hora e se solta pelo DestroyRef. Quem manda no estado aberto é a URL, 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 conduzi-lo por código: set(position) abre, set(null) fecha, e set é exatamente a mesma escrita de baixo nível que o overlay usa internamente ao trocar de slide.

App com rotas — passe um adaptador ligado ao Router, senão a localização dele fica desatualizada e a navegação seguinte derruba o parâmetro:

O objeto de opções recebe param, codec e locator (os três obrigatórios), mais um adapter opcional. codec e locator formam um par combinado que divide o mesmo Id, então uma galeria simples com ?photo=3 espalha ...urlIndexKey(() => images().length), que devolve as duas metades de uma vez. urlIndexKey limita o índice pela contagem atual que o getter devolve, então um ?photo=99 velho é rejeitado e se cura sozinho saindo da URL, em vez de abrir um slide que ninguém nomeou. 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 Angular.

ReelIndicator

Componente opcional que mostra indicadores de progresso no estilo Instagram, sinalizando a posição atual dentro do slider. Colocado dentro de um rk-reel, ele se liga sozinho aos valores de count e active do componente pai pelo token de injeção RK_REEL_CONTEXT — sem ligação manual.

Output apiReady — padrão baseado em sinais

O output (apiReady) dispara uma única vez, depois de o componente ser montado e medido. Ele emite um objeto ReelApi que você guarda e usa para navegar de forma imperativa. Guardar essa referência em um sinal do Angular combina bem com a detecção de mudanças OnPush.

Pontos principais

• Componente standalone

  Importe ReelComponent, RkReelItemDirective e, se quiser, ReelIndicatorComponent direto no array imports do seu componente

• ng-template + rkReelItem

  O equivalente, no Angular, à prop itemBuilder do React — é o que viabiliza a virtualização

• apiReady

  Output que dispara uma vez com a API imperativa de navegação — sem precisar consultar ViewChild

• afterChange

  Emite { index, indexInRange } — acompanhe o índice atual para atualizar a interface

• OnPush por padrão

  Todos os componentes usam ChangeDetectionStrategy.OnPush e sinais do Angular, para tirar o máximo de desempenho

Dicas de desempenho

• Deixe os templates dos slides leves

  O template rkReelItem 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 (afterChange) 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 sinais para o estado imperativo

  Guarde a referência de ReelApi e o índice atual em sinais do Angular, para ter reatividade fina sem provocar a re-renderização do componente inteiro.

• Desligue a roda em páginas roláveis

  Defina [enableWheel]="false" quando o slider estiver dentro de um layout rolável, para não capturar a rolagem da página.