@seakoi/native-ui 1.1.0 → 1.1.2

package/src/components/base/carousel/constants.ts

@@ -0,0 +1,19 @@
+/**
+ * 轮播图动画时长（毫秒）
+ */
+export const CAROUSEL_ANIMATION_DURATION = 300;
+
+/**
+ * 橡皮筋效果阻尼系数
+ */
+export const RUBBERBAND_DAMPING = 0.35;
+
+/**
+ * 手势识别最小移动距离（像素）
+ */
+export const GESTURE_MIN_DISTANCE = 5;
+
+/**
+ * 速度投影系数（用于计算惯性滑动距离）
+ */
+export const VELOCITY_PROJECTION_FACTOR = 2000;

package/src/components/base/carousel/hooks/index.ts

@@ -0,0 +1,8 @@
+export { useCarouselAutoplay } from './use-carousel-autoplay';
+export { useCarouselIndex } from './use-carousel-index';
+export { useCarouselIndicator } from './use-carousel-indicator';
+export { useCarouselLifecycle } from './use-carousel-lifecycle';
+export { useCarouselPanResponder } from './use-carousel-pan-responder';
+export { useCarouselPosition } from './use-carousel-position';
+export { useCarouselSlides } from './use-carousel-slides';
+export { useCarouselSwipe } from './use-carousel-swipe';

package/src/components/base/carousel/hooks/use-carousel-autoplay.ts

