@seakoi/native-ui 1.1.0 → 1.1.1

package/dist/module/components/base/carousel/hooks/use-carousel-autoplay.js

@@ -0,0 +1,42 @@
+"use strict";
+
+import { useEffect } from 'react';
+/**
+ * 轮播图自动轮播 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 => {
+  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/dist/module/components/base/carousel/hooks/use-carousel-index.js

@@ -0,0 +1,124 @@
+"use strict";
+
+import { useMemoizedFn } from 'ahooks';
+import { clamp } from 'lodash-es';
+import { useCallback, useRef, useState } from 'react';
+import { RUBBERBAND_DAMPING } from "../constants.js";
+import { getBoundaryIndexRange } from "../utils.js";
+/**
+ * 轮播图索引管理 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 => {
+  const {
+    total,
+    loopEnabled,
+    clonesBefore,
+    slidePixels,
+    normalizedSlideSize,
+    normalizedTrackOffset,
+    stuckAtBoundary,
+    rubberband,
+    onIndexChange
+  } = params;
+  const [current, setCurrent] = useState(0);
+  const extIndexRef = useRef(0);
+  const reportIndexRef = useRef(null);
+  const updateCurrent = useCallback(next => {
+    const normalized = total > 0 ? clamp(next, 0, total - 1) : 0;
+    setCurrent(normalized);
+  }, [total]);
+  const maybeReportIndex = useMemoizedFn(index => {
+    if (!onIndexChange) return;
+    if (reportIndexRef.current === index) return;
+    reportIndexRef.current = index;
+    onIndexChange(index);
+  });
+  const getExtIndexFromIndex = useCallback(index => {
+    if (!loopEnabled) return index;
+    return clamp(index, 0, total - 1) + clonesBefore;
+  }, [clonesBefore, loopEnabled, total]);
+  const getIndexFromExtIndex = useCallback(extIndex => {
+    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 => {
+    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 => {
+    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/dist/module/components/base/carousel/hooks/use-carousel-indicator.js

@@ -0,0 +1,58 @@
+"use strict";
+
+import { useMemoizedFn } from 'ahooks';
+import { StyleSheet, View } from 'react-native';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 轮播图指示器渲染 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 => {
+  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 /*#__PURE__*/_jsx(View, {
+      style: StyleSheet.flatten([styles.indicatorContainer, indicatorProps?.style]),
+      children: Array.from({
+        length: total
+      }, (_, i) => {
+        const isActive = i === current;
+        return /*#__PURE__*/_jsx(View, {
+          style: StyleSheet.flatten([styles.indicatorDot, {
+            backgroundColor: isActive ? dotActiveColor : inactiveColor
+          }, isActive && styles.indicatorDotActive])
+        }, i);
+      })
+    });
+  });
+  return {
+    renderIndicator
+  };
+};

package/dist/module/components/base/carousel/hooks/use-carousel-lifecycle.js

@@ -0,0 +1,62 @@
+"use strict";
+
+import { clamp } from 'lodash-es';
+import { useEffect } from 'react';
+/**
+ * 轮播图生命周期管理 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 => {
+  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/dist/module/components/base/carousel/hooks/use-carousel-pan-responder.js

@@ -0,0 +1,118 @@
+"use strict";
+
+import { clamp } from 'lodash-es';
+import { useMemo } from 'react';
+import { PanResponder } from 'react-native';
+import { GESTURE_MIN_DISTANCE, VELOCITY_PROJECTION_FACTOR } from "../constants.js";
+/**
+ * 轮播图手势响应 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 => {
+  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 = (_, gestureState) => {
+      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/dist/module/components/base/carousel/hooks/use-carousel-position.js

@@ -0,0 +1,54 @@
+"use strict";
+
+import { useCallback, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { CAROUSEL_ANIMATION_DURATION } from "../constants.js";
+
+/**
+ * 轮播图位置和动画控制 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, onFinished) => {
+    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 => {
+    position.current.stopAnimation();
+    position.current.setValue(toValue);
+    positionValueRef.current = toValue;
+  }, []);
+  return {
+    position,
+    positionValueRef,
+    animateTo,
+    setPositionImmediate
+  };
+};

package/dist/module/components/base/carousel/hooks/use-carousel-slides.js

@@ -0,0 +1,90 @@
+"use strict";
+
+import { useMemoizedFn } from 'ahooks';
+import { clamp } from 'lodash-es';
+import { useMemo } from 'react';
+import { View } from 'react-native';
+import { isRenderPropChildren, normalizeChildren } from "../utils.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 轮播图滑块渲染 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 => {
+  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 => {
+    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 => {
+      const logicalIndex = loopEnabled ? getIndexFromExtIndex(extIndex) : clamp(extIndex, 0, total - 1);
+      if (isRenderPropChildren(children)) return children(logicalIndex);
+      return staticSlides[logicalIndex];
+    };
+    const slideElements = [];
+    for (let extIndex = start; extIndex <= end; extIndex += 1) {
+      const element = getElementForExtIndex(extIndex);
+      if (!element) continue;
+      slideElements.push(/*#__PURE__*/_jsx(View, {
+        style: [slideStyles.slide, slideWrapperStyle],
+        children: element
+      }, extIndex));
+    }
+    const leadSpacer = isVirtual && spacerStyles && spacerStyles.leadingSize > 0 ? /*#__PURE__*/_jsx(View, {
+      style: spacerStyles.leading
+    }) : null;
+    const trailSpacer = isVirtual && spacerStyles && spacerStyles.trailingSize > 0 ? /*#__PURE__*/_jsx(View, {
+      style: spacerStyles.trailing
+    }) : null;
+    return /*#__PURE__*/_jsxs(_Fragment, {
+      children: [leadSpacer, slideElements, trailSpacer]
+    });
+  });
+  return {
+    staticSlides,
+    renderSlides
+  };
+};

package/dist/module/components/base/carousel/hooks/use-carousel-swipe.js

@@ -0,0 +1,135 @@
+"use strict";
+
+import { useMemoizedFn } from 'ahooks';
+import { clamp } from 'lodash-es';
+import { useImperativeHandle } from 'react';
+/**
+ * 轮播图切换逻辑 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 => {
+  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 => {
+    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 => {
+    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
+  };
+};