@seakoi/native-ui 1.0.0 → 1.1.1

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,
+  };
+};

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

@@ -0,0 +1,131 @@
+import { useMemoizedFn } from 'ahooks';
+import { clamp } from 'lodash-es';
+import { type ReactElement, useMemo } from 'react';
+import { View, type ViewStyle } from 'react-native';
+
+import type { CarouselItemProps } from '../types';
+import { isRenderPropChildren, normalizeChildren } from '../utils';
+
+interface UseCarouselSlidesParams {
+  children:
+    | ReactElement<CarouselItemProps>
+    | ReactElement<CarouselItemProps>[]
+    | ((index: number) => ReactElement<CarouselItemProps>)
+    | undefined;
+  total: number;
+  virtualRange: {
+    start: number;
+    end: number;
+    isVirtual: boolean;
+  } | null;
+  loopEnabled: boolean;
+  clonesBefore: number;
+  slideWrapperStyle: ViewStyle;
+  spacerStyles: {
+    leading: ViewStyle;
+    trailing: ViewStyle;
+    leadingSize: number;
+    trailingSize: number;
+  } | null;
+  slideStyles: {
+    slide: ViewStyle;
+  };
+}
+
+/**
+ * 轮播图滑块渲染 Hook
+ *
+ * 负责渲染轮播图的滑块内容，支持静态子组件和 render prop 两种方式。
+ * 实现虚拟渲染优化，仅渲染可见范围内的滑块，并处理循环播放时的克隆逻辑。
+ * 为虚拟渲染添加前后占位空间，确保滚动位置正确。
+ *
+ * @param params - Hook 参数配置
+ * @param params.children - 轮播项内容（静态子组件或 render prop 函数）
+ * @param params.total - 轮播项总数
+ * @param params.virtualRange - 虚拟渲染范围（start、end、isVirtual）
+ * @param params.loopEnabled - 是否启用循环播放
+ * @param params.clonesBefore - 循环播放时前置克隆节点数量
+ * @param params.slideWrapperStyle - 滑块包装器样式
+ * @param params.spacerStyles - 虚拟渲染占位空间样式
+ * @param params.slideStyles - 滑块样式对象
+ *
+ * @returns Hook 返回值
+ * @returns staticSlides - 静态滑块数组（仅在非 render prop 模式下有值）
+ * @returns renderSlides - 渲染滑块的方法，返回 ReactNode 或 null
+ */
+export const useCarouselSlides = (params: UseCarouselSlidesParams) => {
+  const {
+    children,
+    total,
+    virtualRange,
+    loopEnabled,
+    clonesBefore,
+    slideWrapperStyle,
+    spacerStyles,
+    slideStyles,
+  } = params;
+
+  const staticSlides = useMemo(() => {
+    if (isRenderPropChildren(children)) return [];
+    return normalizeChildren(children, total);
+  }, [children, total]);
+
+  const getIndexFromExtIndex = useMemoizedFn((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;
+  });
+
+  const renderSlides = useMemoizedFn(() => {
+    if (!virtualRange) return null;
+
+    const { start, end, isVirtual } = virtualRange;
+
+    const getElementForExtIndex = (extIndex: number) => {
+      const logicalIndex = loopEnabled
+        ? getIndexFromExtIndex(extIndex)
+        : clamp(extIndex, 0, total - 1);
+
+      if (isRenderPropChildren(children)) return children(logicalIndex);
+      return staticSlides[logicalIndex];
+    };
+
+    const slideElements: ReactElement[] = [];
+    for (let extIndex = start; extIndex <= end; extIndex += 1) {
+      const element = getElementForExtIndex(extIndex);
+      if (!element) continue;
+      slideElements.push(
+        <View key={extIndex} style={[slideStyles.slide, slideWrapperStyle]}>
+          {element}
+        </View>,
+      );
+    }
+
+    const leadSpacer =
+      isVirtual && spacerStyles && spacerStyles.leadingSize > 0 ? (
+        <View style={spacerStyles.leading} />
+      ) : null;
+    const trailSpacer =
+      isVirtual && spacerStyles && spacerStyles.trailingSize > 0 ? (
+        <View style={spacerStyles.trailing} />
+      ) : null;
+
+    return (
+      <>
+        {leadSpacer}
+        {slideElements}
+        {trailSpacer}
+      </>
+    );
+  });
+
+  return {
+    staticSlides,
+    renderSlides,
+  };
+};

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

