Vue API रेफ़रेंस

@reelkit/vue के कंपोनेंट, composables और यूटिलिटी का पूरा रेफ़रेंस।

Reel

टैग: <Reel>

Props

ReelProps

इवेंट

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

template ref के ज़रिए मिलने वाला imperative API:

<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

टैग: <ReelIndicator>

Props

ReelIndicatorProps

इवेंट

SwipeToClose

टैग: <SwipeToClose> — अपने default slot को टच समझने वाले कंटेनर में लपेटता है, जिसे स्वाइप करके हटाया जा सकता है।

Props

SwipeToCloseProps

इवेंट

Slots

Observe

टैग: <Observe :signals="[…]"> — जब भी इनमें से कोई सिग्नल बदलता है, यह सिर्फ़ अपना डिफ़ॉल्ट स्लॉट दोबारा बनाता है, आसपास कुछ नहीं।

रेंडर फ़ंक्शन या टेम्पलेट में core का सिग्नल पढ़ लेने भर से उसकी सदस्यता नहीं बनती। आम जवाब toVueRef है, लेकिन वह सिग्नल को उसी कंपोनेंट से बाँध देता है जिसने उसे बुलाया, इसलिए बार-बार बदलने वाला सिग्नल पूरे कंपोनेंट को दोबारा बनवाता है। Observe उससे सँकरी सीमा है: जो हिस्सा वह मान दिखाता है उसी को लपेट दें, बाक़ी कंपोनेंट अपनी जगह बना रहता है। Stories Player इसी तरह हेडर और प्रोग्रेस बार बदलता है और दोनों स्लाइडर दोबारा नहीं बनाता।

प्रॉप्स का टाइप 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>

जब पूरा कंपोनेंट सिग्नल का पीछा करे तो toVueRef लें, और जब उसका सिर्फ़ एक हिस्सा करे तो Observe।

SoundProvider

टैग: <SoundProvider> — context provider, जो SoundController instance बनाता है और उसे RK_SOUND_KEY के ज़रिए descendants को देता है। अपना default slot बिना कुछ जोड़े रेंडर करता है।

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

RK_REEL_KEY और useReelContext

<Reel> अपने descendants को जो InjectionKey<ReelContextValue> देता है। <ReelIndicator> अपने-आप जुड़ने के लिए अंदर से इसे इस्तेमाल करता है। जिन कस्टम कंपोनेंट को स्लाइडर context चाहिए, उनमें useReelContext() इस्तेमाल करें।

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

const ctx = useReelContext();

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

Composables

useBodyLock

दी गई value true होने पर document body का स्क्रॉल lock करता है। reference गिनती इस्तेमाल करता है, इसलिए एक साथ कई कॉल करने वाले अलग-अलग lock/unlock कर सकते हैं। unmount पर अपने-आप unlock होता है।

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

सभी ब्राउज़र के सपोर्ट के साथ Fullscreen API संभालने वाला composable। unmount पर अपने-आप फ़ुलस्क्रीन से बाहर आता है।

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

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

useSoundState

context से मौजूदा SoundController तक पहुँचें। <SoundProvider> के अंदर ही कॉल करना ज़रूरी है। बाहर कॉल करने पर error फेंकता है।

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

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

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

useOverlayUrlState

OverlayUrlStateOptions

किसी overlay के लिए URL-स्टेट कंट्रोलर बनाता है, जिसे आप <LightboxUrlOverlay> को उसके :controller prop के रूप में देते हैं।

पूरी जानकारी और उदाहरणों के लिए Vue गाइड में URL स्टेट देखें।

useVueRouterUrlAdapter

Vue Router पर आधारित UrlAdapter। routing वाले ऐप में इसे useOverlayUrlState के adapter विकल्प के रूप में पास करें, ताकि नेविगेशन की सच्चाई का अकेला स्रोत router ही रहे — router के पीछे history.pushState लिखने से उसकी location पुरानी पड़ जाती है और उसका अगला नेविगेशन parameter गिरा देता है। Writes सिर्फ़ query को छूते हैं, इसलिए path, hash और ?tag=a&tag=b जैसी दोहराई गई keys बिना बदले साथ चलती हैं। हर बदलाव बताता है कि router ने उसी पेज पर push किया, replace किया या history में आगे-पीछे गया, इसलिए <router-link> से खुली गैलरी back के एक कदम से बंद होती है।