@@ -0,0 +1,55 @@
+import { useEffect } from 'react';
+
+interface UseCarouselAutoplayParams {
+  autoplay: boolean | 'reverse';
+  autoplayInterval: number;
+  total: number;
+  dragging: boolean;
+  current: number;
+  swipeNext: () => void;
+  swipePrev: () => void;
+}
+
+/**
+ * 轮播图自动轮播 Hook
+ *
+ * 管理轮播图的自动轮播功能，根据配置自动切换到下一项或上一项。
+ * 在拖动时暂停自动轮播，拖动结束后恢复。
+ * 支持正向和反向自动轮播。
+ *
+ * @param params - Hook 参数配置
+ * @param params.autoplay - 自动轮播配置（false/true/'reverse'）
+ * @param params.autoplayInterval - 自动轮播间隔（毫秒）
+ * @param params.total - 轮播项总数
+ * @param params.dragging - 是否正在拖动
+ * @param params.current - 当前索引（用于触发重新计时）
+ * @param params.swipeNext - 切换到下一项的方法
+ * @param params.swipePrev - 切换到上一项的方法
+ */
+export const useCarouselAutoplay = (params: UseCarouselAutoplayParams) => {
+  const {
+    autoplay,
+    autoplayInterval,
+    total,
+    dragging,
+    current,
+    swipeNext,
+    swipePrev,
+  } = params;
+
+  useEffect(() => {
+    if (!autoplay) return;
+    if (total <= 1) return;
+    if (dragging) return;
+    if (autoplayInterval <= 0) return;
+
+    const timer = setTimeout(() => {
+      if (autoplay === 'reverse') swipePrev();
+      else swipeNext();
+    }, autoplayInterval);
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [autoplay, autoplayInterval, dragging, swipeNext, swipePrev, total, current]);
+};

package/src/components/base/carousel/hooks/use-carousel-index.ts

@@ -0,0 +1,160 @@
+import { useMemoizedFn } from 'ahooks';
+import { clamp } from 'lodash-es';
+import { useCallback, useRef, useState } from 'react';
+
+import { RUBBERBAND_DAMPING } from '#components/base/carousel/constants';
+
+import { getBoundaryIndexRange } from '../utils';
+
+interface UseCarouselIndexParams {
+  total: number;
+  loopEnabled: boolean;
+  clonesBefore: number;
+  slidePixels: number;
+  normalizedSlideSize: number;
+  normalizedTrackOffset: number;
+  stuckAtBoundary: boolean;
+  rubberband: boolean;
+  onIndexChange?: (index: number) => void;
+}
+
+/**
+ * 轮播图索引管理 Hook
+ *
+ * 管理轮播图的索引状态和索引转换逻辑，包括：
+ * - 当前索引状态管理
+ * - 逻辑索引与扩展索引（包含克隆项）之间的转换
+ * - 目标索引计算（处理循环边界）
+ * - 位置边界限制（橡皮筋效果）
+ * - 索引变化回调
+ *
+ * @param params - Hook 参数配置
+ * @param params.total - 轮播项总数
+ * @param params.loopEnabled - 是否启用循环播放
+ * @param params.clonesBefore - 循环播放时前置克隆节点数量
+ * @param params.slidePixels - 单个滑块的像素大小
+ * @param params.normalizedSlideSize - 归一化的滑块大小百分比
+ * @param params.normalizedTrackOffset - 归一化的轨道偏移百分比
+ * @param params.stuckAtBoundary - 是否在边界处卡住
+ * @param params.rubberband - 是否开启橡皮筋效果
+ * @param params.onIndexChange - 索引变化回调
+ *
+ * @returns Hook 返回值
+ * @returns current - 当前索引
+ * @returns updateCurrent - 更新当前索引的方法
+ * @returns extIndexRef - 扩展索引的引用
+ * @returns reportIndexRef - 已报告索引的引用
+ * @returns maybeReportIndex - 可能触发索引变化回调的方法
+ * @returns getExtIndexFromIndex - 从逻辑索引获取扩展索引
+ * @returns getIndexFromExtIndex - 从扩展索引获取逻辑索引
+ * @returns getTargetExtIndexForIndex - 获取目标扩展索引（处理循环边界）
+ * @returns getBoundedPosition - 获取边界限制后的位置（橡皮筋效果）
+ */
+export const useCarouselIndex = (params: UseCarouselIndexParams) => {
+  const {
+    total,
+    loopEnabled,
+    clonesBefore,
+    slidePixels,
+    normalizedSlideSize,
+    normalizedTrackOffset,
+    stuckAtBoundary,
+    rubberband,
+    onIndexChange,
+  } = params;
+
+  const [current, setCurrent] = useState(0);
+  const extIndexRef = useRef(0);
+  const reportIndexRef = useRef<number | null>(null);
+
+  const updateCurrent = useCallback(
+    (next: number) => {
+      const normalized = total > 0 ? clamp(next, 0, total - 1) : 0;
+      setCurrent(normalized);
+    },
+    [total],
+  );
+
+  const maybeReportIndex = useMemoizedFn((index: number) => {
+    if (!onIndexChange) return;
+    if (reportIndexRef.current === index) return;
+    reportIndexRef.current = index;
+    onIndexChange(index);
+  });
+
+  const getExtIndexFromIndex = useCallback(
+    (index: number) => {
+      if (!loopEnabled) return index;
+      return clamp(index, 0, total - 1) + clonesBefore;
+    },
+    [clonesBefore, loopEnabled, total],
+  );
+
+  const getIndexFromExtIndex = useCallback(
+    (extIndex: number) => {
+      if (!loopEnabled) return clamp(extIndex, 0, total - 1);
+      if (extIndex < clonesBefore) {
+        return (((extIndex - clonesBefore) % total) + total) % total;
+      }
+      if (extIndex >= clonesBefore + total) {
+        return (extIndex - clonesBefore - total) % total;
+      }
+      return extIndex - clonesBefore;
+    },
+    [clonesBefore, loopEnabled, total],
+  );
+
+  const getTargetExtIndexForIndex = useCallback(
+    (targetIndex: number) => {
+      if (!loopEnabled) return clamp(targetIndex, 0, total - 1);
+
+      const currentExt = extIndexRef.current;
+      const normalizedTarget = clamp(targetIndex, 0, total - 1);
+      const targetExt = normalizedTarget + clonesBefore;
+
+      if (currentExt === clonesBefore && normalizedTarget === total - 1)
+        return clonesBefore - 1;
+      if (currentExt === clonesBefore + total - 1 && normalizedTarget === 0)
+        return clonesBefore + total;
+      return targetExt;
+    },
+    [clonesBefore, loopEnabled, total],
+  );
+
+  const getBoundedPosition = useMemoizedFn((nextPosition: number) => {
+    if (loopEnabled) return nextPosition;
+    if (slidePixels <= 0) return nextPosition;
+    if (total <= 0) return 0;
+
+    const { min, max } = getBoundaryIndexRange({
+      total,
+      slideSize: normalizedSlideSize,
+      trackOffset: normalizedTrackOffset,
+      stuckAtBoundary,
+    });
+    const minPos = min * slidePixels;
+    const maxPos = max * slidePixels;
+
+    if (nextPosition < minPos) {
+      if (!rubberband) return minPos;
+      return minPos - (minPos - nextPosition) * RUBBERBAND_DAMPING;
+    }
+    if (nextPosition > maxPos) {
+      if (!rubberband) return maxPos;
+      return maxPos + (nextPosition - maxPos) * RUBBERBAND_DAMPING;
+    }
+    return nextPosition;
+  });
+
+  return {
+    current,
+    updateCurrent,
+    extIndexRef,
+    reportIndexRef,
+    maybeReportIndex,
+    getExtIndexFromIndex,
+    getIndexFromExtIndex,
+    getTargetExtIndexForIndex,
+    getBoundedPosition,
+  };
+};

package/src/components/base/carousel/hooks/use-carousel-indicator.tsx

@@ -0,0 +1,84 @@
+import { useMemoizedFn } from 'ahooks';
+import { StyleSheet, View } from 'react-native';
+
+import type { CarouselProps } from '../types';
+
+interface UseCarouselIndicatorParams {
+  indicator: CarouselProps['indicator'];
+  indicatorProps: CarouselProps['indicatorProps'];
+  total: number;
+  current: number;
+  activeColor: string;
+  inactiveColor: string;
+  styles: {
+    indicatorContainer: object;
+    indicatorDot: object;
+    indicatorDotActive: object;
+  };
+}
+
+/**
+ * 轮播图指示器渲染 Hook
+ *
+ * 负责渲染轮播图底部的指示器（小圆点），支持自定义指示器或使用默认样式。
+ * 当轮播项总数小于等于 1 时，不显示指示器。
+ *
+ * @param params - Hook 参数配置
+ * @param params.indicator - 指示器配置（false 表示不显示，函数表示自定义渲染）
+ * @param params.indicatorProps - 指示器属性配置（颜色、样式）
+ * @param params.total - 轮播项总数
+ * @param params.current - 当前激活的索引
+ * @param params.activeColor - 激活状态的指示器颜色
+ * @param params.inactiveColor - 非激活状态的指示器颜色
+ * @param params.styles - 指示器样式对象
+ *
+ * @returns Hook 返回值
+ * @returns renderIndicator - 渲染指示器的方法，返回 ReactNode 或 null
+ */
+export const useCarouselIndicator = (params: UseCarouselIndicatorParams) => {
+  const {
+    indicator,
+    indicatorProps,
+    total,
+    current,
+    activeColor,
+    inactiveColor,
+    styles,
+  } = params;
+
+  const renderIndicator = useMemoizedFn(() => {
+    if (indicator === false) return null;
+    if (total <= 1) return null;
+
+    if (typeof indicator === 'function') {
+      return indicator(total, current);
+    }
+
+    const dotActiveColor = indicatorProps?.color ?? activeColor;
+
+    return (
+      <View
+        style={StyleSheet.flatten([
+          styles.indicatorContainer,
+          indicatorProps?.style,
+        ])}
+      >
+        {Array.from({ length: total }, (_, i) => {
+          const isActive = i === current;
+          return (
+            <View
+              key={i}
+              style={StyleSheet.flatten([
+                styles.indicatorDot,
+                { backgroundColor: isActive ? dotActiveColor : inactiveColor },
+                isActive && styles.indicatorDotActive,
+              ])}
+            />
+          );
+        })}
+      </View>
+    );
+  });
+
+  return { renderIndicator };
+};

package/src/components/base/carousel/hooks/use-carousel-lifecycle.ts

@@ -0,0 +1,85 @@
+import { clamp } from 'lodash-es';
+import { type RefObject, useEffect } from 'react';
+
+interface UseCarouselLifecycleParams {
+  total: number;
+  defaultIndex: number;
+  slidePixels: number;
+  extIndexRef: RefObject<number>;
+  reportIndexRef: RefObject<number | null>;
+  getExtIndexFromIndex: (index: number) => number;
+  getBoundedPosition: (position: number) => number;
+  updateCurrent: (index: number) => void;
+  setPositionImmediate: (toValue: number) => void;
+}
+
+/**
+ * 轮播图生命周期管理 Hook
+ *
+ * 管理轮播图的初始化和响应式更新：
+ * - 初始化时设置默认索引和位置
+ * - 响应 slidePixels 变化时更新位置
+ * - 确保位置和索引状态的一致性
+ *
+ * @param params - Hook 参数配置
+ * @param params.total - 轮播项总数
+ * @param params.defaultIndex - 初始展示的索引
+ * @param params.slidePixels - 单个滑块的像素大小
+ * @param params.extIndexRef - 扩展索引的引用
+ * @param params.reportIndexRef - 已报告索引的引用
+ * @param params.getExtIndexFromIndex - 从逻辑索引获取扩展索引
+ * @param params.getBoundedPosition - 获取边界限制后的位置
+ * @param params.updateCurrent - 更新当前索引
+ * @param params.setPositionImmediate - 立即设置位置
+ */
+export const useCarouselLifecycle = (params: UseCarouselLifecycleParams) => {
+  const {
+    total,
+    defaultIndex,
+    slidePixels,
+    extIndexRef,
+    reportIndexRef,
+    getExtIndexFromIndex,
+    getBoundedPosition,
+    updateCurrent,
+    setPositionImmediate,
+  } = params;
+
+  // 初始化位置
+  useEffect(() => {
+    if (total <= 0) {
+      updateCurrent(0);
+      reportIndexRef.current = null;
+      extIndexRef.current = 0;
+      setPositionImmediate(0);
+      return;
+    }
+
+    const normalizedDefault = clamp(Math.round(defaultIndex), 0, total - 1);
+    updateCurrent(normalizedDefault);
+    reportIndexRef.current = normalizedDefault;
+
+    const extIndex = getExtIndexFromIndex(normalizedDefault);
+    extIndexRef.current = extIndex;
+    if (slidePixels > 0) {
+      setPositionImmediate(getBoundedPosition(extIndex * slidePixels));
+    }
+  }, [
+    defaultIndex,
+    getExtIndexFromIndex,
+    getBoundedPosition,
+    setPositionImmediate,
+    slidePixels,
+    total,
+    updateCurrent,
+    reportIndexRef,
+    extIndexRef,
+  ]);
+
+  // 响应 slidePixels 变化
+  useEffect(() => {
+    if (slidePixels <= 0) return;
+    const extIndex = extIndexRef.current;
+    setPositionImmediate(getBoundedPosition(extIndex * slidePixels));
+  }, [getBoundedPosition, setPositionImmediate, slidePixels, extIndexRef]);
+};

package/src/components/base/carousel/hooks/use-carousel-pan-responder.ts

@@ -0,0 +1,172 @@
+import { clamp } from 'lodash-es';
+import { type RefObject, useMemo } from 'react';
+import {
+  type Animated,
+  PanResponder,
+  type PanResponderInstance,
+} from 'react-native';
+
+import { GESTURE_MIN_DISTANCE, VELOCITY_PROJECTION_FACTOR } from '../constants';
+
+interface UseCarouselPanResponderParams {
+  allowTouchMove: boolean;
+  total: number;
+  slidePixels: number;
+  direction: 'horizontal' | 'vertical';
+  extTotal: number;
+  clonesBefore: number;
+  blockNativeResponder: boolean;
+  position: RefObject<Animated.Value>;
+  positionValueRef: RefObject<number>;
+  extIndexRef: RefObject<number>;
+  setDragging: (dragging: boolean) => void;
+  setAnimating: (animating: boolean) => void;
+  updateCurrent: (index: number) => void;
+  getIndexFromExtIndex: (extIndex: number) => number;
+  getBoundedPosition: (position: number) => number;
+  swipeToExtIndex: (extIndex: number) => void;
+}
+
+/**
+ * 轮播图手势响应 Hook
+ *
+ * 创建并管理 PanResponder，处理用户的拖动手势，实现轮播图的滑动交互。
+ * 支持水平和垂直方向的滑动，处理循环播放时的边界循环逻辑，
+ * 并根据滑动速度和距离计算最终停留位置。
+ *
+ * @param params - Hook 参数配置
+ * @param params.allowTouchMove - 是否允许手势滑动
+ * @param params.total - 轮播项总数
+ * @param params.slidePixels - 单个滑块的像素大小
+ * @param params.direction - 滑动方向（horizontal/vertical）
+ * @param params.extTotal - 扩展总数（包含克隆项）
+ * @param params.clonesBefore - 循环播放时前置克隆节点数量
+ * @param params.blockNativeResponder - 是否阻断原生手势响应
+ * @param params.position - Animated.Value 位置引用
+ * @param params.positionValueRef - 当前位置值的引用
+ * @param params.extIndexRef - 扩展索引的引用
+ * @param params.setDragging - 设置拖动状态
+ * @param params.setAnimating - 设置动画状态
+ * @param params.updateCurrent - 更新当前索引
+ * @param params.getIndexFromExtIndex - 从扩展索引获取逻辑索引
+ * @param params.getBoundedPosition - 获取边界限制后的位置
+ * @param params.swipeToExtIndex - 切换到扩展索引
+ *
+ * @returns PanResponderInstance 或 null（当不允许滑动或轮播项少于 2 个时）
+ */
+export const useCarouselPanResponder = (
+  params: UseCarouselPanResponderParams,
+): PanResponderInstance | null => {
+  const {
+    allowTouchMove,
+    total,
+    slidePixels,
+    direction,
+    extTotal,
+    clonesBefore,
+    blockNativeResponder,
+    position,
+    positionValueRef,
+    extIndexRef,
+    setDragging,
+    setAnimating,
+    updateCurrent,
+    getIndexFromExtIndex,
+    getBoundedPosition,
+    swipeToExtIndex,
+  } = params;
+
+  return useMemo(() => {
+    if (!allowTouchMove) return null;
+    if (total <= 1) return null;
+    if (slidePixels <= 0) return null;
+
+    let startPosition = 0;
+    const axis = direction === 'horizontal' ? 'x' : 'y';
+
+    const shouldSet = (_: unknown, gestureState: { dx: number; dy: number }) => {
+      const primary = axis === 'x' ? gestureState.dx : gestureState.dy;
+      return Math.abs(primary) >= GESTURE_MIN_DISTANCE;
+    };
+
+    return PanResponder.create({
+      onMoveShouldSetPanResponder: shouldSet,
+      onPanResponderGrant: () => {
+        setDragging(true);
+        setAnimating(false);
+        position.current.stopAnimation();
+        startPosition = positionValueRef.current;
+      },
+      onPanResponderMove: (_evt, gestureState) => {
+        const delta = axis === 'x' ? gestureState.dx : gestureState.dy;
+        let nextPosition = startPosition - delta;
+
+        // loop 开启时,拖动到最外层有效克隆中心之外则循环偏移,保证视口内始终有内容
+        // minPos/maxPos 是 outermost before/after clone 的中心位置,由 clonesBefore 公式保证此范围内视口始终被覆盖
+        if (extTotal > total && slidePixels > 0) {
+          const totalPixels = total * slidePixels;
+          const minPos = (clonesBefore - 1) * slidePixels;
+          const maxPos = (clonesBefore + total) * slidePixels;
+          while (nextPosition < minPos) {
+            nextPosition += totalPixels;
+            startPosition += totalPixels;
+          }
+          while (nextPosition > maxPos) {
+            nextPosition -= totalPixels;
+            startPosition -= totalPixels;
+          }
+        }
+
+        const bounded = getBoundedPosition(nextPosition);
+        position.current.setValue(bounded);
+        positionValueRef.current = bounded;
+
+        const nextExtIndex = clamp(
+          Math.round(bounded / slidePixels),
+          0,
+          extTotal - 1,
+        );
+        extIndexRef.current = nextExtIndex;
+        updateCurrent(getIndexFromExtIndex(nextExtIndex));
+      },
+      onPanResponderRelease: (_evt, gestureState) => {
+        setDragging(false);
+        const velocity = axis === 'x' ? gestureState.vx : gestureState.vy;
+        position.current.stopAnimation(value => {
+          const baseIndex = value / slidePixels;
+          const projectedIndex =
+            (value - velocity * VELOCITY_PROJECTION_FACTOR) / slidePixels;
+
+          const minAdj = Math.floor(baseIndex);
+          const maxAdj = minAdj + 1;
+          const rounded = Math.round(projectedIndex);
+          const adjacent = clamp(rounded, minAdj, maxAdj);
+          swipeToExtIndex(adjacent);
+        });
+      },
+      onPanResponderTerminate: () => {
+        setDragging(false);
+        swipeToExtIndex(extIndexRef.current);
+      },
+      onPanResponderTerminationRequest: () => false,
+      onShouldBlockNativeResponder: () => blockNativeResponder,
+    });
+  }, [
+    allowTouchMove,
+    blockNativeResponder,
+    clonesBefore,
+    direction,
+    extTotal,
+    extIndexRef,
+    getBoundedPosition,
+    getIndexFromExtIndex,
+    position,
+    positionValueRef,
+    setAnimating,
+    setDragging,
+    slidePixels,
+    swipeToExtIndex,
+    total,
+    updateCurrent,
+  ]);
+};

package/src/components/base/carousel/hooks/use-carousel-position.ts

@@ -0,0 +1,52 @@
+import { useCallback, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+
+import { CAROUSEL_ANIMATION_DURATION } from '../constants';
+
+/**
+ * 轮播图位置和动画控制 Hook
+ *
+ * 管理轮播图的位置状态和动画执行，提供平滑的动画过渡和即时位置设置功能。
+ * 使用 Animated.Value 实现原生驱动的动画，确保流畅的性能。
+ *
+ * @returns Hook 返回值
+ * @returns position - Animated.Value 位置引用，用于动画变换
+ * @returns positionValueRef - 当前位置值的引用，用于同步读取位置
+ * @returns animateTo - 执行动画到指定位置的方法
+ * @returns setPositionImmediate - 立即设置位置（无动画）的方法
+ */
+export const useCarouselPosition = () => {
+  const position = useRef(new Animated.Value(0));
+  const positionValueRef = useRef(0);
+
+  const animateTo = useCallback((toValue: number, onFinished?: () => void) => {
+    const listenerId = position.current.addListener(({ value }) => {
+      positionValueRef.current = value;
+    });
+    Animated.timing(position.current, {
+      toValue,
+      duration: CAROUSEL_ANIMATION_DURATION,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start(({ finished }) => {
+      position.current.removeListener(listenerId);
+      if (finished) {
+        positionValueRef.current = toValue;
+        onFinished?.();
+      }
+    });
+  }, []);
+
+  const setPositionImmediate = useCallback((toValue: number) => {
+    position.current.stopAnimation();
+    position.current.setValue(toValue);
+    positionValueRef.current = toValue;
+  }, []);
+
+  return {
+    position,
+    positionValueRef,
+    animateTo,
+    setPositionImmediate,
+  };
+};