Referência da API para Vue

Referência completa dos componentes, dos composables e dos utilitários de @reelkit/vue.

Reel

Tag: <Reel>

Props

ReelProps

Eventos

Slots

<Reel :count="items.length">
  <template #item="{ index, indexInRange, size }">
    <!-- index       : number         — absolute slide index (0 to count-1) -->
    <!-- indexInRange : number         — position in the visible window (0, 1, or 2) -->
    <!-- size         : [number,number] — [width, height] of the container -->
    <MySlide :index="index" :size="size" />
  </template>

  <!-- default slot: overlay content rendered on top of the slides -->
  <ReelIndicator />
</Reel>

ReelExpose

API imperativa exposta por um ref de template:

<script setup lang="ts">
import { ref } from 'vue';
import { Reel, type ReelExpose } from '@reelkit/vue';

const reelRef = ref<ReelExpose | null>(null);

function prev()  { reelRef.value?.prev(); }
function next()  { reelRef.value?.next(); }
function jump(i: number) { reelRef.value?.goTo(i, true); }
</script>

<template>
  <Reel ref="reelRef" :count="100">
    <template #item="{ index }">
      <div>Slide {{ index }}</div>
    </template>
  </Reel>
</template>

ReelIndicator

Tag: <ReelIndicator>

Props

ReelIndicatorProps

Eventos

SwipeToClose

Tag: <SwipeToClose> — envolve o slot padrão em um contêiner sensível ao toque, que dá para dispensar com um deslize.

Props

SwipeToCloseProps

Eventos

Slots

Observe

Tag: <Observe :signals="[…]"> — re-renderiza o seu slot padrão sempre que um dos sinais muda, e nada ao redor.

Ler um sinal do core numa função de render ou num template não inscreve você nele. A resposta de sempre é toVueRef, mas ele amarra o sinal ao componente que o chamou, então um sinal que muda com frequência re-renderiza o componente inteiro. Observe é a fronteira mais estreita: coloque-o em volta da parte que mostra o valor e o resto do componente fica parado. É assim que o player de stories repinta o cabeçalho e a barra de progresso sem redesenhar nenhum dos sliders.

O tipo das props é exportado como ObserveProps.

<script setup lang="ts">
import { Observe, createTimerController, toVueRef } from '@reelkit/vue';

const timer = createTimerController({ duration: 5000 });

// toVueRef binds the signal to THIS component: every tick re-renders all of
// it. Fine for a small component, wasteful when something heavy sits beside
// the part that changes.
const progress = toVueRef(timer.progress);
</script>

<template>
  <section>
    <!-- Only the slot below re-renders on a tick; the list keeps its DOM. -->
    <Observe :signals="[timer.progress]">
      <progress :value="timer.progress.value" max="1" />
    </Observe>

    <ExpensiveList :items="items" />

    <!-- The same value through toVueRef, for comparison. -->
    <p>{{ Math.round(progress * 100) }}%</p>
  </section>
</template>

Use toVueRef quando o componente inteiro acompanha o sinal, e Observe quando só um pedaço dele acompanha.

SoundProvider

Tag: <SoundProvider> — provedor de contexto que cria uma instância de SoundController e a entrega aos descendentes por RK_SOUND_KEY. Renderiza o slot padrão de forma transparente.

<template>
  <SoundProvider>
    <Reel :count="items.length">
      <template #item="{ index }">
        <VideoSlide :index="index" />
      </template>
      <MuteButton />
    </Reel>
  </SoundProvider>
</template>

RK_REEL_KEY e useReelContext

Uma InjectionKey<ReelContextValue> que o <Reel> fornece aos seus descendentes. Usada internamente pelo <ReelIndicator> para se ligar sozinho. Use useReelContext() em componentes seus que precisem do contexto do slider.

<script setup lang="ts">
import { useReelContext } from '@reelkit/vue';

const ctx = useReelContext();

function jump(index: number) {
  ctx?.goTo(index, true);
}
</script>

Composables

useBodyLock

Trava a rolagem do corpo do documento enquanto o valor informado for true. Usa contagem de referências, então vários chamadores simultâneos travam e destravam de forma independente. Destrava sozinho na desmontagem.

import { ref } from 'vue';
import { useBodyLock } from '@reelkit/vue';

const isOpen = ref(false);
useBodyLock(isOpen);

// Also accepts a static boolean
useBodyLock(true);

useFullscreen

UseFullscreenOptions → UseFullscreenReturn

Composable para lidar com a Fullscreen API com suporte entre navegadores. Sai da tela cheia sozinho na desmontagem.

import { ref } from 'vue';
import { useFullscreen } from '@reelkit/vue';

const containerRef = ref<HTMLElement | null>(null);
const { isFullscreen, request, exit, toggle } = useFullscreen({
  elementRef: containerRef,
});

useSoundState

Alcança o SoundController atual pelo contexto. Precisa ser chamado dentro de um <SoundProvider>. Lança erro se for chamado fora.

import { useSoundState } from '@reelkit/vue';

// Inside a SoundProvider descendant
const sound = useSoundState();

sound.muted;    // Signal<boolean>
sound.toggle(); // Toggle muted state

useOverlayUrlState

OverlayUrlStateOptions

Monta um controlador de estado na URL para o overlay, que você entrega a um <LightboxUrlOverlay> pela prop :controller.

Veja Estado na URL no guia para Vue para o passo a passo e os exemplos.

useVueRouterUrlAdapter