@@ -0,0 +1,171 @@
+import { useMemoizedFn } from 'ahooks';
+import { clamp } from 'lodash-es';
+import { type RefObject, useImperativeHandle } from 'react';
+
+interface UseCarouselSwipeParams {
+  total: number;
+  loopEnabled: boolean;
+  clonesBefore: number;
+  slidePixels: number;
+  extTotal: number;
+  extIndexRef: RefObject<number>;
+  getBoundedPosition: (position: number) => number;
+  getIndexFromExtIndex: (extIndex: number) => number;
+  getTargetExtIndexForIndex: (targetIndex: number) => number;
+  updateCurrent: (index: number) => void;
+  maybeReportIndex: (index: number) => void;
+  setAnimating: (animating: boolean) => void;
+  animateTo: (toValue: number, onFinished?: () => void) => void;
+  setPositionImmediate: (toValue: number) => void;
+  ref?: React.Ref<{
+    swipeTo: (index: number) => void;
+    swipeNext: () => void;
+    swipePrev: () => void;
+  }>;
+}
+
+/**
+ * 轮播图切换逻辑 Hook
+ *
+ * 实现轮播图的切换功能，包括切换到指定索引、下一项、上一项。
+ * 处理循环播放时的边界无缝跳转，确保视觉上的连续性。
+ * 通过 ref 暴露切换方法供外部调用。
+ *
+ * @param params - Hook 参数配置
+ * @param params.total - 轮播项总数
+ * @param params.loopEnabled - 是否启用循环播放
+ * @param params.clonesBefore - 循环播放时前置克隆节点数量
+ * @param params.slidePixels - 单个滑块的像素大小
+ * @param params.extTotal - 扩展总数（包含克隆项）
+ * @param params.extIndexRef - 扩展索引的引用
+ * @param params.getBoundedPosition - 获取边界限制后的位置
+ * @param params.getIndexFromExtIndex - 从扩展索引获取逻辑索引
+ * @param params.getTargetExtIndexForIndex - 获取目标扩展索引
+ * @param params.updateCurrent - 更新当前索引
+ * @param params.maybeReportIndex - 可能触发索引变化回调
+ * @param params.setAnimating - 设置动画状态
+ * @param params.animateTo - 执行动画到指定位置
+ * @param params.setPositionImmediate - 立即设置位置
+ * @param params.ref - 组件 ref，用于暴露实例方法
+ *
+ * @returns Hook 返回值
+ * @returns swipeTo - 切换到指定索引的方法
+ * @returns swipeNext - 切换到下一项的方法
+ * @returns swipePrev - 切换到上一项的方法
+ * @returns swipeToExtIndex - 切换到扩展索引的方法
+ * @returns finalizeLoopJumpIfNeeded - 完成循环边界跳转的方法
+ */
+export const useCarouselSwipe = (params: UseCarouselSwipeParams) => {
+  const {
+    total,
+    loopEnabled,
+    clonesBefore,
+    slidePixels,
+    extTotal,
+    extIndexRef,
+    getBoundedPosition,
+    getIndexFromExtIndex,
+    getTargetExtIndexForIndex,
+    updateCurrent,
+    maybeReportIndex,
+    setAnimating,
+    animateTo,
+    setPositionImmediate,
+    ref,
+  } = params;
+
+  const finalizeLoopJumpIfNeeded = useMemoizedFn(() => {
+    if (!loopEnabled) return;
+    const currentExt = extIndexRef.current;
+    if (currentExt < clonesBefore) {
+      const targetExt = currentExt + total;
+      extIndexRef.current = targetExt;
+      if (slidePixels > 0) setPositionImmediate(targetExt * slidePixels);
+      return;
+    }
+    if (currentExt >= clonesBefore + total) {
+      const targetExt = currentExt - total;
+      extIndexRef.current = targetExt;
+      if (slidePixels > 0) setPositionImmediate(targetExt * slidePixels);
+    }
+  });
+
+  const swipeToExtIndex = useMemoizedFn((targetExtIndex: number) => {
+    if (total <= 0) return;
+    if (slidePixels <= 0) {
+      extIndexRef.current = clamp(targetExtIndex, 0, extTotal - 1);
+      setAnimating(false);
+      updateCurrent(getIndexFromExtIndex(extIndexRef.current));
+      return;
+    }
+
+    const boundedExtIndex = clamp(targetExtIndex, 0, extTotal - 1);
+    extIndexRef.current = boundedExtIndex;
+
+    const nextIndex = getIndexFromExtIndex(boundedExtIndex);
+    updateCurrent(nextIndex);
+
+    const rawPosition = boundedExtIndex * slidePixels;
+    const toPosition = getBoundedPosition(rawPosition);
+
+    setAnimating(true);
+    animateTo(toPosition, () => {
+      finalizeLoopJumpIfNeeded();
+      const normalizedIndex = getIndexFromExtIndex(extIndexRef.current);
+      updateCurrent(normalizedIndex);
+      maybeReportIndex(normalizedIndex);
+      setAnimating(false);
+    });
+  });
+
+  const swipeTo = useMemoizedFn((index: number) => {
+    if (total <= 0) return;
+    const targetIndex = clamp(Math.round(index), 0, total - 1);
+    const targetExtIndex = getTargetExtIndexForIndex(targetIndex);
+    swipeToExtIndex(targetExtIndex);
+  });
+
+  const swipeNext = useMemoizedFn(() => {
+    if (total <= 1) return;
+    let currentExt = extIndexRef.current;
+    // 若当前处于 after-clone 区域（快速连击导致 finalizeLoopJumpIfNeeded 尚未执行），
+    // 立即将位置平移回真实 item 区域（视觉内容相同，不可感知），再继续前进
+    if (clonesBefore > 0 && currentExt >= clonesBefore + total) {
+      currentExt -= total;
+      extIndexRef.current = currentExt;
+      if (slidePixels > 0) setPositionImmediate(currentExt * slidePixels);
+    }
+    swipeToExtIndex(currentExt + 1);
+  });
+
+  const swipePrev = useMemoizedFn(() => {
+    if (total <= 1) return;
+    let currentExt = extIndexRef.current;
+    // 若当前处于 before-clone 区域（快速连击导致 finalizeLoopJumpIfNeeded 尚未执行），
+    // 立即将位置平移回真实 item 区域（视觉内容相同，不可感知），再继续后退
+    if (clonesBefore > 0 && currentExt < clonesBefore) {
+      currentExt += total;
+      extIndexRef.current = currentExt;
+      if (slidePixels > 0) setPositionImmediate(currentExt * slidePixels);
+    }
+    swipeToExtIndex(currentExt - 1);
+  });
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      swipeTo,
+      swipeNext,
+      swipePrev,
+    }),
+    [swipeNext, swipePrev, swipeTo],
+  );
+
+  return {
+    swipeTo,
+    swipeNext,
+    swipePrev,
+    swipeToExtIndex,
+    finalizeLoopJumpIfNeeded,
+  };
+};

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

