react-native-reanimated-carousel 2.1.2 → 2.2.4

package/src/hooks/useCarouselController.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import type Animated from 'react-native-reanimated';
 import { Easing } from '../constants';
 import { runOnJS, useSharedValue, withTiming } from 'react-native-reanimated';
+import type { TCarouselActionOptions } from '../types';
 
 interface IOpts {
     loop: boolean;
@@ -22,14 +23,15 @@ export interface ICarouselController {
     index: Animated.SharedValue<number>;
     sharedIndex: React.MutableRefObject<number>;
     sharedPreIndex: React.MutableRefObject<number>;
-    prev: () => void;
-    next: () => void;
+    prev: (opts?: TCarouselActionOptions) => void;
+    next: (opts?: TCarouselActionOptions) => void;
     computedIndex: () => void;
     getCurrentIndex: () => number;
     to: (index: number, animated?: boolean) => void;
+    scrollTo: (opts?: TCarouselActionOptions) => void;
 }
 
-export function useCarouselController(opts: IOpts): ICarouselController {
+export function useCarouselController(options: IOpts): ICarouselController {
     const {
         size,
         loop,
@@ -39,13 +41,26 @@ export function useCarouselController(opts: IOpts): ICarouselController {
         length,
         onChange,
         duration,
-    } = opts;
+    } = options;
 
     const index = useSharedValue<number>(0);
     // The Index displayed to the user
     const sharedIndex = React.useRef<number>(0);
     const sharedPreIndex = React.useRef<number>(0);
 
+    const currentFixedPage = React.useCallback(() => {
+        if (loop) {
+            return -Math.round(handlerOffsetX.value / size);
+        }
+
+        const fixed = (handlerOffsetX.value / size) % length;
+        return Math.round(
+            handlerOffsetX.value <= 0
+                ? Math.abs(fixed)
+                : Math.abs(fixed > 0 ? length - fixed : 0)
+        );
+    }, [handlerOffsetX, length, size, loop]);
+
     const convertToSharedIndex = React.useCallback(
         (i: number) => {
             if (loop) {
@@ -92,22 +107,22 @@ export function useCarouselController(opts: IOpts): ICarouselController {
     }, [disable]);
 
     const onScrollEnd = React.useCallback(() => {
-        opts.onScrollEnd?.();
-    }, [opts]);
+        options.onScrollEnd?.();
+    }, [options]);
 
     const onScrollBegin = React.useCallback(() => {
-        opts.onScrollBegin?.();
-    }, [opts]);
+        options.onScrollBegin?.();
+    }, [options]);
 
     const scrollWithTiming = React.useCallback(
-        (toValue: number, callback?: () => void) => {
+        (toValue: number, onFinished?: () => void) => {
             return withTiming(
                 toValue,
                 { duration, easing: Easing.easeOutQuart },
                 (isFinished: boolean) => {
-                    callback?.();
                     if (isFinished) {
                         runOnJS(onScrollEnd)();
+                        onFinished && runOnJS(onFinished)();
                     }
                 }
             );
@@ -115,42 +130,70 @@ export function useCarouselController(opts: IOpts): ICarouselController {
         [onScrollEnd, duration]
     );
 
-    const next = React.useCallback(() => {
-        if (!canSliding() || (!loop && index.value === length - 1)) return;
+    const next = React.useCallback(
+        (opts: TCarouselActionOptions = {}) => {
+            const { count = 1, animated = true, onFinished } = opts;
+            if (!canSliding() || (!loop && index.value >= length - 1)) return;
 
-        onScrollBegin?.();
+            onScrollBegin?.();
 
-        const currentPage = Math.round(handlerOffsetX.value / size);
+            const nextPage = currentFixedPage() + count;
+            index.value = nextPage;
 
-        handlerOffsetX.value = scrollWithTiming((currentPage - 1) * size);
-    }, [
-        canSliding,
-        loop,
-        index.value,
-        length,
-        onScrollBegin,
-        handlerOffsetX,
-        size,
-        scrollWithTiming,
-    ]);
+            if (animated) {
+                handlerOffsetX.value = scrollWithTiming(
+                    -nextPage * size,
+                    onFinished
+                );
+            } else {
+                handlerOffsetX.value = -nextPage * size;
+                onFinished?.();
+            }
+        },
+        [
+            canSliding,
+            loop,
+            index,
+            length,
+            onScrollBegin,
+            handlerOffsetX,
+            size,
+            scrollWithTiming,
+            currentFixedPage,
+        ]
+    );
 
-    const prev = React.useCallback(() => {
-        if (!canSliding() || (!loop && index.value === 0)) return;
+    const prev = React.useCallback(
+        (opts: TCarouselActionOptions = {}) => {
+            const { count = 1, animated = true, onFinished } = opts;
+            if (!canSliding() || (!loop && index.value <= 0)) return;
 
-        onScrollBegin?.();
+            onScrollBegin?.();
 
-        const currentPage = Math.round(handlerOffsetX.value / size);
+            const prevPage = currentFixedPage() - count;
+            index.value = prevPage;
 
-        handlerOffsetX.value = scrollWithTiming((currentPage + 1) * size);
-    }, [
-        canSliding,
-        loop,
-        index.value,
-        onScrollBegin,
-        handlerOffsetX,
-        size,
-        scrollWithTiming,
-    ]);
+            if (animated) {
+                handlerOffsetX.value = scrollWithTiming(
+                    -prevPage * size,
+                    onFinished
+                );
+            } else {
+                handlerOffsetX.value = -prevPage * size;
+                onFinished?.();
+            }
+        },
+        [
+            canSliding,
+            loop,
+            index,
+            onScrollBegin,
+            handlerOffsetX,
+            size,
+            scrollWithTiming,
+            currentFixedPage,
+        ]
+    );
 
     const to = React.useCallback(
         (idx: number, animated: boolean = false) => {
@@ -162,9 +205,8 @@ export function useCarouselController(opts: IOpts): ICarouselController {
             const offset = handlerOffsetX.value + (index.value - idx) * size;
 
             if (animated) {
-                handlerOffsetX.value = scrollWithTiming(offset, () => {
-                    index.value = idx;
-                });
+                index.value = idx;
+                handlerOffsetX.value = scrollWithTiming(offset);
             } else {
                 handlerOffsetX.value = offset;
                 index.value = idx;
@@ -182,10 +224,27 @@ export function useCarouselController(opts: IOpts): ICarouselController {
         ]
     );
 
+    const scrollTo = React.useCallback(
+        (opts: TCarouselActionOptions = {}) => {
+            const { count, animated = false, onFinished } = opts;
+            if (!count) {
+                return;
+            }
+            const n = Math.round(count);
+            if (n < 0) {
+                prev({ count: Math.abs(n), animated, onFinished });
+            } else {
+                next({ count: n, animated, onFinished });
+            }
+        },
+        [prev, next]
+    );
+
     return {
         next,
         prev,
         to,
+        scrollTo,
         index,
         length,
         sharedIndex,

package/src/hooks/useInitProps.ts

@@ -2,21 +2,33 @@ import React from 'react';
 import { DATA_LENGTH } from '../constants';
 import type { TCarouselProps } from '../types';
 
-export type TInitializeCarouselProps<T> = TCarouselProps<T> & {
-    defaultIndex: Required<TCarouselProps>['defaultIndex'];
-    loop: Required<TCarouselProps>['loop'];
-    width: Required<TCarouselProps>['width'];
-    height: Required<TCarouselProps>['height'];
-};
+type TGetRequiredProps<P extends keyof TCarouselProps> = Record<
+    P,
+    Required<TCarouselProps>[P]
+>;
+
+export type TInitializeCarouselProps<T> = TCarouselProps<T> &
+    TGetRequiredProps<
+        | 'defaultIndex'
+        | 'loop'
+        | 'width'
+        | 'height'
+        | 'scrollAnimationDuration'
+        | 'autoPlayInterval'
+    > & {
+        // Raw data that has not been processed
+        rawData: T[];
+    };
 
 export function useInitProps<T>(
     props: TCarouselProps<T>
 ): TInitializeCarouselProps<T> {
     const {
         defaultIndex = 0,
-        data: _data = [],
+        data: rawData = [],
         loop = true,
-        autoPlayInterval = 1000,
+        autoPlayInterval: _autoPlayInterval = 1000,
+        scrollAnimationDuration = 500,
         style = {},
         panGestureHandlerProps = {},
         pagingEnabled = true,
@@ -27,20 +39,21 @@ export function useInitProps<T>(
 
     const width = Math.round(_width || 0);
     const height = Math.round(_height || 0);
+    const autoPlayInterval = Math.max(_autoPlayInterval, 0);
 
     const data = React.useMemo<T[]>(() => {
-        if (!loop) return _data;
+        if (!loop) return rawData;
 
-        if (_data.length === DATA_LENGTH.SINGLE_ITEM) {
-            return [_data[0], _data[0], _data[0]];
+        if (rawData.length === DATA_LENGTH.SINGLE_ITEM) {
+            return [rawData[0], rawData[0], rawData[0]];
         }
 
-        if (_data.length === DATA_LENGTH.DOUBLE_ITEM) {
-            return [_data[0], _data[1], _data[0], _data[1]];
+        if (rawData.length === DATA_LENGTH.DOUBLE_ITEM) {
+            return [rawData[0], rawData[1], rawData[0], rawData[1]];
         }
 
-        return _data;
-    }, [_data, loop]);
+        return rawData;
+    }, [rawData, loop]);
 
     if (props.mode === 'vertical-stack' || props.mode === 'horizontal-stack') {
         if (!props.modeConfig) {
@@ -53,8 +66,10 @@ export function useInitProps<T>(
         ...props,
         defaultIndex,
         data,
+        rawData,
         loop,
         autoPlayInterval,
+        scrollAnimationDuration,
         style,
         panGestureHandlerProps,
         pagingEnabled,

package/src/hooks/useOnProgressChange.ts

@@ -9,31 +9,32 @@ export function useOnProgressChange(
     opts: {
         size: number;
         offsetX: Animated.SharedValue<number>;
-    } & Pick<TCarouselProps, 'data' | 'onProgressChange'>
+        rawData: TCarouselProps['data'];
+    } & Pick<TCarouselProps, 'onProgressChange'>
 ) {
-    const { offsetX, data, size, onProgressChange } = opts;
+    const { offsetX, rawData, size, onProgressChange } = opts;
     useAnimatedReaction(
         () => offsetX.value,
         (_value) => {
             let value = _value;
 
-            if (data.length === DATA_LENGTH.SINGLE_ITEM) {
+            if (rawData.length === DATA_LENGTH.SINGLE_ITEM) {
                 value = value % size;
             }
 
-            if (data.length === DATA_LENGTH.DOUBLE_ITEM) {
+            if (rawData.length === DATA_LENGTH.DOUBLE_ITEM) {
                 value = value % (size * 2);
             }
 
             let absoluteProgress = Math.abs(value / size);
 
             if (value > 0) {
-                absoluteProgress = data.length - absoluteProgress;
+                absoluteProgress = rawData.length - absoluteProgress;
             }
 
             !!onProgressChange &&
                 runOnJS(onProgressChange)(value, absoluteProgress);
         },
-        [onProgressChange, data]
+        [onProgressChange, rawData]
     );
 }

package/src/layouts/stack.ts

@@ -1,7 +1,7 @@
 import { useMemo } from 'react';
 import { Dimensions, TransformsStyle, ViewStyle } from 'react-native';
 import { Extrapolate, interpolate } from 'react-native-reanimated';
-import type { ComputedDirectionTypes, CustomConfig } from 'src/types';
+import type { ComputedDirectionTypes, CustomConfig } from '../types';
 
 const screen = Dimensions.get('window');
 

package/src/types.ts

@@ -71,6 +71,11 @@ export type TCarouselProps<T = any> = {
      * @description playback interval
      */
     autoPlayInterval?: number;
+    /**
+     * Time a scroll animation takes to finish
+     * @default 500 (ms)
+     */
+    scrollAnimationDuration?: number;
     /**
      * Carousel container style
      */
@@ -138,21 +143,29 @@ export type TCarouselProps<T = any> = {
 
 export interface ICarouselInstance {
     /**
-     * Play the last one
+     * Scroll to previous item, it takes one optional argument (count),
+     * which allows you to specify how many items to cross
      */
-    prev: () => void;
+    prev: (opts?: TCarouselActionOptions) => void;
     /**
-     * Play the next one
+     * Scroll to next item, it takes one optional argument (count),
+     * which allows you to specify how many items to cross
      */
-    next: () => void;
+    next: (opts?: TCarouselActionOptions) => void;
     /**
      * Get current item index
      */
     getCurrentIndex: () => number;
     /**
      * Go to index
+     * @deprecated use scrollTo instead
      */
     goToIndex: (index: number, animated?: boolean) => void;
+    /**
+     * Use value to scroll to a position where relative to the current position,
+     * scrollTo(-2) is equivalent to prev(2), scrollTo(2) is equivalent to next(2)
+     */
+    scrollTo: (opts?: TCarouselActionOptions) => void;
 }
 
 export interface CarouselRenderItemInfo<ItemT> {
@@ -164,3 +177,9 @@ export interface CarouselRenderItemInfo<ItemT> {
 export type CarouselRenderItem<ItemT> = (
     info: CarouselRenderItemInfo<ItemT>
 ) => React.ReactElement;
+
+export interface TCarouselActionOptions {
+    count?: number;
+    animated?: boolean;
+    onFinished?: () => void;
+}