Um UrlAdapter apoiado no Vue Router. Passe-o na opção adapter de useOverlayUrlState em um app com rotas, para que o roteador 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 hash e chaves repetidas como ?tag=a&tag=b seguem intactos. Cada mudança informa se o roteador empilhou na mesma página, substituiu ou andou pelo histórico, de modo que uma galeria aberta por um <router-link> fecha com um único passo para trás.

Vem de um subcaminho próprio, então um app sem roteador nunca puxa vue-router para o bundle. vue-router é uma peer dependency opcional, da versão 4.1 em diante: o adaptador leva seu carimbo de propriedade pela opção de navegação state do roteador, que as versões mais antigas ignoram. Em um roteador antigo nada quebra — fechar apenas limpa o parâmetro no lugar, em vez de dar um passo para trás.

import { useVueRouterUrlAdapter } from '@reelkit/vue/vue-router-url-adapter';

const adapter = useVueRouterUrlAdapter();
const photo = useOverlayUrlState({
  param: 'photo',
  adapter,
  ...urlIndexKey(() => props.images.length),
});

toVueRef

Faz a ponte de um Subscribable do core (qualquer Signal de @reelkit/core) para um Ref somente leitura do Vue. Use sempre que o valor de um sinal do core precisar provocar uma nova renderização no Vue — ler signal.value direto em funções de renderização ou em templates não é reativo por si só.

A assinatura é descartada sozinha por onScopeDispose, então isto precisa ser chamado dentro de um setup() do Vue ou de outro contexto com escopo de efeito.

import { defineComponent, h } from 'vue';
import { toVueRef, useSoundState } from '@reelkit/vue';

export const MuteIcon = defineComponent({
  setup() {
    const sound = useSoundState();
    const muted = toVueRef(sound.muted); // Readonly<Ref<boolean>>

    return () => h('span', muted.value ? '🔇' : '🔊');
  },
});

asGenericPropKeys

Cria um componente genérico em relação aos itens que recebe, como ReelPlayerOverlay e StoriesOverlay. O Vue 3.3 aceita uma função setup com parâmetro de tipo, defineComponent(<T>(props: Props<T>) => …, options), mas só mantém esse parâmetro quando options.props lista nomes de props. Passe um objeto de props e o Vue lê os tipos das props de volta a partir do objeto, então T se perde. asGenericPropKeys repassa o objeto de props intacto enquanto o verificador de tipos vê uma lista de nomes: T é inferido do que o componente pai vincula, e os valores padrão, a validação e a conversão de booleanos continuam valendo em tempo de execução.

O argumento de tipo é o tipo das props com o item base, e o componente precisa do Vue 3.3 ou mais recente. Slots e eventos não podem usar T: para tipar o escopo de um slot, anote-o no template.

import { defineComponent, h, type PropType } from 'vue';
import { asGenericPropKeys } from '@reelkit/vue';

interface Item {
  id: string;
}

interface FeedProps<T extends Item> {
  items: T[];
  loop?: boolean;
}

const feedProps = {
  items: { type: Array as PropType<Item[]>, required: true as const },
  loop: { type: Boolean, default: false },
};

export const Feed = defineComponent(
  <T extends Item = Item>(props: FeedProps<T>) =>
    () =>
      h('ul', props.items.map((item) => h('li', item.id))),
  { name: 'Feed', props: asGenericPropKeys<FeedProps<Item>>(feedProps) },
);

hasRenderedNodes

hasRenderedNodes(nodes) diz se o resultado de um slot vai colocar algo na página, para um componente que volta à própria renderização quando o pai deixa um slot vazio, como fazem os overlays. Um slot cujo conteúdo está atrás de um v-if falso ainda devolve um nó de comentário, então checar o tamanho do array o trataria como preenchido e descartaria o fallback. hasRenderedNodes desembrulha fragmentos, ignora nós de comentário e devolve false para null ou undefined, então hasRenderedNodes(slots.controls?.(scope)) é o teste em que se basear.

Acessibilidade

<Reel> é renderizado como role="region" com aria-roledescription="carousel". Passe aria-label (no TypeScript a prop é 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.

<ReelIndicator> é 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 <Reel>? captureFocusForReturn, createFocusTrap e getFocusableElements são reexportados por @reelkit/vue para devolver e prender o foco.

Exports do pacote

Todos os exports públicos de @reelkit/vue:

// Components
import {
  Reel,
  ReelIndicator,
  SwipeToClose,
  SoundProvider,
  Observe,
} from '@reelkit/vue';

// Types
import type {
  ReelExpose,
  ReelContextValue,
  SwipeToCloseDirection,
  SwipeToCloseProps,
  UseFullscreenOptions,
  UseFullscreenReturn,
} from '@reelkit/vue';

// Context & composables
import {
  RK_REEL_KEY,
  useReelContext,
  RK_SOUND_KEY,
  useBodyLock,
  useFullscreen,
  useSoundState,
  toVueRef,
} from '@reelkit/vue';

// Generic components
import { asGenericPropKeys } from '@reelkit/vue';

// Utilities (re-exported from @reelkit/core)
import {
  createDefaultKeyExtractorForLoop,
  defaultRangeExtractor,
} from '@reelkit/vue';

// Core re-exports
import {
  // Signals & reactivity
  createSignal, createComputed, reaction, batch, createDeferred,

  // Transitions
  slideTransition, fadeTransition, flipTransition,
  cubeTransition, zoomTransition, getSlideProgress,

  // Content loading & preloading
  createContentLoadingController, createContentPreloader,
  observeMediaLoading,

  // 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,

  // Gestures
  createGestureController,

  // Video
  captureFrame, createSharedVideo,

  // Animation
  animate,

  // Utilities
  noop, clamp, abs, first, last, extractRange,
  lerp, isNegative, generate,
} from '@reelkit/vue';