@@ -0,0 +1,8 @@
+import { Carousel as _Carousel } from './carousel';
+import { CarouselItem } from './carousel-item';
+
+export * from './carousel';
+export * from './carousel-item';
+export type * from './types';
+
+export const Carousel = Object.assign(_Carousel, { Item: CarouselItem });

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

@@ -0,0 +1,44 @@
+import { createThemedStyles } from '#native-provider';
+
+const INDICATOR_DOT_SIZE = 6;
+
+export const useCarouselStyles = createThemedStyles(theme => ({
+  container: {
+    overflow: 'hidden',
+    height: '100%',
+    width: '100%',
+  },
+  track: {
+    flex: 1,
+    overflow: 'hidden',
+  },
+  trackInner: {
+    flexGrow: 0,
+    flexShrink: 0,
+  },
+  slide: {
+    flexGrow: 0,
+    flexShrink: 0,
+    overflow: 'hidden',
+  },
+  indicatorContainer: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    bottom: theme.spacing.sm,
+    flexDirection: 'row',
+    justifyContent: 'center',
+    alignItems: 'center',
+    gap: theme.spacing.xs,
+  },
+  indicatorDot: {
+    width: INDICATOR_DOT_SIZE,
+    height: INDICATOR_DOT_SIZE,
+    borderRadius: theme.roundness.full,
+    backgroundColor: theme.palette.fontGray5,
+    opacity: 0.6,
+  },
+  indicatorDotActive: {
+    opacity: 1,
+  },
+}));