Referência da API para Angular
Referência completa dos componentes, das diretivas, dos serviços e dos utilitários de @reelkit/angular.
ReelComponent
Seletor: rk-reel
Inputs
| Input | Tipo | Padrão | Descrição |
|---|---|---|---|
count | number | obrigatório | Número total de slides |
direction | 'vertical' | 'horizontal' | 'vertical' | Direção do deslocamento |
size | [number, number] | undefined | undefined | Largura e altura, na forma [largura, altura]. Sem este input, o tamanho é medido pelo ResizeObserver |
initialIndex | number | 0 | Índice do slide inicial |
loop | boolean | false | Liga o ciclo infinito |
transition | TransitionTransformFn | slideTransition | Função do efeito de transição. Prontas: slideTransition, fadeTransition, flipTransition, cubeTransition, zoomTransition |
transitionDuration | number | 300 | Duração da animação em ms |
swipeDistanceFactor | number | 0.12 | Limiar do deslize (0-1) |
enableGestures | boolean | true | Liga a navegação por arrasto de toque ou mouse |
enableNavKeys | boolean | true | Liga a navegação pelas setas do teclado |
enableWheel | boolean | false | Liga a navegação pela roda do mouse |
wheelDebounceMs | number | 200 | Debounce do evento de roda, em ms |
rangeExtractor | (index: number, count: number) => number[] | defaultRangeExtractor | Função própria para decidir quais índices são renderizados |
keyExtractor | (index: number, indexInRange: number) => string | number | index => index | Função de chave própria para as expressões track do @for (útil com loop) |
className | string | '' | Classe CSS aplicada ao elemento contêiner raiz |
ariaLabel | string | 'Carousel' | Rótulo acessível da região do carrossel |
Outputs
| Output | Tipo | Descrição |
|---|---|---|
afterChange | EventEmitter<{ index: number; indexInRange: number }> | Emitido depois que a transição de slide termina |
beforeChange | EventEmitter<{ index: number; nextIndex: number; indexInRange: number }> | Emitido antes de a transição de slide começar |
slideDragStart | EventEmitter<number> | Emitido quando um gesto de arrasto começa |
slideDragEnd | EventEmitter<number> | Emitido quando um gesto de arrasto termina (dedo solto) |
slideDragCanceled | EventEmitter<number> | Emitido quando um gesto de arrasto é cancelado (o slide volta ao lugar) |
apiReady | EventEmitter<ReelApi> | Emitido uma vez, depois da inicialização da view, expondo a API imperativa |
Interface ReelApi
Obtida pelo output (apiReady):
import { type ReelApi } from '@reelkit/angular';
@Component({ ... })
export class AppComponent {
api: ReelApi | undefined;
// In template: (apiReady)="api = $event"
prev() { this.api?.prev(); }
next() { this.api?.next(); }
jump(i: number) { this.api?.goTo(i, true); } // animated
}| Método | Tipo | Descrição |
|---|---|---|
next() | () => void | Vai para o próximo slide |
prev() | () => void | Vai para o slide anterior |
goTo(index, animate?) | (number, boolean?) => Promise<void> | Navega até um índice de slide específico |
adjust() | () => void | Recalcula as posições dos slides (útil depois de uma mudança de layout) |
observe() | () => void | Começa a escutar os eventos de teclado |
unobserve() | () => void | Para de escutar os eventos de teclado |
RkReelItemDirective
Seletor: [rkReelItem] — aplicado a um ng-template dentro do rk-reel.
Contexto do template
<ng-template rkReelItem let-i let-indexInRange="indexInRange" let-size="size">
<!-- $implicit (let-i) : number — absolute slide index -->
<!-- indexInRange : number — position in the visible window (0, 1, or 2) -->
<!-- size : [number,number] — [width, height] of the container -->
</ng-template>| Variável | Tipo | Descrição |
|---|---|---|
$implicit (let-i) | number | Índice absoluto do slide (de 0 até count-1) |
indexInRange | number | Posição dentro da janela visível (0, 1 ou 2) |
size | [number, number] | Dimensões atuais do slider, na forma [largura, altura], em pixels |
ReelIndicatorComponent
Seletor: rk-reel-indicator
Inputs
| Input | Tipo | Padrão | Descrição |
|---|---|---|---|
count | number | undefined | automático | Número total de itens. Vem sozinho do contexto do rk-reel que o envolve; passe explicitamente ao usar o indicador isolado |
active | number | undefined | automático | Índice ativo no momento. Vem sozinho do contexto do rk-reel que o envolve; passe explicitamente ao usar o indicador isolado |
direction | 'vertical' | 'horizontal' | 'vertical' | Orientação do indicador |
radius | number | 3 | Raio do ponto em pixels |
visible | number | 5 | Máximo de pontos em tamanho normal visíveis ao mesmo tempo |
gap | number | 4 | Espaço entre os pontos em pixels |
activeColor | string | '#fff' | Cor do ponto ativo |
inactiveColor | string | 'rgba(255,255,255,0.5)' | Cor dos pontos inativos |
edgeScale | number | 0.5 | Fator de escala dos pontos que transbordam nas bordas |
className | string | '' | Classe CSS própria aplicada ao contêiner do indicador |
tablistLabel | string | 'Slide navigation' | Rótulo acessível do marco tablist |
Outputs
| Output | Tipo | Descrição |
|---|---|---|
dotClick | EventEmitter<number> | Emitido quando um ponto é clicado; entrega o índice do ponto |
RK_REEL_CONTEXT
Um InjectionToken<ReelContextValue> que o rk-reel fornece aos seus descendentes. Usado internamente pelo rk-reel-indicator para se ligar sozinho. Injete-o em componentes seus que precisem do contexto do slider.
import { inject } from '@angular/core';
import { RK_REEL_CONTEXT } from '@reelkit/angular';
@Component({ ... })
export class MyCustomControl {
private readonly ctx = inject(RK_REEL_CONTEXT, { optional: true });
jump(index: number) {
this.ctx?.goTo(index, true);
}
}| Propriedade | Tipo | Descrição |
|---|---|---|
index | Signal<number> | Índice reativo do slide atual |
count | Signal<number> | Contagem reativa do total de itens |
goTo | (index: number, animate?: boolean) => Promise<void> | Navega até um slide por código |
BodyLockService
Trava de rolagem do corpo com contagem de referências. Vários chamadores simultâneos (uma galeria e um modal abertos ao mesmo tempo, por exemplo) travam e destravam de forma independente — o corpo só volta ao normal quando o último deles solta. Fornecido na raiz: injete onde quiser.
import { inject } from '@angular/core';
import { BodyLockService } from '@reelkit/angular';
@Component({ ... })
export class OverlayComponent {
private readonly bodyLock = inject(BodyLockService);
open() { this.bodyLock.lock(); }
close() { this.bodyLock.unlock(); }
}| Membro | Tipo | Descrição |
|---|---|---|
locked | boolean (getter) | Se o corpo está travado no momento |
lock() | () => void | Trava a rolagem do corpo e compensa a largura da barra de rolagem |
unlock() | () => void | Devolve ao corpo os estilos de rolagem originais |
SoundStateService
Estado de mudo e de indisponível para um overlay que reproduz mídia, em signals do Angular. Forneça-o no componente dono da mídia em vez da raiz, para que cada overlay guarde o próprio estado. Todo overlay Angular do reelkit usa este serviço — @reelkit/angular-reel-player reexporta a mesma classe, então um import já existente de lá continua valendo.
O lightbox é a exceção: forneça o serviço acima de <rk-lightbox-overlay>, porque o slide de vídeo é renderizado pelo seu próprio template e nunca enxergaria a instância de dentro do overlay.
import { inject } from '@angular/core';
import { SoundStateService } from '@reelkit/angular';
@Component({
// Provide it on the component that owns the media, so two overlays
// on one page never share a muted state.
providers: [SoundStateService],
// ...
})
export class OverlayComponent {
readonly soundState = inject(SoundStateService);
// Use in template:
// [muted]="soundState.muted()"
// [hidden]="soundState.disabled()"
// (click)="soundState.toggle()"
}| Membro | Tipo | Descrição |
|---|---|---|
muted() | Signal<boolean> | Se o áudio está mudo no momento. Começa mudo |
disabled() | Signal<boolean> | Verdadeiro enquanto o som não pode ser controlado, e o botão de som some. Quem define é o overlay — RkReelPlayerOverlayComponent levanta a flag enquanto o slide não tem vídeo ou está em transição |
controller | SoundController (getter) | O SoundController do core por baixo — entregue-o a syncMutedToVideo para manter um <video> em dia com o estado de mudo |
toggle() | () => void | Alterna o estado de mudo |
setDisabled() | (value: boolean) => void | Define se o som pode ser controlado agora |
reset() | () => void | Volta ao estado inicial: mudo e controlável |
Utilitários da ponte de sinais
Funções utilitárias que ligam o sistema de sinais do core (@reelkit/core) à API nativa de sinais do Angular. Usadas internamente pelo ReelComponent e disponíveis para integrações próprias.
| Função | Assinatura | Descrição |
|---|---|---|
toAngularSignal | (source: Subscribable<T>, destroyRef: DestroyRef) => Signal<T> | Liga um Subscribable do core a um Signal somente leitura do Angular |
animatedSignalBridge | (source: AnimatedValue, zone: NgZone, cdRef: ChangeDetectorRef, destroyRef: DestroyRef) => Signal<number> | Liga um valor animado do core a um Signal do Angular, atualizando por requestAnimationFrame fora da zone |
import { DestroyRef, inject } from '@angular/core';
import { toAngularSignal } from '@reelkit/angular';
import { createSliderController } from '@reelkit/core';
// Custom component using low-level signal bridge
const destroyRef = inject(DestroyRef);
const controller = createSliderController({ count: 10 }, {});
const index = toAngularSignal(controller.state.index, destroyRef);createOverlayUrlState
OverlayUrlStateOptions
Monta um controlador de estado na URL para o overlay, que você entrega ao <rk-lightbox-url-overlay> pelo input [controller]. 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. Passo a passo: Estado na URL na página do Lightbox para Angular.
| Opção | Tipo | Padrão | Descrição |
|---|---|---|---|
param | string | obrigatório | Parâmetro de consulta que carrega o slide ativo, por exemplo photo. |
adapter | UrlAdapter | History API | Sistema de navegação por onde ler e escrever. Em um app com rotas, passe um adaptador ligado ao Router para que a localização dele não fique desatualizada. |
codec | UrlCodec<Id> | obrigatório | Formato do fio: texto do parâmetro até uma identidade estável. Anda junto do locator como par combinado — espalhe ...urlIndexKey(() => images().length) para a galeria padrão em ?photo=3, ou forneça o seu para que um favorito sobreviva à reordenação. |
locator | UrlLocator<Id> | obrigatório | Liga a identidade a uma posição e responde pela própria validade: locate (síncrono), locateAsync (plano B assíncrono de uma galeria paginada) e identify (nas escritas). |
createRouterUrlAdapter
@reelkit/angular/ng-router-url-adapter
Um UrlAdapter apoiado no Router do Angular. Passe-o na opção adapter de createOverlayUrlState em um app com rotas, para que o Router siga sendo a única fonte de verdade da navegação — escrever history.pushState por trás dele deixa sua localização desatualizada, e a navegação seguinte derruba o parâmetro. As escritas mexem apenas na consulta, então o caminho, o fragmento e chaves repetidas como ?tag=a&tag=b seguem intactos. Cada mudança informa se o Router empilhou na mesma página, substituiu ou andou pelo histórico, de modo que uma galeria aberta por um routerLink fecha com um único passo para trás. Chame-o em um contexto de injeção; a assinatura do router se solta pelo DestroyRef.
Vem de um subcaminho próprio, então um app sem rotas nunca puxa @angular/router para o bundle. @angular/router é uma peer dependency opcional.
import { createRouterUrlAdapter } from '@reelkit/angular/ng-router-url-adapter';
protected readonly photo = createOverlayUrlState({
param: 'photo',
adapter: createRouterUrlAdapter(),
...urlIndexKey(() => this.images().length),
});Acessibilidade
<rk-reel> é renderizado como role="region" com aria-roledescription="carousel". Defina o input ariaLabel para dar à região um nome que o leitor de tela anuncie. Uma live region educada anuncia "Slide N de M" a cada troca. Os slides inativos recebem o atributo inert, então o foco e a navegação por tecnologia assistiva passam por cima deles.
<rk-reel-indicator> é renderizado como role="tablist", com tabindex móvel nos pontos; as setas movem o foco e Enter ou Espaço ativa o slide.
Montando um modal próprio em volta de <rk-reel>? captureFocusForReturn, createFocusTrap e getFocusableElements são reexportados por @reelkit/angular para devolver e prender o foco.
Exports do pacote
Todos os exports públicos de @reelkit/angular:
// Components & directives
import {
ReelComponent,
ReelIndicatorComponent,
RkReelItemDirective,
RkSwipeToCloseDirective,
} from '@reelkit/angular';
// Types
import type {
ReelApi,
ReelContextValue,
RkReelItemContext,
CoreSignal,
Subscribable,
AnimatedValue,
RangeExtractor,
SliderDirection,
Disposer,
DisposableList,
GestureController,
SliderController,
ContentLoadingController,
ContentPreloader,
ContentPreloaderConfig,
SoundController,
BodyLock,
TransitionTransformFn,
SlideTransformStyle,
SwipeToCloseDirection,
} from '@reelkit/angular';
// Context
import { RK_REEL_CONTEXT } from '@reelkit/angular';
// Services
import { BodyLockService, SoundStateService } from '@reelkit/angular';
// Signal bridges
import { toAngularSignal, animatedSignalBridge } from '@reelkit/angular';
// Core re-exports
import {
// Signals & reactivity
createSignal, createComputed, reaction, batch,
// Transitions
slideTransition, fadeTransition, flipTransition,
cubeTransition, zoomTransition, getSlideProgress,
// Content loading & preloading
createContentLoadingController, createContentPreloader,
// Sound
createSoundController, syncMutedToVideo,
// Fullscreen
fullscreenSignal, requestFullscreen, exitFullscreen,
// DOM & cleanup
observeDomEvent, createDisposableList, createBodyLock, sharedBodyLock,
// Size detection
observeElementSize, getViewportSize, observeViewportSize,
isMobileWidth, fitAspectRatio, isTouchDevice,
// Autoplay & download
createTimerController, createSlideshowController, downloadFile,
// Focus management
captureFocusForReturn, createFocusTrap, getFocusableElements,
// Slider & gestures
createSliderController, createGestureController,
defaultRangeExtractor, createDefaultKeyExtractorForLoop,
// Video
captureFrame, createSharedVideo,
// Utilities
animate, noop, clamp, abs, first, last, extractRange,
} from '@reelkit/angular';