यह अपने अलग subpath से आता है, इसलिए बिना router वाला ऐप vue-router को कभी अपने बंडल में नहीं खींचता। vue-router एक वैकल्पिक peer dependency है, 4.1 या उसके बाद का: adapter अपनी पहचान की मुहर router के state नेविगेशन विकल्प से ले जाता है, जिसे पुराने रिलीज़ अनदेखा करते हैं। पुराने router पर कुछ नहीं टूटता — बंद करना बस एक कदम पीछे जाने के बजाय parameter को उसी जगह साफ़ कर देता है।

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

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

toVueRef

core के Subscribable (@reelkit/core का कोई भी Signal) को read-only Vue Ref से जोड़ता है। जब भी core signal की value से Vue को दोबारा रेंडर करवाना हो, इसे इस्तेमाल करें — render फ़ंक्शन या templates में सीधे signal.value पढ़ना अपने-आप में reactive नहीं है।

subscription onScopeDispose से अपने-आप हट जाता है, इसलिए इसे Vue के setup() या effect scope समझने वाले किसी दूसरे context के अंदर ही कॉल करें।

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

ऐसा कंपोनेंट बनाता है जो मिलने वाले आइटम पर जेनेरिक हो, जैसे ReelPlayerOverlay और StoriesOverlay हैं। Vue 3.3 टाइप पैरामीटर वाला setup फ़ंक्शन defineComponent(<T>(props: Props<T>) => …, options) स्वीकार करता है, पर वह पैरामीटर तभी बचता है जब options.props में prop के नाम हों। props ऑब्जेक्ट देने पर Vue ऑब्जेक्ट से ही prop के टाइप पढ़ लेता है, और T खो जाता है। asGenericPropKeys props ऑब्जेक्ट को बिना बदले आगे देता है, जबकि टाइप चेकर उसे नामों की सूची के रूप में देखता है: T पैरेंट के bind किए मान से निकलता है, और runtime पर default, validation और boolean casting पहले की तरह काम करते हैं।

टाइप आर्ग्युमेंट बेस आइटम वाला props टाइप है, और कंपोनेंट को Vue 3.3 या नया चाहिए। स्लॉट और events T का इस्तेमाल नहीं कर सकते: स्लॉट के स्कोप को टाइप करने के लिए टेम्पलेट में उस पर टाइप लिखें।

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) बताता है कि किसी स्लॉट का नतीजा पेज पर कुछ रखेगा या नहीं। यह उस कंपोनेंट के लिए है जो पैरेंट के स्लॉट खाली छोड़ने पर अपनी रेंडरिंग पर लौट आता है, जैसा ओवरले करते हैं। जिस स्लॉट का कंटेंट किसी false v-if के पीछे है, वह फिर भी एक comment node लौटाता है, इसलिए array की लंबाई जाँचने से वह भरा हुआ लगेगा और फ़ॉलबैक हट जाएगा। hasRenderedNodes fragments को खोलता है, comment nodes को अनदेखा करता है, और null या undefined के लिए false लौटाता है, इसलिए शाखा बनाने के लिए सही जाँच hasRenderedNodes(slots.controls?.(scope)) है।

सुलभता

<Reel> aria-roledescription="carousel" के साथ role="region" के रूप में रेंडर होता है। क्षेत्र को स्क्रीन रीडर के लिए नाम देने के लिए aria-label पास करें (TS में prop का नाम ariaLabel है)। एक polite live region हर स्लाइड बदलने पर "Slide N of M" बोलता है। निष्क्रिय स्लाइडों को inert attribute मिलता है, ताकि फ़ोकस और सहायक तकनीक का नेविगेशन उन्हें छोड़ दे।

<ReelIndicator> बिंदुओं पर roving tabindex के साथ role="tablist" के रूप में रेंडर होता है; तीर वाली कुंजियाँ फ़ोकस खिसकाती हैं और Enter या Space स्लाइड सक्रिय करता है।

<Reel> के आसपास अपना modal बना रहे हैं? फ़ोकस लौटाने और रोकने के लिए captureFocusForReturn, createFocusTrap और getFocusableElements @reelkit/vue से भी export होते हैं।

पैकेज exports

@reelkit/vue के सारे सार्वजनिक exports:

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