@seakoi/native-ui 1.0.0 → 1.1.1

package/src/components/base/carousel/carousel.tsx

@@ -0,0 +1,361 @@
+import { clamp } from 'lodash-es';
+import React, { useCallback, useMemo, useState } from 'react';
+import {
+  Animated,
+  type LayoutChangeEvent,
+  type StyleProp,
+  StyleSheet,
+  View,
+  type ViewStyle,
+} from 'react-native';
+
+import { useTheme } from '#native-provider';
+
+import {
+  useCarouselAutoplay,
+  useCarouselIndex,
+  useCarouselIndicator,
+  useCarouselLifecycle,
+  useCarouselPanResponder,
+  useCarouselPosition,
+  useCarouselSlides,
+  useCarouselSwipe,
+} from './hooks';
+import { useCarouselStyles } from './style';
+import type { CarouselProps } from './types';
+import { getDefaultTotal, isRenderPropChildren } from './utils';
+
+interface LayoutState {
+  width: number;
+  height: number;
+}
+
+/**
+ * 轮播图组件
+ *
+ * 支持水平/垂直滑动、循环播放、自动轮播、虚拟渲染等功能的高性能轮播组件。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <Carousel>
+ *   <Carousel.Item><View /></Carousel.Item>
+ *   <Carousel.Item><View /></Carousel.Item>
+ * </Carousel>
+ *
+ * // 循环播放和自动轮播
+ * <Carousel loop autoplay autoplayInterval={3000}>
+ *   {items.map(item => <Carousel.Item key={item.id}>{item.content}</Carousel.Item>)}
+ * </Carousel>
+ *
+ * // 虚拟渲染（大量数据）
+ * <Carousel total={1000}>
+ *   {(index) => <Carousel.Item><Text>{index}</Text></Carousel.Item>}
+ * </Carousel>
+ * ```
+ *
+ * @param props - 组件属性
+ * @returns 轮播图组件
+ */
+export const Carousel = (props: CarouselProps) => {
+  const {
+    defaultIndex = 0,
+    allowTouchMove = true,
+    autoplay = false,
+    autoplayInterval = 3000,
+    loop = false,
+    direction = 'horizontal',
+    onIndexChange,
+    indicatorProps,
+    indicator,
+    slideSize = 100,
+    trackOffset = 0,
+    stuckAtBoundary = true,
+    rubberband = true,
+    virtualOverscan = 2,
+    total: totalProp,
+    children,
+    style,
+    blockNativeResponder = true,
+    ref,
+  } = props;
+
+  const styles = useCarouselStyles();
+  const theme = useTheme();
+
+  const [layout, setLayout] = useState<LayoutState>({ width: 0, height: 0 });
+  const [dragging, setDragging] = useState(false);
+  const [animating, setAnimating] = useState(false);
+
+  const normalizedSlideSize = useMemo(() => {
+    if (!Number.isFinite(slideSize)) return 100;
+    return clamp(slideSize, 0, 100);
+  }, [slideSize]);
+
+  const normalizedTrackOffset = useMemo(() => {
+    if (stuckAtBoundary) {
+      return 100 - normalizedSlideSize;
+    }
+    if (!Number.isFinite(trackOffset)) return 0;
+    return clamp(trackOffset, 0, 100 - normalizedSlideSize);
+  }, [normalizedSlideSize, trackOffset, stuckAtBoundary]);
+
+  const total = useMemo(() => {
+    const normalizedDefault = getDefaultTotal(children);
+    return totalProp ?? normalizedDefault;
+  }, [children, totalProp]);
+
+  const loopEnabled = loop && total > 1;
+
+  // 计算循环播放时需要克隆的前置节点数量
+  // 若是非全屏的轮播项，则在循环播放开启的情况下，则会在下一轮展示第一项时看见下一项为空白（或闪烁），这需要额外渲染更多的项（与offset、slideSize相关）
+  const clonesBefore = useMemo(() => {
+    if (!loopEnabled) return 0;
+    if (normalizedSlideSize <= 0) return 1;
+
+    const offsetSlides = Math.ceil(normalizedTrackOffset / normalizedSlideSize);
+    return Math.max(1, offsetSlides + 1);
+  }, [loopEnabled, normalizedSlideSize, normalizedTrackOffset]);
+
+  // 计算循环播放时需要克隆的后置节点数量
+  const clonesAfter = useMemo(() => {
+    if (!loopEnabled) return 0;
+    if (normalizedSlideSize <= 0) return 1;
+
+    const remainingSpace = 100 - normalizedTrackOffset - normalizedSlideSize;
+    const trailingSlides = Math.ceil(remainingSpace / normalizedSlideSize);
+    return Math.max(1, trailingSlides + 1);
+  }, [loopEnabled, normalizedSlideSize, normalizedTrackOffset]);
+
+  const extTotal = loopEnabled ? total + clonesBefore + clonesAfter : total;
+
+  const slidePixels = useMemo(() => {
+    const trackSize = direction === 'horizontal' ? layout.width : layout.height;
+    if (trackSize <= 0) return 0;
+    return trackSize * (normalizedSlideSize / 100);
+  }, [direction, layout.height, layout.width, normalizedSlideSize]);
+
+  const trackOffsetPixels = useMemo(() => {
+    const trackSize = direction === 'horizontal' ? layout.width : layout.height;
+    if (trackSize <= 0) return 0;
+    return trackSize * (normalizedTrackOffset / 100);
+  }, [direction, layout.height, layout.width, normalizedTrackOffset]);
+
+  const {
+    current,
+    updateCurrent,
+    extIndexRef,
+    reportIndexRef,
+    maybeReportIndex,
+    getExtIndexFromIndex,
+    getIndexFromExtIndex,
+    getTargetExtIndexForIndex,
+    getBoundedPosition,
+  } = useCarouselIndex({
+    total,
+    loopEnabled,
+    clonesBefore,
+    slidePixels,
+    normalizedSlideSize,
+    normalizedTrackOffset,
+    stuckAtBoundary,
+    rubberband,
+    onIndexChange,
+  });
+
+  // 位置和动画控制
+  const { position, positionValueRef, animateTo, setPositionImmediate } =
+    useCarouselPosition();
+
+  // 切换逻辑
+  const { swipeNext, swipePrev, swipeToExtIndex } = useCarouselSwipe({
+    total,
+    loopEnabled,
+    clonesBefore,
+    slidePixels,
+    extTotal,
+    extIndexRef,
+    getBoundedPosition,
+    getIndexFromExtIndex,
+    getTargetExtIndexForIndex,
+    updateCurrent,
+    maybeReportIndex,
+    setAnimating,
+    animateTo,
+    setPositionImmediate,
+    ref,
+  });
+
+  // 自动轮播
+  useCarouselAutoplay({
+    autoplay,
+    autoplayInterval,
+    total,
+    dragging,
+    current,
+    swipeNext,
+    swipePrev,
+  });
+
+  // 生命周期管理
+  useCarouselLifecycle({
+    total,
+    defaultIndex,
+    slidePixels,
+    extIndexRef,
+    reportIndexRef,
+    getExtIndexFromIndex,
+    getBoundedPosition,
+    updateCurrent,
+    setPositionImmediate,
+  });
+
+  const onLayoutTrack = useCallback((e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout;
+    setLayout(prev => {
+      if (prev.width === width && prev.height === height) return prev;
+      return { width, height };
+    });
+  }, []);
+
+  const panResponder = useCarouselPanResponder({
+    allowTouchMove,
+    total,
+    slidePixels,
+    direction,
+    extTotal,
+    clonesBefore,
+    blockNativeResponder,
+    position,
+    positionValueRef,
+    extIndexRef,
+    setDragging,
+    setAnimating,
+    updateCurrent,
+    getIndexFromExtIndex,
+    getBoundedPosition,
+    swipeToExtIndex,
+  });
+
+  const trackTransformStyle: StyleProp<ViewStyle> = useMemo(() => {
+    const translate = Animated.add(
+      Animated.multiply(position.current, -1),
+      trackOffsetPixels,
+    );
+    return direction === 'horizontal'
+      ? { transform: [{ translateX: translate }] }
+      : { transform: [{ translateY: translate }] };
+  }, [direction, position, trackOffsetPixels]);
+
+  // 计算虚拟渲染的范围
+  // 注意: extIndexRef 的变化不会触发重新计算，
+  // 通过 dragging 和 animating 状态的变化来触发虚拟范围的更新
+  const virtualRange = useMemo(() => {
+    if (total <= 0 || slidePixels <= 0) {
+      return null;
+    }
+
+    const isVirtual =
+      isRenderPropChildren(children) && typeof totalProp === 'number';
+    const effectiveOverscan = isVirtual
+      ? Math.max(virtualOverscan, dragging || animating ? 1 : 0)
+      : virtualOverscan;
+
+    const currentExtIndex = extIndexRef.current;
+    const start = isVirtual
+      ? clamp(currentExtIndex - effectiveOverscan, 0, extTotal - 1)
+      : 0;
+    const end = isVirtual
+      ? clamp(currentExtIndex + effectiveOverscan, 0, extTotal - 1)
+      : extTotal - 1;
+
+    return { start, end, isVirtual };
+  }, [
+    total,
+    slidePixels,
+    children,
+    totalProp,
+    virtualOverscan,
+    dragging,
+    animating,
+    extIndexRef, // 保留以表明依赖关系，虽然不会触发更新
+    extTotal,
+  ]);
+
+  // 计算滑块包装器样式
+  const slideWrapperStyle: ViewStyle = useMemo(() => {
+    return direction === 'horizontal'
+      ? { width: slidePixels, height: '100%' }
+      : { height: slidePixels, width: '100%' };
+  }, [direction, slidePixels]);
+
+  // 计算虚拟渲染的占位空间样式
+  const spacerStyles = useMemo(() => {
+    if (!virtualRange) return null;
+
+    const { start, end } = virtualRange;
+    const leadingSize = start * slidePixels;
+    const trailingSize = (extTotal - end - 1) * slidePixels;
+
+    return {
+      leading:
+        direction === 'horizontal'
+          ? { width: leadingSize }
+          : { height: leadingSize },
+      trailing:
+        direction === 'horizontal'
+          ? { width: trailingSize }
+          : { height: trailingSize },
+      leadingSize,
+      trailingSize,
+    };
+  }, [virtualRange, slidePixels, extTotal, direction]);
+
+  const { renderSlides } = useCarouselSlides({
+    children,
+    total,
+    virtualRange,
+    loopEnabled,
+    clonesBefore,
+    slideWrapperStyle,
+    spacerStyles,
+    slideStyles: styles,
+  });
+
+  const { renderIndicator } = useCarouselIndicator({
+    indicator,
+    indicatorProps,
+    total,
+    current,
+    activeColor: theme.palette.brand7,
+    inactiveColor: theme.palette.fontGray5,
+    styles,
+  });
+
+  const trackInnerStyle: ViewStyle = useMemo(() => {
+    return direction === 'horizontal'
+      ? { flexDirection: 'row', height: '100%' }
+      : { flexDirection: 'column', width: '100%' };
+  }, [direction]);
+
+  return (
+    <View style={StyleSheet.flatten([styles.container, style])}>
+      <View
+        style={styles.track}
+        onLayout={onLayoutTrack}
+        {...panResponder?.panHandlers}
+      >
+        <Animated.View
+          style={StyleSheet.flatten([
+            styles.trackInner,
+            trackInnerStyle,
+            trackTransformStyle,
+          ])}
+        >
+          {renderSlides()}
+        </Animated.View>
+        {renderIndicator()}
+      </View>
+    </View>
+  );
+};

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