Referencia de la API de Vue

Referencia completa de los componentes, los composables y las utilidades de @reelkit/vue.

Reel

Etiqueta: <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 expuesta a través del template ref:

<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

Etiqueta: <ReelIndicator>

Props

ReelIndicatorProps

Eventos

SwipeToClose

Etiqueta: <SwipeToClose>. Envuelve su slot por defecto en un contenedor que responde al tacto y que se puede deslizar para cerrar.

Props

SwipeToCloseProps

Eventos

Slots

RK_REEL_KEY y useReelContext

Una InjectionKey<ReelContextValue> que <Reel> proporciona a sus descendientes. <ReelIndicator> la usa internamente para conectarse solo. Usa useReelContext() en componentes propios que necesiten el contexto del slider.

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

const ctx = useReelContext();

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

Composables

useBodyLock

Bloquea el scroll del body del documento cuando el valor pasado es true. Usa recuento de referencias, así que varios llamadores a la vez pueden bloquear y desbloquear cada uno por su cuenta. Se desbloquea solo al desmontar.

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 gestionar la Fullscreen API, compatible con todos los navegadores. Sale de la pantalla completa automáticamente al desmontar.

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

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

useSoundState

Accede al SoundController actual desde el contexto. Debe llamarse dentro de un <SoundProvider>; fuera de él lanza un error.

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

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

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

useOverlayUrlState

OverlayUrlStateOptions

Crea un controlador de estado en la URL para un overlay, que después pasas a un <LightboxUrlOverlay> en su prop :controller.

Consulta el estado en la URL en la guía de Vue para ver la explicación paso a paso y los ejemplos.

useVueRouterUrlAdapter

Un UrlAdapter basado en Vue Router. Pásalo como opción adapter de useOverlayUrlState en una aplicación con router para que el router siga siendo la única fuente de verdad de la navegación: escribir con history.pushState a sus espaldas deja su ubicación desfasada y su siguiente navegación pierde el parámetro. Las escrituras solo tocan la query, así que la ruta, el hash y las claves repetidas como ?tag=a&tag=b se mantienen intactos. Cada cambio indica si el router hizo push en la misma página, sustituyó la entrada o se movió por el historial, así que una galería abierta desde un <router-link> se cierra volviendo atrás una vez.

Se publica en su propia subruta, así que una aplicación sin router nunca mete vue-router en su bundle. vue-router es una peer dependency opcional, de la versión 4.1 o posterior: el adaptador guarda su marca de propiedad en la opción de navegación state del router, que las versiones anteriores ignoran. Con un router más antiguo no se rompe nada; simplemente, al cerrar se limpia el parámetro en el sitio en lugar de volver atrás.

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

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

toVueRef

Convierte un Subscribable del core (cualquier Signal de @reelkit/core) en un Ref de Vue de solo lectura. Úsalo siempre que el valor de una señal del core deba provocar un re-renderizado en Vue: leer signal.value directamente en funciones de renderizado o plantillas no es reactivo por sí solo.

La suscripción se libera sola con onScopeDispose, así que hay que llamarlo dentro del setup() de Vue o de otro contexto con ámbito de efectos.

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 ? '🔇' : '🔊');
  },
});

SoundProvider

Etiqueta: <SoundProvider>. Proveedor de contexto que crea una instancia de SoundController y la pone a disposición de sus descendientes a través de RK_SOUND_KEY. Renderiza su slot por defecto de forma transparente.

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

Accesibilidad

<Reel> se renderiza como role="region" con aria-roledescription="carousel". Pasa aria-label (en TS la prop es ariaLabel) para darle a la región un nombre para los lectores de pantalla. Una región en vivo educada anuncia "Slide N of M" en cada cambio de slide. Los slides inactivos reciben el atributo inert, así que el foco y la navegación con tecnologías de apoyo se los saltan.

<ReelIndicator> se renderiza como role="tablist" con tabindex itinerante en los puntos; las flechas mueven el foco y Intro o Espacio activan el slide.

¿Vas a crear un modal propio alrededor de <Reel>? captureFocusForReturn, createFocusTrap y getFocusableElements se reexportan desde @reelkit/vue para devolver y atrapar el foco.

Exports del paquete

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

// Components
import {
  Reel,
  ReelIndicator,
  SwipeToClose,
  SoundProvider,
} 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';

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

  // 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';